@automerge/automerge-repo 2.0.0-alpha.6 → 2.0.0-collectionsync-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/dist/CollectionHandle.d.ts +14 -0
  2. package/dist/CollectionHandle.d.ts.map +1 -0
  3. package/dist/CollectionHandle.js +37 -0
  4. package/dist/DocHandle.d.ts +67 -2
  5. package/dist/DocHandle.d.ts.map +1 -1
  6. package/dist/DocHandle.js +113 -2
  7. package/dist/DocUrl.d.ts +47 -0
  8. package/dist/DocUrl.d.ts.map +1 -0
  9. package/dist/DocUrl.js +72 -0
  10. package/dist/EphemeralData.d.ts +20 -0
  11. package/dist/EphemeralData.d.ts.map +1 -0
  12. package/dist/EphemeralData.js +1 -0
  13. package/dist/Repo.d.ts +28 -7
  14. package/dist/Repo.d.ts.map +1 -1
  15. package/dist/Repo.js +142 -143
  16. package/dist/ferigan.d.ts +51 -0
  17. package/dist/ferigan.d.ts.map +1 -0
  18. package/dist/ferigan.js +98 -0
  19. package/dist/helpers/tests/storage-adapter-tests.d.ts +2 -2
  20. package/dist/helpers/tests/storage-adapter-tests.d.ts.map +1 -1
  21. package/dist/helpers/tests/storage-adapter-tests.js +19 -39
  22. package/dist/index.d.ts +2 -0
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +1 -0
  25. package/dist/network/NetworkSubsystem.d.ts +1 -0
  26. package/dist/network/NetworkSubsystem.d.ts.map +1 -1
  27. package/dist/network/NetworkSubsystem.js +3 -0
  28. package/dist/network/messages.d.ts +7 -1
  29. package/dist/network/messages.d.ts.map +1 -1
  30. package/dist/network/messages.js +2 -1
  31. package/dist/src/DocHandle.d.ts +182 -0
  32. package/dist/src/DocHandle.d.ts.map +1 -0
  33. package/dist/src/DocHandle.js +405 -0
  34. package/dist/src/DocUrl.d.ts +49 -0
  35. package/dist/src/DocUrl.d.ts.map +1 -0
  36. package/dist/src/DocUrl.js +72 -0
  37. package/dist/src/EphemeralData.d.ts +19 -0
  38. package/dist/src/EphemeralData.d.ts.map +1 -0
  39. package/dist/src/EphemeralData.js +1 -0
  40. package/dist/src/Repo.d.ts +74 -0
  41. package/dist/src/Repo.d.ts.map +1 -0
  42. package/dist/src/Repo.js +208 -0
  43. package/dist/src/helpers/arraysAreEqual.d.ts +2 -0
  44. package/dist/src/helpers/arraysAreEqual.d.ts.map +1 -0
  45. package/dist/src/helpers/arraysAreEqual.js +2 -0
  46. package/dist/src/helpers/cbor.d.ts +4 -0
  47. package/dist/src/helpers/cbor.d.ts.map +1 -0
  48. package/dist/src/helpers/cbor.js +8 -0
  49. package/dist/src/helpers/eventPromise.d.ts +11 -0
  50. package/dist/src/helpers/eventPromise.d.ts.map +1 -0
  51. package/dist/src/helpers/eventPromise.js +7 -0
  52. package/dist/src/helpers/headsAreSame.d.ts +2 -0
  53. package/dist/src/helpers/headsAreSame.d.ts.map +1 -0
  54. package/dist/src/helpers/headsAreSame.js +4 -0
  55. package/dist/src/helpers/mergeArrays.d.ts +2 -0
  56. package/dist/src/helpers/mergeArrays.d.ts.map +1 -0
  57. package/dist/src/helpers/mergeArrays.js +15 -0
  58. package/dist/src/helpers/pause.d.ts +6 -0
  59. package/dist/src/helpers/pause.d.ts.map +1 -0
  60. package/dist/src/helpers/pause.js +10 -0
  61. package/dist/src/helpers/tests/network-adapter-tests.d.ts +21 -0
  62. package/dist/src/helpers/tests/network-adapter-tests.d.ts.map +1 -0
  63. package/dist/src/helpers/tests/network-adapter-tests.js +122 -0
  64. package/dist/src/helpers/withTimeout.d.ts +12 -0
  65. package/dist/src/helpers/withTimeout.d.ts.map +1 -0
  66. package/dist/src/helpers/withTimeout.js +24 -0
  67. package/dist/src/index.d.ts +53 -0
  68. package/dist/src/index.d.ts.map +1 -0
  69. package/dist/src/index.js +40 -0
  70. package/dist/src/network/NetworkAdapter.d.ts +26 -0
  71. package/dist/src/network/NetworkAdapter.d.ts.map +1 -0
  72. package/dist/src/network/NetworkAdapter.js +4 -0
  73. package/dist/src/network/NetworkSubsystem.d.ts +23 -0
  74. package/dist/src/network/NetworkSubsystem.d.ts.map +1 -0
  75. package/dist/src/network/NetworkSubsystem.js +120 -0
  76. package/dist/src/network/messages.d.ts +85 -0
  77. package/dist/src/network/messages.d.ts.map +1 -0
  78. package/dist/src/network/messages.js +23 -0
  79. package/dist/src/storage/StorageAdapter.d.ts +14 -0
  80. package/dist/src/storage/StorageAdapter.d.ts.map +1 -0
  81. package/dist/src/storage/StorageAdapter.js +1 -0
  82. package/dist/src/storage/StorageSubsystem.d.ts +12 -0
  83. package/dist/src/storage/StorageSubsystem.d.ts.map +1 -0
  84. package/dist/src/storage/StorageSubsystem.js +145 -0
  85. package/dist/src/synchronizer/CollectionSynchronizer.d.ts +25 -0
  86. package/dist/src/synchronizer/CollectionSynchronizer.d.ts.map +1 -0
  87. package/dist/src/synchronizer/CollectionSynchronizer.js +106 -0
  88. package/dist/src/synchronizer/DocSynchronizer.d.ts +29 -0
  89. package/dist/src/synchronizer/DocSynchronizer.d.ts.map +1 -0
  90. package/dist/src/synchronizer/DocSynchronizer.js +263 -0
  91. package/dist/src/synchronizer/Synchronizer.d.ts +9 -0
  92. package/dist/src/synchronizer/Synchronizer.d.ts.map +1 -0
  93. package/dist/src/synchronizer/Synchronizer.js +2 -0
  94. package/dist/src/types.d.ts +16 -0
  95. package/dist/src/types.d.ts.map +1 -0
  96. package/dist/src/types.js +1 -0
  97. package/dist/storage/StorageAdapter.d.ts +9 -0
  98. package/dist/storage/StorageAdapter.d.ts.map +1 -1
  99. package/dist/storage/StorageAdapter.js +33 -0
  100. package/dist/storage/StorageSubsystem.d.ts +12 -2
  101. package/dist/storage/StorageSubsystem.d.ts.map +1 -1
  102. package/dist/storage/StorageSubsystem.js +42 -100
  103. package/dist/synchronizer/CollectionSynchronizer.d.ts +4 -2
  104. package/dist/synchronizer/CollectionSynchronizer.d.ts.map +1 -1
  105. package/dist/synchronizer/CollectionSynchronizer.js +28 -15
  106. package/dist/synchronizer/DocSynchronizer.d.ts +6 -5
  107. package/dist/synchronizer/DocSynchronizer.d.ts.map +1 -1
  108. package/dist/synchronizer/DocSynchronizer.js +76 -178
  109. package/dist/synchronizer/Synchronizer.d.ts +11 -0
  110. package/dist/synchronizer/Synchronizer.d.ts.map +1 -1
  111. package/dist/test/CollectionSynchronizer.test.d.ts +2 -0
  112. package/dist/test/CollectionSynchronizer.test.d.ts.map +1 -0
  113. package/dist/test/CollectionSynchronizer.test.js +57 -0
  114. package/dist/test/DocHandle.test.d.ts +2 -0
  115. package/dist/test/DocHandle.test.d.ts.map +1 -0
  116. package/dist/test/DocHandle.test.js +238 -0
  117. package/dist/test/DocSynchronizer.test.d.ts +2 -0
  118. package/dist/test/DocSynchronizer.test.d.ts.map +1 -0
  119. package/dist/test/DocSynchronizer.test.js +111 -0
  120. package/dist/test/Network.test.d.ts +2 -0
  121. package/dist/test/Network.test.d.ts.map +1 -0
  122. package/dist/test/Network.test.js +11 -0
  123. package/dist/test/Repo.test.d.ts +2 -0
  124. package/dist/test/Repo.test.d.ts.map +1 -0
  125. package/dist/test/Repo.test.js +568 -0
  126. package/dist/test/StorageSubsystem.test.d.ts +2 -0
  127. package/dist/test/StorageSubsystem.test.d.ts.map +1 -0
  128. package/dist/test/StorageSubsystem.test.js +56 -0
  129. package/dist/test/helpers/DummyNetworkAdapter.d.ts +9 -0
  130. package/dist/test/helpers/DummyNetworkAdapter.d.ts.map +1 -0
  131. package/dist/test/helpers/DummyNetworkAdapter.js +15 -0
  132. package/dist/test/helpers/DummyStorageAdapter.d.ts +16 -0
  133. package/dist/test/helpers/DummyStorageAdapter.d.ts.map +1 -0
  134. package/dist/test/helpers/DummyStorageAdapter.js +33 -0
  135. package/dist/test/helpers/generate-large-object.d.ts +5 -0
  136. package/dist/test/helpers/generate-large-object.d.ts.map +1 -0
  137. package/dist/test/helpers/generate-large-object.js +9 -0
  138. package/dist/test/helpers/getRandomItem.d.ts +2 -0
  139. package/dist/test/helpers/getRandomItem.d.ts.map +1 -0
  140. package/dist/test/helpers/getRandomItem.js +4 -0
  141. package/dist/test/types.d.ts +4 -0
  142. package/dist/test/types.d.ts.map +1 -0
  143. package/dist/test/types.js +1 -0
  144. package/package.json +3 -3
  145. package/src/CollectionHandle.ts +54 -0
  146. package/src/DocHandle.ts +133 -4
  147. package/src/Repo.ts +192 -183
  148. package/src/ferigan.ts +184 -0
  149. package/src/helpers/tests/storage-adapter-tests.ts +31 -62
  150. package/src/index.ts +2 -0
  151. package/src/network/NetworkSubsystem.ts +4 -0
  152. package/src/network/messages.ts +11 -2
  153. package/src/storage/StorageAdapter.ts +42 -0
  154. package/src/storage/StorageSubsystem.ts +59 -119
  155. package/src/synchronizer/CollectionSynchronizer.ts +34 -26
  156. package/src/synchronizer/DocSynchronizer.ts +84 -231
  157. package/src/synchronizer/Synchronizer.ts +14 -0
  158. package/test/CollectionSynchronizer.test.ts +4 -2
  159. package/test/DocHandle.test.ts +141 -0
  160. package/test/DocSynchronizer.test.ts +6 -1
  161. package/test/RemoteHeadsSubscriptions.test.ts +1 -1
  162. package/test/Repo.test.ts +225 -117
  163. package/test/StorageSubsystem.test.ts +20 -16
  164. package/test/remoteHeads.test.ts +1 -1
@@ -0,0 +1,14 @@
1
+ import { EventEmitter } from "eventemitter3";
2
+ import { Index } from "./ferigan.js";
3
+ import { AutomergeUrl } from "./types.js";
4
+ import { next as A } from "@automerge/automerge";
5
+ export type CollectionHandleEvents = {
6
+ doc_added: (url: AutomergeUrl) => void;
7
+ };
8
+ export declare class CollectionHandle extends EventEmitter<CollectionHandleEvents> {
9
+ #private;
10
+ get index(): Index;
11
+ constructor(belay: A.beelay.Beelay, rootUrl: AutomergeUrl, entries: AutomergeUrl[]);
12
+ add(url: AutomergeUrl): void;
13
+ }
14
+ //# sourceMappingURL=CollectionHandle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"CollectionHandle.d.ts","sourceRoot":"","sources":["../src/CollectionHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAW,KAAK,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAc,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,sBAAsB,CAAA;AAGhD,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,CAAA;CACvC,CAAA;AAED,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;IAQxE,IAAI,KAAK,IAAI,KAAK,CAKjB;gBAGC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EACtB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,YAAY,EAAE;IAoBzB,GAAG,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;CAK7B"}
@@ -0,0 +1,37 @@
1
+ import { EventEmitter } from "eventemitter3";
2
+ import { parseAutomergeUrl } from "./AutomergeUrl.js";
3
+ export class CollectionHandle extends EventEmitter {
4
+ //#index: Index
5
+ #beelay;
6
+ //#ferigan: Ferigan
7
+ #rootId;
8
+ #rootUrl;
9
+ #entries = [];
10
+ get index() {
11
+ return {
12
+ rootUrl: this.#rootUrl,
13
+ entries: this.#entries,
14
+ };
15
+ }
16
+ constructor(belay, rootUrl, entries) {
17
+ super();
18
+ this.#rootUrl = rootUrl;
19
+ this.#rootId = parseAutomergeUrl(rootUrl).documentId;
20
+ this.#beelay = belay;
21
+ this.#entries = entries;
22
+ //this.#ferigan.on("indexChanged", ({indexUrl, change}) => {
23
+ //if (indexUrl != this.#index.rootUrl) {
24
+ //return
25
+ //}
26
+ //if (change.type === "add") {
27
+ //this.#index.entries.push(change.url)
28
+ //this.emit("doc_added", change.url as AutomergeUrl)
29
+ //}
30
+ //})
31
+ }
32
+ add(url) {
33
+ this.#entries.push(url);
34
+ let docId = parseAutomergeUrl(url).documentId;
35
+ this.#beelay.addLink({ from: this.#rootId, to: docId });
36
+ }
37
+ }
@@ -30,6 +30,13 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
30
30
  * peers. We do not currently have an equivalent `whenSynced()`.
31
31
  */
32
32
  isReady: () => boolean;
33
+ /**
34
+ * @returns true if the document has been unloaded.
35
+ *
36
+ * Unloaded documents are freed from memory but not removed from local storage. It's not currently
37
+ * possible at runtime to reload an unloaded document.
38
+ */
39
+ isUnloaded: () => boolean;
33
40
  /**
34
41
  * @returns true if the document has been marked as deleted.
35
42
  *
@@ -48,7 +55,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
48
55
  */
49
56
  inState: (states: HandleState[]) => boolean;
50
57
  /** @hidden */
51
- get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "deleted";
58
+ get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "unloaded" | "deleted";
52
59
  /**
53
60
  * @returns a promise that resolves when the document is in one of the given states (if no states
54
61
  * are passed, when the document is ready)
@@ -86,6 +93,58 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
86
93
  * @returns the current document's heads, or undefined if the document is not ready
87
94
  */
88
95
  heads(): A.Heads | undefined;
96
+ begin(): void;
97
+ /**
98
+ * Creates a fixed "view" of an automerge document at the given point in time represented
99
+ * by the `heads` passed in. The return value is the same type as docSync() and will return
100
+ * undefined if the object hasn't finished loading.
101
+ *
102
+ * @remarks
103
+ * A point-in-time in an automerge document is an *array* of heads since there may be
104
+ * concurrent edits. This API just returns a topologically sorted history of all edits
105
+ * so every previous entry will be (in some sense) before later ones, but the set of all possible
106
+ * history views would be quite large under concurrency (every thing in each branch against each other).
107
+ * There might be a clever way to think about this, but we haven't found it yet, so for now at least
108
+ * we present a single traversable view which excludes concurrency.
109
+ * @returns The individual heads for every change in the document.
110
+ */
111
+ history(): A.Heads[] | undefined;
112
+ /**
113
+ * Creates a fixed "view" of an automerge document at the given point in time represented
114
+ * by the `heads` passed in. The return value is the same type as docSync() and will return
115
+ * undefined if the object hasn't finished loading.
116
+ *
117
+ * @remarks
118
+ * Note that our Typescript types do not consider change over time and the current version
119
+ * of Automerge doesn't check types at runtime, so if you go back to an old set of heads
120
+ * that doesn't match the heads here, Typescript will not save you.
121
+ *
122
+ * @returns An Automerge.Doc<T> at the point in time.
123
+ */
124
+ view(heads: A.Heads): A.Doc<T> | undefined;
125
+ /**
126
+ * Returns a set of Patch operations that will move a materialized document from one state to another
127
+ * if applied.
128
+ *
129
+ * @remarks
130
+ * We allow specifying both a from/to heads or just a single comparison point, in which case
131
+ * the base will be the current document heads.
132
+ *
133
+ * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
134
+ */
135
+ diff(first: A.Heads, second?: A.Heads): A.Patch[] | undefined;
136
+ /**
137
+ * `metadata(head?)` allows you to look at the metadata for a change
138
+ * this can be used to build history graphs to find commit messages and edit times.
139
+ * this interface.
140
+ *
141
+ * @remarks
142
+ * I'm really not convinced this is the right way to surface this information so
143
+ * I'm leaving this API "hidden".
144
+ *
145
+ * @hidden
146
+ */
147
+ metadata(change?: string): A.DecodedChange | undefined;
89
148
  /**
90
149
  * `update` is called any time we have a new document state; could be
91
150
  * from a local change, a remote change, or a new document from storage.
@@ -148,6 +207,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
148
207
  * @hidden
149
208
  * */
150
209
  request(): void;
210
+ /** Called by the repo to free memory used by the document. */
211
+ unload(): void;
212
+ /** Called by the repo to reuse an unloaded handle. */
213
+ reload(): void;
151
214
  /** Called by the repo when the document is deleted. */
152
215
  delete(): void;
153
216
  /**
@@ -236,11 +299,13 @@ export declare const HandleState: {
236
299
  readonly REQUESTING: "requesting";
237
300
  /** The document is available */
238
301
  readonly READY: "ready";
302
+ /** The document has been unloaded from the handle, to free memory usage */
303
+ readonly UNLOADED: "unloaded";
239
304
  /** The document has been deleted from the repo */
240
305
  readonly DELETED: "deleted";
241
306
  /** The document was not available in storage or from any connected peers */
242
307
  readonly UNAVAILABLE: "unavailable";
243
308
  };
244
309
  export type HandleState = (typeof HandleState)[keyof typeof HandleState];
245
- export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", DELETED: "deleted", UNAVAILABLE: "unavailable";
310
+ export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", UNLOADED: "unloaded", DELETED: "deleted", UNAVAILABLE: "unavailable";
246
311
  //# sourceMappingURL=DocHandle.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
package/dist/DocHandle.js CHANGED
@@ -59,6 +59,9 @@ export class DocHandle extends EventEmitter {
59
59
  this.emit("delete", { handle: this });
60
60
  return { doc: A.init() };
61
61
  }),
62
+ onUnload: assign(() => {
63
+ return { doc: A.init() };
64
+ }),
62
65
  onUnavailable: () => {
63
66
  this.emit("unavailable", { handle: this });
64
67
  },
@@ -71,6 +74,7 @@ export class DocHandle extends EventEmitter {
71
74
  context: { documentId, doc },
72
75
  on: {
73
76
  UPDATE: { actions: "onUpdate" },
77
+ UNLOAD: ".unloaded",
74
78
  DELETE: ".deleted",
75
79
  },
76
80
  states: {
@@ -98,6 +102,12 @@ export class DocHandle extends EventEmitter {
98
102
  on: { DOC_READY: "ready" },
99
103
  },
100
104
  ready: {},
105
+ unloaded: {
106
+ entry: "onUnload",
107
+ on: {
108
+ RELOAD: "loading",
109
+ },
110
+ },
101
111
  deleted: { entry: "onDelete", type: "final" },
102
112
  },
103
113
  });
@@ -113,7 +123,7 @@ export class DocHandle extends EventEmitter {
113
123
  });
114
124
  // Start the machine, and send a create or find event to get things going
115
125
  this.#machine.start();
116
- this.#machine.send({ type: BEGIN });
126
+ this.begin();
117
127
  }
118
128
  // PRIVATE
119
129
  /** Returns the current document, regardless of state */
@@ -172,6 +182,13 @@ export class DocHandle extends EventEmitter {
172
182
  * peers. We do not currently have an equivalent `whenSynced()`.
173
183
  */
174
184
  isReady = () => this.inState(["ready"]);
185
+ /**
186
+ * @returns true if the document has been unloaded.
187
+ *
188
+ * Unloaded documents are freed from memory but not removed from local storage. It's not currently
189
+ * possible at runtime to reload an unloaded document.
190
+ */
191
+ isUnloaded = () => this.inState(["unloaded"]);
175
192
  /**
176
193
  * @returns true if the document has been marked as deleted.
177
194
  *
@@ -253,6 +270,88 @@ export class DocHandle extends EventEmitter {
253
270
  }
254
271
  return A.getHeads(this.#doc);
255
272
  }
273
+ begin() {
274
+ this.#machine.send({ type: BEGIN });
275
+ }
276
+ /**
277
+ * Creates a fixed "view" of an automerge document at the given point in time represented
278
+ * by the `heads` passed in. The return value is the same type as docSync() and will return
279
+ * undefined if the object hasn't finished loading.
280
+ *
281
+ * @remarks
282
+ * A point-in-time in an automerge document is an *array* of heads since there may be
283
+ * concurrent edits. This API just returns a topologically sorted history of all edits
284
+ * so every previous entry will be (in some sense) before later ones, but the set of all possible
285
+ * history views would be quite large under concurrency (every thing in each branch against each other).
286
+ * There might be a clever way to think about this, but we haven't found it yet, so for now at least
287
+ * we present a single traversable view which excludes concurrency.
288
+ * @returns The individual heads for every change in the document.
289
+ */
290
+ history() {
291
+ if (!this.isReady()) {
292
+ return undefined;
293
+ }
294
+ // This just returns all the heads as individual strings.
295
+ return A.topoHistoryTraversal(this.#doc).map(h => [h]);
296
+ }
297
+ /**
298
+ * Creates a fixed "view" of an automerge document at the given point in time represented
299
+ * by the `heads` passed in. The return value is the same type as docSync() and will return
300
+ * undefined if the object hasn't finished loading.
301
+ *
302
+ * @remarks
303
+ * Note that our Typescript types do not consider change over time and the current version
304
+ * of Automerge doesn't check types at runtime, so if you go back to an old set of heads
305
+ * that doesn't match the heads here, Typescript will not save you.
306
+ *
307
+ * @returns An Automerge.Doc<T> at the point in time.
308
+ */
309
+ view(heads) {
310
+ if (!this.isReady()) {
311
+ return undefined;
312
+ }
313
+ return A.view(this.#doc, heads);
314
+ }
315
+ /**
316
+ * Returns a set of Patch operations that will move a materialized document from one state to another
317
+ * if applied.
318
+ *
319
+ * @remarks
320
+ * We allow specifying both a from/to heads or just a single comparison point, in which case
321
+ * the base will be the current document heads.
322
+ *
323
+ * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
324
+ */
325
+ diff(first, second) {
326
+ if (!this.isReady()) {
327
+ return undefined;
328
+ }
329
+ // We allow only one set of heads to be specified, in which case we use the doc's heads
330
+ const from = second ? first : this.heads() || []; // because we guard above this should always have useful data
331
+ const to = second ? second : first;
332
+ return A.diff(this.#doc, from, to);
333
+ }
334
+ /**
335
+ * `metadata(head?)` allows you to look at the metadata for a change
336
+ * this can be used to build history graphs to find commit messages and edit times.
337
+ * this interface.
338
+ *
339
+ * @remarks
340
+ * I'm really not convinced this is the right way to surface this information so
341
+ * I'm leaving this API "hidden".
342
+ *
343
+ * @hidden
344
+ */
345
+ metadata(change) {
346
+ if (!this.isReady()) {
347
+ return undefined;
348
+ }
349
+ if (!change) {
350
+ change = this.heads()[0];
351
+ }
352
+ // we return undefined instead of null by convention in this API
353
+ return A.inspectChange(this.#doc, change) || undefined;
354
+ }
256
355
  /**
257
356
  * `update` is called any time we have a new document state; could be
258
357
  * from a local change, a remote change, or a new document from storage.
@@ -365,6 +464,14 @@ export class DocHandle extends EventEmitter {
365
464
  if (this.#state === "loading")
366
465
  this.#machine.send({ type: REQUEST });
367
466
  }
467
+ /** Called by the repo to free memory used by the document. */
468
+ unload() {
469
+ this.#machine.send({ type: UNLOAD });
470
+ }
471
+ /** Called by the repo to reuse an unloaded handle. */
472
+ reload() {
473
+ this.#machine.send({ type: RELOAD });
474
+ }
368
475
  /** Called by the repo when the document is deleted. */
369
476
  delete() {
370
477
  this.#machine.send({ type: DELETE });
@@ -400,16 +507,20 @@ export const HandleState = {
400
507
  REQUESTING: "requesting",
401
508
  /** The document is available */
402
509
  READY: "ready",
510
+ /** The document has been unloaded from the handle, to free memory usage */
511
+ UNLOADED: "unloaded",
403
512
  /** The document has been deleted from the repo */
404
513
  DELETED: "deleted",
405
514
  /** The document was not available in storage or from any connected peers */
406
515
  UNAVAILABLE: "unavailable",
407
516
  };
408
- export const { IDLE, LOADING, REQUESTING, READY, DELETED, UNAVAILABLE } = HandleState;
517
+ export const { IDLE, LOADING, REQUESTING, READY, UNLOADED, DELETED, UNAVAILABLE, } = HandleState;
409
518
  const BEGIN = "BEGIN";
410
519
  const REQUEST = "REQUEST";
411
520
  const DOC_READY = "DOC_READY";
412
521
  const UPDATE = "UPDATE";
522
+ const UNLOAD = "UNLOAD";
523
+ const RELOAD = "RELOAD";
413
524
  const DELETE = "DELETE";
414
525
  const TIMEOUT = "TIMEOUT";
415
526
  const DOC_UNAVAILABLE = "DOC_UNAVAILABLE";
@@ -0,0 +1,47 @@
1
+ import {
2
+ type AutomergeUrl,
3
+ type BinaryDocumentId,
4
+ type DocumentId,
5
+ } from "./types.js"
6
+ export declare const urlPrefix = "automerge:"
7
+ /**
8
+ * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
9
+ *
10
+ * @param url
11
+ * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
12
+ */
13
+ export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
14
+ binaryDocumentId: BinaryDocumentId
15
+ documentId: DocumentId
16
+ }
17
+ /**
18
+ * Given a documentId in either canonical form, return an Automerge URL
19
+ * Throws on invalid input.
20
+ * Note: this is an object because we anticipate adding fields in the future.
21
+ * @param { documentId: BinaryDocumentId | DocumentId }
22
+ * @returns AutomergeUrl
23
+ */
24
+ export declare const stringifyAutomergeUrl: ({
25
+ documentId,
26
+ }: {
27
+ documentId: DocumentId | BinaryDocumentId
28
+ }) => AutomergeUrl
29
+ /**
30
+ * Given a string, return true if it is a valid Automerge URL
31
+ * also acts as a type discriminator in Typescript.
32
+ * @param str: URL candidate
33
+ * @returns boolean
34
+ */
35
+ export declare const isValidAutomergeUrl: (str: string) => str is AutomergeUrl
36
+ /**
37
+ * generateAutomergeUrl produces a new AutomergeUrl.
38
+ * generally only called by create(), but used in tests as well.
39
+ * @returns a new Automerge URL with a random UUID documentId
40
+ */
41
+ export declare const generateAutomergeUrl: () => AutomergeUrl
42
+ export declare const documentIdToBinary: (
43
+ docId: DocumentId
44
+ ) => BinaryDocumentId | undefined
45
+ export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId
46
+ export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined
47
+ //# sourceMappingURL=DocUrl.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"DocUrl.d.ts","sourceRoot":"","sources":["../src/DocUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAS,YAAY;;;CAIlD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;gBAGpB,UAAU,GAAG,gBAAgB;MACvC,YAQH,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAS,MAAM,wBAK9C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGpC,CAAA;AAEJ,eAAO,MAAM,kBAAkB,UACtB,UAAU,KAChB,gBAAgB,GAAG,SACyC,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAAG,UACtB,CAAA;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,KAAG,YAAY,GAAG,SAM5D,CAAA"}
package/dist/DocUrl.js ADDED
@@ -0,0 +1,72 @@
1
+ import * as Uuid from "uuid"
2
+ import bs58check from "bs58check"
3
+ export const urlPrefix = "automerge:"
4
+ /**
5
+ * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
6
+ *
7
+ * @param url
8
+ * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
9
+ */
10
+ export const parseAutomergeUrl = url => {
11
+ const { binaryDocumentId, documentId } = parts(url)
12
+ if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
13
+ return { binaryDocumentId, documentId }
14
+ }
15
+ /**
16
+ * Given a documentId in either canonical form, return an Automerge URL
17
+ * Throws on invalid input.
18
+ * Note: this is an object because we anticipate adding fields in the future.
19
+ * @param { documentId: BinaryDocumentId | DocumentId }
20
+ * @returns AutomergeUrl
21
+ */
22
+ export const stringifyAutomergeUrl = ({ documentId }) => {
23
+ if (documentId instanceof Uint8Array)
24
+ return urlPrefix + binaryToDocumentId(documentId)
25
+ else if (typeof documentId === "string") {
26
+ return urlPrefix + documentId
27
+ }
28
+ throw new Error("Invalid documentId: " + documentId)
29
+ }
30
+ /**
31
+ * Given a string, return true if it is a valid Automerge URL
32
+ * also acts as a type discriminator in Typescript.
33
+ * @param str: URL candidate
34
+ * @returns boolean
35
+ */
36
+ export const isValidAutomergeUrl = str => {
37
+ if (!str.startsWith(urlPrefix)) return false
38
+ const { binaryDocumentId: documentId } = parts(str)
39
+ return documentId ? true : false
40
+ }
41
+ /**
42
+ * generateAutomergeUrl produces a new AutomergeUrl.
43
+ * generally only called by create(), but used in tests as well.
44
+ * @returns a new Automerge URL with a random UUID documentId
45
+ */
46
+ export const generateAutomergeUrl = () =>
47
+ stringifyAutomergeUrl({
48
+ documentId: Uuid.v4(null, new Uint8Array(16)),
49
+ })
50
+ export const documentIdToBinary = docId => bs58check.decodeUnsafe(docId)
51
+ export const binaryToDocumentId = docId => bs58check.encode(docId)
52
+ export const parseLegacyUUID = str => {
53
+ if (Uuid.validate(str)) {
54
+ const uuid = Uuid.parse(str)
55
+ return stringifyAutomergeUrl({ documentId: uuid })
56
+ }
57
+ return undefined
58
+ }
59
+ /**
60
+ * parts breaks up the URL into constituent pieces,
61
+ * eventually this could include things like heads, so we use this structure
62
+ * we return both a binary & string-encoded version of the document ID
63
+ * @param str
64
+ * @returns { binaryDocumentId, documentId }
65
+ */
66
+ const parts = str => {
67
+ const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
68
+ const [_, docMatch] = str.match(regex) || []
69
+ const documentId = docMatch
70
+ const binaryDocumentId = documentIdToBinary(documentId)
71
+ return { binaryDocumentId, documentId }
72
+ }
@@ -0,0 +1,20 @@
1
+ import { DocumentId, PeerId } from "./index.js"
2
+ import { EphemeralMessage, MessageContents } from "./network/messages.js"
3
+ /** A randomly generated string created when the {@link Repo} starts up */
4
+ export type SessionId = string & {
5
+ __SessionId: false
6
+ }
7
+ export interface EphemeralDataPayload {
8
+ documentId: DocumentId
9
+ peerId: PeerId
10
+ data: {
11
+ peerId: PeerId
12
+ documentId: DocumentId
13
+ data: unknown
14
+ }
15
+ }
16
+ export type EphemeralDataMessageEvents = {
17
+ message: (event: MessageContents<EphemeralMessage>) => void
18
+ data: (event: EphemeralDataPayload) => void
19
+ }
20
+ //# sourceMappingURL=EphemeralData.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"EphemeralData.d.ts","sourceRoot":"","sources":["../src/EphemeralData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGzE,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAChE;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAA;IAC3D,IAAI,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;CAC5C,CAAA"}
@@ -0,0 +1 @@
1
+ export {}
package/dist/Repo.d.ts CHANGED
@@ -6,7 +6,8 @@ import { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js";
6
6
  import { StorageSubsystem } from "./storage/StorageSubsystem.js";
7
7
  import { StorageId } from "./storage/types.js";
8
8
  import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
9
- import type { AnyDocumentId, DocumentId, PeerId } from "./types.js";
9
+ import { DocSyncMetrics } from "./synchronizer/Synchronizer.js";
10
+ import type { AnyDocumentId, AutomergeUrl, DocumentId, PeerId } from "./types.js";
10
11
  /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
11
12
  /** The `Repo` is the main entry point of this library
12
13
  *
@@ -19,11 +20,7 @@ export declare class Repo extends EventEmitter<RepoEvents> {
19
20
  #private;
20
21
  /** @hidden */
21
22
  networkSubsystem: NetworkSubsystem;
22
- /** @hidden */
23
- storageSubsystem?: StorageSubsystem;
24
- /** The debounce rate is adjustable on the repo. */
25
- /** @hidden */
26
- saveDebounceRate: number;
23
+ storageSubsystem: StorageSubsystem;
27
24
  /** @hidden */
28
25
  synchronizer: CollectionSynchronizer;
29
26
  /** By default, we share generously with all peers. */
@@ -32,7 +29,7 @@ export declare class Repo extends EventEmitter<RepoEvents> {
32
29
  /** maps peer id to to persistence information (storageId, isEphemeral), access by collection synchronizer */
33
30
  /** @hidden */
34
31
  peerMetadataByPeerId: Record<PeerId, PeerMetadata>;
35
- constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, }?: RepoConfig);
32
+ constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, denylist, }?: RepoConfig);
36
33
  /** Returns all the handles we have cached. */
37
34
  get handles(): Record<DocumentId, DocHandle<any>>;
38
35
  /** Returns a list of all connected peer ids */
@@ -92,6 +89,13 @@ export declare class Repo extends EventEmitter<RepoEvents> {
92
89
  * @returns Promise<void>
93
90
  */
94
91
  flush(documents?: DocumentId[]): Promise<void>;
92
+ /**
93
+ * Removes a DocHandle from the handleCache.
94
+ * @hidden this API is experimental and may change.
95
+ * @param documentId - documentId of the DocHandle to remove from handleCache, if present in cache.
96
+ * @returns Promise<void>
97
+ */
98
+ removeFromCache(documentId: DocumentId): Promise<void>;
95
99
  shutdown(): Promise<void>;
96
100
  metrics(): {
97
101
  documents: {
@@ -118,6 +122,12 @@ export interface RepoConfig {
118
122
  * Whether to enable the experimental remote heads gossiping feature
119
123
  */
120
124
  enableRemoteHeadsGossiping?: boolean;
125
+ /**
126
+ * A list of automerge URLs which should never be loaded regardless of what
127
+ * messages are received or what the share policy is. This is useful to avoid
128
+ * loading documents that are known to be too resource intensive.
129
+ */
130
+ denylist?: AutomergeUrl[];
121
131
  }
122
132
  /** A function that determines whether we should share a document with a peer
123
133
  *
@@ -135,6 +145,7 @@ export interface RepoEvents {
135
145
  "delete-document": (arg: DeleteDocumentPayload) => void;
136
146
  /** A document was marked as unavailable (we don't have it and none of our peers have it) */
137
147
  "unavailable-document": (arg: DeleteDocumentPayload) => void;
148
+ "doc-metrics": (arg: DocMetrics) => void;
138
149
  }
139
150
  export interface DocumentPayload {
140
151
  handle: DocHandle<any>;
@@ -142,4 +153,14 @@ export interface DocumentPayload {
142
153
  export interface DeleteDocumentPayload {
143
154
  documentId: DocumentId;
144
155
  }
156
+ export type DocMetrics = DocSyncMetrics | {
157
+ type: "doc-loaded";
158
+ documentId: DocumentId;
159
+ durationMillis: number;
160
+ numOps: number;
161
+ numChanges: number;
162
+ } | {
163
+ type: "doc-denied";
164
+ documentId: DocumentId;
165
+ };
145
166
  //# sourceMappingURL=Repo.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}