ipfs-log/docs/index.html at main · orbitdb-archive/ipfs-log · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Home</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Home</h1>


    <h3> </h3>


    <section>
        <article><h1>ipfs-log</h1>
<p><a href="https://www.npmjs.com/package/ipfs-log"><img src="https://img.shields.io/npm/v/ipfs-log.svg" alt="npm"></a>
<a href="https://circleci.com/gh/orbitdb/ipfs-log"><img src="https://circleci.com/gh/orbitdb/ipfs-log.svg?style=shield" alt="CircleCI Status"></a>
<a href="https://gitter.im/orbitdb/Lobby"><img src="https://img.shields.io/gitter/room/nwjs/nw.js.svg" alt="Gitter"></a> <a href="https://riot.permaweb.io/#/room/#orbitdb:permaweb.io"><img src="https://img.shields.io/badge/matrix-%23orbitdb%3Apermaweb.io-blue.svg" alt="Matrix"></a> <a href="https://discord.gg/cscuf5T"><img src="https://img.shields.io/discord/475789330380488707?color=blueviolet&amp;label=discord" alt="Discord"></a></p>
<blockquote>
<p>An append-only log on IPFS.</p>
</blockquote>
<p><code>ipfs-log</code> is an immutable, operation-based conflict-free replicated data structure (<a href="https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type">CRDT</a>) for distributed systems. It's an append-only log that can be used to model a mutable, shared state between peers in p2p applications.</p>
<p>Every entry in the log is saved in IPFS and each points to a hash of previous entry(ies) forming a graph. Logs can be forked and joined back together.</p>
<p>The module works in <strong>Node.js</strong> and <strong>Browsers</strong>.</p>
<pre class="prettyprint source"><code>           Log A                Log B
             |                    |
     logA.append(&quot;one&quot;)   logB.append(&quot;hello&quot;)
             |                    |
             v                    v
          +-----+             +-------+
          |&quot;one&quot;|             |&quot;hello&quot;|
          +-----+             +-------+
             |                    |
     logA.append(&quot;two&quot;)   logB.append(&quot;world&quot;)
             |                    |
             v                    v
       +-----------+       +---------------+
       |&quot;one&quot;,&quot;two&quot;|       |&quot;hello&quot;,&quot;world&quot;|
       +-----------+       +---------------+
             |                    |
             |                    |
       logA.join(logB) &lt;----------+
             |
             v
+---------------------------+
|&quot;one&quot;,&quot;hello&quot;,&quot;two&quot;,&quot;world&quot;|
+---------------------------+
</code></pre>
<h2>Table of Contents</h2>
<ul>
<li><a href="#background">Background</a></li>
<li><a href="#install">Install</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#api">API</a></li>
<li><a href="#tests">Tests</a></li>
<li><a href="#benchmarking">Benchmarking</a></li>
<li><a href="#build">Build</a></li>
<li><a href="#contribute">Contribute</a></li>
<li><a href="#license">License</a></li>
</ul>
<h2>Background</h2>
<p>IPFS Log has a few use cases:</p>
<ul>
<li>CRDTs</li>
<li>Database operations log</li>
<li>Feed of data</li>
<li>Track a version of a file</li>
<li>Messaging</li>
</ul>
<p>It was originally created for, and currently used in, <a href="https://github.com/orbitdb/orbit-db">orbit-db</a> - a distributed peer-to-peer database on <a href="https://github.com/ipfs/ipfs">IPFS</a>.</p>
<h2>Requirements</h2>
<ul>
<li>Node.js v8.6.0 or newer (uses <code>...</code> spread syntax)</li>
<li>Preferably you should use an LTS version of node.js (even numbered 8, 10, etc)</li>
</ul>
<h2>Install</h2>
<p>This project uses <a href="http://npmjs.com/">npm</a> and <a href="https://nodejs.org/">nodejs</a>.</p>
<pre class="prettyprint source"><code>npm install ipfs-log
</code></pre>
<h2>Usage</h2>
<p>See the <a href="#api">API documentation</a> and <a href="https://github.com/orbitdb/ipfs-log/tree/master/examples">examples</a> for more details.</p>
<h3>Quick Start</h3>
<p>Install dependencies:</p>
<pre class="prettyprint source"><code>npm install ipfs-log ipfs
</code></pre>
<p>Run a simple program:</p>
<pre class="prettyprint source lang-javascript"><code>
// For js-ipfs >= 0.38

const Log = require(&quot;ipfs-log&quot;);
const IdentityProvider = require(&quot;orbit-db-identity-provider&quot;);
const IPFS = require(&quot;ipfs&quot;);

const start = async () => {
  const identity = await IdentityProvider.createIdentity({ id: &quot;peerid&quot; });
  const ipfs = await IPFS.create({ repo: &quot;./path-for-js-ipfs-repo&quot; });
  const log = new Log(ipfs, identity);

  await log.append({ some: &quot;data&quot; });
  await log.append(&quot;text&quot;);
  console.log(log.values.map((e) => e.payload));
};

start();

// [ { some: 'data' }, 'text' ]
</code></pre>
<h3>Node.js</h3>
<p>See <a href="https://github.com/orbitdb/ipfs-log/tree/master/examples">examples</a> for details.</p>
<p><em>If your platforms requires ES5-compatible JavaScript, there's a build in <code>lib/es5/</code>.</em></p>
<h3>Browser</h3>
<p>See <a href="https://github.com/orbitdb/ipfs-log/tree/master/examples/browser">examples/browser</a> for details.</p>
<p><em>The distribution package for browsers is located in <a href="https://github.com/orbitdb/ipfs-log/tree/master/dist">dist/ipfslog.min.js</a></em></p>
<p><em>If your platforms requires ES5-compatible JavaScript, there's a build in <code>lib/es5/</code>.</em></p>
<h2>API</h2>
<p>See <a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md">API Documentation</a> for full details.</p>
<ul>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md#log">Log</a>
<ul>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##constructor">Constructor</a>
<ul>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##new-log-ipfs-id">new Log(ipfs, identity, [{ logId, access, entries, heads, clock, sortFn }])</a></li>
</ul>
</li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##properties">Properties</a>
<ul>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##id">id</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##values">values</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##length">length</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##length">clock</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##heads">heads</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##tails">tails</a></li>
</ul>
</li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##methods">Methods</a>
<ul>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##appenddata">append(data)</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##joinlog">join(log)</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##tomultihash">toMultihash()</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##tobuffer">toBuffer()</a></li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##toString">toString()</a></li>
</ul>
</li>
<li><a href="https://github.com/orbitdb/ipfs-log/tree/master/API.md##static-methods">Static Methods</a>
<ul>
<li><a href="">Log.fromEntry()</a></li>
<li><a href="">Log.fromEntryCid()</a></li>
<li><a href="">Log.fromCID()</a></li>
<li><a href="">Log.fromMultihash()</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h2>Tests</h2>
<p>Run all tests:</p>
<pre class="prettyprint source"><code>npm test
</code></pre>
<p>Run tests with js-ipfs only (default):</p>
<pre class="prettyprint source"><code>mocha
</code></pre>
<p>Run tests with go-ipfs only:</p>
<pre class="prettyprint source"><code>TEST=go mocha
</code></pre>
<h2>Benchmarking</h2>
<p>To use the benchmark runner:</p>
<pre class="prettyprint source lang-JavaScript"><code>node --expose-gc benchmarks/runner/index.js -r --grep append-stress --stress-limit Infinity
</code></pre>
<p>This will run the <code>append-stress</code> benchmarks until it is canceled. For more information, see the <a href="./benchmarks/README.md">Benchmarking README</a>.</p>
<h2>Build</h2>
<p>Run the following command before you commit.</p>
<pre class="prettyprint source"><code>make rebuild
</code></pre>
<p>This will ensure that dependencies and built files are all based on the current code base.</p>
<h2>Benchmarks</h2>
<p>There's a benchmark suite in <a href="https://github.com/orbitdb/ipfs-log/blob/master/benchmarks">benchmarks/</a> that can be run with:</p>
<pre class="prettyprint source"><code>node benchmarks/benchmark-append.js
node benchmarks/benchmark-join.js
node benchmarks/benchmark-expand.js
</code></pre>
<p>There's <code>append</code> and <code>join</code> benchmarks for browsers in <a href="https://github.com/orbitdb/ipfs-log/blob/master/benchmarks/browser">benchmarks/browser/</a> which you can run by opening the <code>.html</code> files in your browser.</p>
<h2>Contribute</h2>
<p>If you find a bug or something is broken, let us know! PRs and <a href="https://github.com/orbitdb/ipfs-log/issues">issues</a> are gladly accepted too. Take a look at the open issues, too, to see if there is anything that you could do or someone else has already done. Here are some things I know I need:</p>
<h3>TODO</h3>
<ul>
<li>Support for payload encryption</li>
</ul>
<h2>License</h2>
<p><a href="LICENSE">MIT</a> © 2016-2018 Protocol Labs Inc.,
2016-2019 Haja Networks Oy</p></article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="GSet.html">GSet</a></li><li><a href="Log.html">Log</a></li></ul><h3>Global</h3><ul><li><a href="global.html#LastWriteWins">LastWriteWins</a></li><li><a href="global.html#NoZeroes">NoZeroes</a></li><li><a href="global.html#SortByClockId">SortByClockId</a></li><li><a href="global.html#SortByClocks">SortByClocks</a></li><li><a href="global.html#SortByEntryHash">SortByEntryHash</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.6</a> on Fri Dec 11 2020 17:11:17 GMT-0500 (Eastern Standard Time)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>