@automerge/automerge-repo 2.0.0-alpha.7 → 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 +37 -6
  5. package/dist/DocHandle.d.ts.map +1 -1
  6. package/dist/DocHandle.js +64 -6
  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 +80 -8
  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 +72 -13
  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,7 @@ 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;
89
97
  /**
90
98
  * Creates a fixed "view" of an automerge document at the given point in time represented
91
99
  * by the `heads` passed in. The return value is the same type as docSync() and will return
@@ -105,13 +113,18 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
105
113
  * Creates a fixed "view" of an automerge document at the given point in time represented
106
114
  * by the `heads` passed in. The return value is the same type as docSync() and will return
107
115
  * undefined if the object hasn't finished loading.
108
- * @returns
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.
109
123
  */
110
124
  view(heads: A.Heads): A.Doc<T> | undefined;
111
125
  /**
112
- * Creates a fixed "view" of an automerge document at the given point in time represented
113
- * by the `heads` passed in. The return value is the same type as docSync() and will return
114
- * undefined if the object hasn't finished loading.
126
+ * Returns a set of Patch operations that will move a materialized document from one state to another
127
+ * if applied.
115
128
  *
116
129
  * @remarks
117
130
  * We allow specifying both a from/to heads or just a single comparison point, in which case
@@ -120,6 +133,18 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
120
133
  * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
121
134
  */
122
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;
123
148
  /**
124
149
  * `update` is called any time we have a new document state; could be
125
150
  * from a local change, a remote change, or a new document from storage.
@@ -182,6 +207,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
182
207
  * @hidden
183
208
  * */
184
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;
185
214
  /** Called by the repo when the document is deleted. */
186
215
  delete(): void;
187
216
  /**
@@ -270,11 +299,13 @@ export declare const HandleState: {
270
299
  readonly REQUESTING: "requesting";
271
300
  /** The document is available */
272
301
  readonly READY: "ready";
302
+ /** The document has been unloaded from the handle, to free memory usage */
303
+ readonly UNLOADED: "unloaded";
273
304
  /** The document has been deleted from the repo */
274
305
  readonly DELETED: "deleted";
275
306
  /** The document was not available in storage or from any connected peers */
276
307
  readonly UNAVAILABLE: "unavailable";
277
308
  };
278
309
  export type HandleState = (typeof HandleState)[keyof typeof HandleState];
279
- 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";
280
311
  //# sourceMappingURL=DocHandle.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAM5C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;;IAkBvD,UAAU,EAAE,UAAU;IAF/B,cAAc;gBAEL,UAAU,EAAE,UAAU,EAC7B,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM;IAoJnC;OACG;IACH,IAAI,GAAG,IAAI,YAAY,CAEtB;IAED;;;;;OAKG;IACH,OAAO,gBAAgC;IAEvC;;;;;OAKG;IACH,SAAS,gBAAkC;IAE3C;;;;OAIG;IACH,aAAa,gBAAsC;IAEnD;;OAEG;IACH,OAAO,WAAY,WAAW,EAAE,aAC0B;IAE1D,cAAc;IACd,IAAI,KAAK,4EAER;IAED;;;;;;OAMG;IACG,SAAS,CAAC,WAAW,GAAE,WAAW,EAAc;IAItD;;;;;OAKG;IACG,GAAG;IACP,sEAAsE;IACtE,WAAW,GAAE,WAAW,EAA6B;IAavD;;;;;;;;;;;;OAYG;IACH,OAAO;IAKP;;;;OAIG;IACH,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,SAAS;IAO5B;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,CAAC,CAAC,KAAK,EAAE,GAAG,SAAS;IAShC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS;IAO1C;;;;;;;;;;OAUG;IACH,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,SAAS;IAU7D;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAI5C;;;;OAIG;IACH,WAAW;IAIX;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK;IAKnD,0CAA0C;IAC1C,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,GAAG,SAAS;IAIzD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM;IAWhE;;;;OAIG;IACH,QAAQ,CACN,KAAK,EAAE,CAAC,CAAC,KAAK,EACd,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM,GAC/B,MAAM,EAAE,GAAG,SAAS;IAsBvB;;;;;;;OAOG;IACH,KAAK;IACH,wDAAwD;IACxD,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;IAe3B;;;OAGG;IACH,WAAW;IAIX;;SAEK;IACL,OAAO;IAIP,uDAAuD;IACvD,MAAM;IAIN;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO;IAO1B,OAAO,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAGlD;AAID,cAAc;AACd,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE1B;IACE,gGAAgG;IAChG,KAAK,EAAE,IAAI,CAAA;IAEX,yCAAyC;IACzC,YAAY,CAAC,EAAE,CAAC,CAAA;CACjB,GAED;IACE,KAAK,CAAC,EAAE,KAAK,CAAA;IAEb,+HAA+H;IAC/H,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAIL,2EAA2E;AAC3E,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,eAAe,EAAE,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpE,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpD,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpD,WAAW,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC9D,mBAAmB,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC3E,4BAA4B,EAAE,CAC5B,OAAO,EAAE,wCAAwC,CAAC,CAAC,CAAC,KACjD,IAAI,CAAA;IACT,cAAc,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAA;CAC/D;AAED,sDAAsD;AACtD,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC9C,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,iDAAiD;IACjD,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACb,wDAAwD;IACxD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAA;IAClB,mCAAmC;IACnC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,gCAAgC,CAAC,CAAC;IACjD,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,wCAAwC,CAAC,CAAC;IACzD,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAA;CACf;AAMD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB,kEAAkE;;IAElE,mDAAmD;;IAEnD,6EAA6E;;IAE7E,gCAAgC;;IAEhC,kDAAkD;;IAElD,4EAA4E;;CAEpE,CAAA;AACV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAExE,eAAO,MAAQ,IAAI,UAAE,OAAO,aAAE,UAAU,gBAAE,KAAK,WAAE,OAAO,aAAE,WAAW,eACxD,CAAA"}
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,9 @@ 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
+ }
256
276
  /**
257
277
  * Creates a fixed "view" of an automerge document at the given point in time represented
258
278
  * by the `heads` passed in. The return value is the same type as docSync() and will return
@@ -278,7 +298,13 @@ export class DocHandle extends EventEmitter {
278
298
  * Creates a fixed "view" of an automerge document at the given point in time represented
279
299
  * by the `heads` passed in. The return value is the same type as docSync() and will return
280
300
  * undefined if the object hasn't finished loading.
281
- * @returns
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.
282
308
  */
283
309
  view(heads) {
284
310
  if (!this.isReady()) {
@@ -287,9 +313,8 @@ export class DocHandle extends EventEmitter {
287
313
  return A.view(this.#doc, heads);
288
314
  }
289
315
  /**
290
- * Creates a fixed "view" of an automerge document at the given point in time represented
291
- * by the `heads` passed in. The return value is the same type as docSync() and will return
292
- * undefined if the object hasn't finished loading.
316
+ * Returns a set of Patch operations that will move a materialized document from one state to another
317
+ * if applied.
293
318
  *
294
319
  * @remarks
295
320
  * We allow specifying both a from/to heads or just a single comparison point, in which case
@@ -306,6 +331,27 @@ export class DocHandle extends EventEmitter {
306
331
  const to = second ? second : first;
307
332
  return A.diff(this.#doc, from, to);
308
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
+ }
309
355
  /**
310
356
  * `update` is called any time we have a new document state; could be
311
357
  * from a local change, a remote change, or a new document from storage.
@@ -418,6 +464,14 @@ export class DocHandle extends EventEmitter {
418
464
  if (this.#state === "loading")
419
465
  this.#machine.send({ type: REQUEST });
420
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
+ }
421
475
  /** Called by the repo when the document is deleted. */
422
476
  delete() {
423
477
  this.#machine.send({ type: DELETE });
@@ -453,16 +507,20 @@ export const HandleState = {
453
507
  REQUESTING: "requesting",
454
508
  /** The document is available */
455
509
  READY: "ready",
510
+ /** The document has been unloaded from the handle, to free memory usage */
511
+ UNLOADED: "unloaded",
456
512
  /** The document has been deleted from the repo */
457
513
  DELETED: "deleted",
458
514
  /** The document was not available in storage or from any connected peers */
459
515
  UNAVAILABLE: "unavailable",
460
516
  };
461
- export const { IDLE, LOADING, REQUESTING, READY, DELETED, UNAVAILABLE } = HandleState;
517
+ export const { IDLE, LOADING, REQUESTING, READY, UNLOADED, DELETED, UNAVAILABLE, } = HandleState;
462
518
  const BEGIN = "BEGIN";
463
519
  const REQUEST = "REQUEST";
464
520
  const DOC_READY = "DOC_READY";
465
521
  const UPDATE = "UPDATE";
522
+ const UNLOAD = "UNLOAD";
523
+ const RELOAD = "RELOAD";
466
524
  const DELETE = "DELETE";
467
525
  const TIMEOUT = "TIMEOUT";
468
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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"}