@automerge/automerge-repo 2.0.0-alpha.2 → 2.0.0-alpha.20

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 (61) hide show
  1. package/dist/AutomergeUrl.d.ts +17 -5
  2. package/dist/AutomergeUrl.d.ts.map +1 -1
  3. package/dist/AutomergeUrl.js +71 -24
  4. package/dist/DocHandle.d.ts +80 -8
  5. package/dist/DocHandle.d.ts.map +1 -1
  6. package/dist/DocHandle.js +181 -10
  7. package/dist/RemoteHeadsSubscriptions.d.ts +4 -5
  8. package/dist/RemoteHeadsSubscriptions.d.ts.map +1 -1
  9. package/dist/RemoteHeadsSubscriptions.js +4 -1
  10. package/dist/Repo.d.ts +35 -2
  11. package/dist/Repo.d.ts.map +1 -1
  12. package/dist/Repo.js +112 -70
  13. package/dist/entrypoints/fullfat.d.ts +1 -0
  14. package/dist/entrypoints/fullfat.d.ts.map +1 -1
  15. package/dist/entrypoints/fullfat.js +1 -2
  16. package/dist/helpers/bufferFromHex.d.ts +3 -0
  17. package/dist/helpers/bufferFromHex.d.ts.map +1 -0
  18. package/dist/helpers/bufferFromHex.js +13 -0
  19. package/dist/helpers/headsAreSame.d.ts +2 -2
  20. package/dist/helpers/headsAreSame.d.ts.map +1 -1
  21. package/dist/helpers/mergeArrays.d.ts +1 -1
  22. package/dist/helpers/mergeArrays.d.ts.map +1 -1
  23. package/dist/helpers/tests/storage-adapter-tests.d.ts +2 -2
  24. package/dist/helpers/tests/storage-adapter-tests.d.ts.map +1 -1
  25. package/dist/helpers/tests/storage-adapter-tests.js +25 -48
  26. package/dist/index.d.ts +1 -1
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/storage/StorageSubsystem.d.ts +11 -1
  30. package/dist/storage/StorageSubsystem.d.ts.map +1 -1
  31. package/dist/storage/StorageSubsystem.js +20 -4
  32. package/dist/synchronizer/CollectionSynchronizer.d.ts +15 -2
  33. package/dist/synchronizer/CollectionSynchronizer.d.ts.map +1 -1
  34. package/dist/synchronizer/CollectionSynchronizer.js +29 -8
  35. package/dist/synchronizer/DocSynchronizer.d.ts +7 -0
  36. package/dist/synchronizer/DocSynchronizer.d.ts.map +1 -1
  37. package/dist/synchronizer/DocSynchronizer.js +14 -0
  38. package/dist/synchronizer/Synchronizer.d.ts +11 -0
  39. package/dist/synchronizer/Synchronizer.d.ts.map +1 -1
  40. package/dist/types.d.ts +4 -1
  41. package/dist/types.d.ts.map +1 -1
  42. package/package.json +3 -3
  43. package/src/AutomergeUrl.ts +101 -26
  44. package/src/DocHandle.ts +245 -20
  45. package/src/RemoteHeadsSubscriptions.ts +11 -9
  46. package/src/Repo.ts +163 -68
  47. package/src/entrypoints/fullfat.ts +1 -2
  48. package/src/helpers/bufferFromHex.ts +14 -0
  49. package/src/helpers/headsAreSame.ts +2 -2
  50. package/src/helpers/tests/storage-adapter-tests.ts +44 -86
  51. package/src/index.ts +2 -0
  52. package/src/storage/StorageSubsystem.ts +29 -4
  53. package/src/synchronizer/CollectionSynchronizer.ts +42 -9
  54. package/src/synchronizer/DocSynchronizer.ts +15 -0
  55. package/src/synchronizer/Synchronizer.ts +14 -0
  56. package/src/types.ts +4 -1
  57. package/test/AutomergeUrl.test.ts +130 -0
  58. package/test/DocHandle.test.ts +209 -2
  59. package/test/DocSynchronizer.test.ts +10 -3
  60. package/test/Repo.test.ts +228 -3
  61. package/test/StorageSubsystem.test.ts +17 -0
@@ -1,17 +1,26 @@
1
- import type { LegacyDocumentId, AutomergeUrl, BinaryDocumentId, DocumentId, AnyDocumentId } from "./types.js";
1
+ import type { LegacyDocumentId, AutomergeUrl, BinaryDocumentId, DocumentId, AnyDocumentId, UrlHeads } from "./types.js";
2
+ import type { Heads as AutomergeHeads } from "@automerge/automerge/slim";
2
3
  export declare const urlPrefix = "automerge:";
3
- /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
4
- export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
4
+ interface ParsedAutomergeUrl {
5
5
  /** unencoded DocumentId */
6
6
  binaryDocumentId: BinaryDocumentId;
7
- /** encoded DocumentId */
7
+ /** bs58 encoded DocumentId */
8
8
  documentId: DocumentId;
9
- };
9
+ /** Optional array of heads, if specified in URL */
10
+ heads?: UrlHeads;
11
+ /** Optional hex array of heads, in Automerge core format */
12
+ hexHeads?: string[];
13
+ }
14
+ /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
15
+ export declare const parseAutomergeUrl: (url: AutomergeUrl) => ParsedAutomergeUrl;
10
16
  /**
11
17
  * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
12
18
  * Throws on invalid input.
13
19
  */
14
20
  export declare const stringifyAutomergeUrl: (arg: UrlOptions | DocumentId | BinaryDocumentId) => AutomergeUrl;
21
+ /** Helper to extract just the heads from a URL if they exist */
22
+ export declare const getHeadsFromUrl: (url: AutomergeUrl) => string[] | undefined;
23
+ export declare const anyDocumentIdToAutomergeUrl: (id: AnyDocumentId) => AutomergeUrl | undefined;
15
24
  /**
16
25
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
17
26
  * discriminator in Typescript.
@@ -25,6 +34,8 @@ export declare const isValidUuid: (str: unknown) => str is LegacyDocumentId;
25
34
  export declare const generateAutomergeUrl: () => AutomergeUrl;
26
35
  export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
27
36
  export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
37
+ export declare const encodeHeads: (heads: AutomergeHeads) => UrlHeads;
38
+ export declare const decodeHeads: (heads: UrlHeads) => AutomergeHeads;
28
39
  export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
29
40
  /**
30
41
  * Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
@@ -40,6 +51,7 @@ export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
40
51
  export declare const interpretAsDocumentId: (id: AnyDocumentId) => DocumentId;
41
52
  type UrlOptions = {
42
53
  documentId: DocumentId | BinaryDocumentId;
54
+ heads?: UrlHeads;
43
55
  };
44
56
  export {};
45
57
  //# sourceMappingURL=AutomergeUrl.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"AutomergeUrl.d.ts","sourceRoot":"","sources":["../src/AutomergeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,QAAS,YAAY;IAQ/C,2BAA2B;;IAE3B,yBAAyB;;CAG5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAC3B,UAAU,GAAG,UAAU,GAAG,gBAAgB,KAmBL,YAC3C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAS,OAAO,KAAG,GAAG,IAAI,YAUzD,CAAA;AAED,eAAO,MAAM,iBAAiB,QAAS,OAAO,KAAG,GAAG,IAAI,UASvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAS,OAAO,KAAG,GAAG,IAAI,gBACH,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGvC,CAAA;AAED,eAAO,MAAM,kBAAkB,UAAW,UAAU,KACjB,gBAAgB,GAAG,SAAS,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAC7B,UAAU,CAAA;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,6BAI1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,OAAQ,aAAa,eAqBtD,CAAA;AAID,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;CAC1C,CAAA"}
1
+ {"version":3,"file":"AutomergeUrl.d.ts","sourceRoot":"","sources":["../src/AutomergeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,EACT,MAAM,YAAY,CAAA;AASnB,OAAO,KAAK,EAAE,KAAK,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAExE,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,UAAU,kBAAkB;IAC1B,2BAA2B;IAC3B,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,8BAA8B;IAC9B,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,QAAS,YAAY,KAAG,kBAsBrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAC3B,UAAU,GAAG,UAAU,GAAG,gBAAgB,KAC9C,YAgCF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,eAAe,QAAS,YAAY,KAAG,MAAM,EAAE,GAAG,SAG9D,CAAA;AAED,eAAO,MAAM,2BAA2B,OAAQ,aAAa,6BAO9C,CAAA;AAEf;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAS,OAAO,KAAG,GAAG,IAAI,YAsBzD,CAAA;AAED,eAAO,MAAM,iBAAiB,QAAS,OAAO,KAAG,GAAG,IAAI,UASvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAS,OAAO,KAAG,GAAG,IAAI,gBACH,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGvC,CAAA;AAED,eAAO,MAAM,kBAAkB,UAAW,UAAU,KACjB,gBAAgB,GAAG,SAAS,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAC7B,UAAU,CAAA;AAEvC,eAAO,MAAM,WAAW,UAAW,cAAc,KAAG,QACsB,CAAA;AAE1E,eAAO,MAAM,WAAW,UAAW,QAAQ,KAAG,cACgC,CAAA;AAE9E,eAAO,MAAM,eAAe,QAAS,MAAM,6BAI1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,OAAQ,aAAa,eAqBtD,CAAA;AAID,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;IACzC,KAAK,CAAC,EAAE,QAAQ,CAAA;CACjB,CAAA"}
@@ -1,53 +1,98 @@
1
1
  import * as Uuid from "uuid";
2
2
  import bs58check from "bs58check";
3
+ import { uint8ArrayFromHexString, uint8ArrayToHexString, } from "./helpers/bufferFromHex.js";
3
4
  export const urlPrefix = "automerge:";
4
5
  /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
5
6
  export const parseAutomergeUrl = (url) => {
7
+ const [baseUrl, headsSection, ...rest] = url.split("#");
8
+ if (rest.length > 0) {
9
+ throw new Error("Invalid URL: contains multiple heads sections");
10
+ }
6
11
  const regex = new RegExp(`^${urlPrefix}(\\w+)$`);
7
- const [, docMatch] = url.match(regex) || [];
12
+ const [, docMatch] = baseUrl.match(regex) || [];
8
13
  const documentId = docMatch;
9
14
  const binaryDocumentId = documentIdToBinary(documentId);
10
15
  if (!binaryDocumentId)
11
16
  throw new Error("Invalid document URL: " + url);
12
- return {
13
- /** unencoded DocumentId */
14
- binaryDocumentId,
15
- /** encoded DocumentId */
16
- documentId,
17
- };
17
+ if (headsSection === undefined)
18
+ return { binaryDocumentId, documentId };
19
+ const heads = (headsSection === "" ? [] : headsSection.split("|"));
20
+ const hexHeads = heads.map(head => {
21
+ try {
22
+ return uint8ArrayToHexString(bs58check.decode(head));
23
+ }
24
+ catch (e) {
25
+ throw new Error(`Invalid head in URL: ${head}`);
26
+ }
27
+ });
28
+ return { binaryDocumentId, hexHeads, documentId, heads };
18
29
  };
19
30
  /**
20
31
  * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
21
32
  * Throws on invalid input.
22
33
  */
23
34
  export const stringifyAutomergeUrl = (arg) => {
24
- const documentId = arg instanceof Uint8Array || typeof arg === "string"
25
- ? arg
26
- : "documentId" in arg
27
- ? arg.documentId
28
- : undefined;
35
+ if (arg instanceof Uint8Array || typeof arg === "string") {
36
+ return (urlPrefix +
37
+ (arg instanceof Uint8Array
38
+ ? binaryToDocumentId(arg)
39
+ : arg));
40
+ }
41
+ const { documentId, heads = undefined } = arg;
42
+ if (documentId === undefined)
43
+ throw new Error("Invalid documentId: " + documentId);
29
44
  const encodedDocumentId = documentId instanceof Uint8Array
30
45
  ? binaryToDocumentId(documentId)
31
- : typeof documentId === "string"
32
- ? documentId
33
- : undefined;
34
- if (encodedDocumentId === undefined)
35
- throw new Error("Invalid documentId: " + documentId);
36
- return (urlPrefix + encodedDocumentId);
46
+ : documentId;
47
+ let url = `${urlPrefix}${encodedDocumentId}`;
48
+ if (heads !== undefined) {
49
+ heads.forEach(head => {
50
+ try {
51
+ bs58check.decode(head);
52
+ }
53
+ catch (e) {
54
+ throw new Error(`Invalid head: ${head}`);
55
+ }
56
+ });
57
+ url += "#" + heads.join("|");
58
+ }
59
+ return url;
60
+ };
61
+ /** Helper to extract just the heads from a URL if they exist */
62
+ export const getHeadsFromUrl = (url) => {
63
+ const { heads } = parseAutomergeUrl(url);
64
+ return heads;
37
65
  };
66
+ export const anyDocumentIdToAutomergeUrl = (id) => isValidAutomergeUrl(id)
67
+ ? id
68
+ : isValidDocumentId(id)
69
+ ? stringifyAutomergeUrl({ documentId: id })
70
+ : isValidUuid(id)
71
+ ? parseLegacyUUID(id)
72
+ : undefined;
38
73
  /**
39
74
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
40
75
  * discriminator in Typescript.
41
76
  */
42
77
  export const isValidAutomergeUrl = (str) => {
43
- if (typeof str !== "string")
44
- return false;
45
- if (!str || !str.startsWith(urlPrefix))
78
+ if (typeof str !== "string" || !str || !str.startsWith(urlPrefix))
46
79
  return false;
47
- const automergeUrl = str;
48
80
  try {
49
- const { documentId } = parseAutomergeUrl(automergeUrl);
50
- return isValidDocumentId(documentId);
81
+ const { documentId, heads } = parseAutomergeUrl(str);
82
+ if (!isValidDocumentId(documentId))
83
+ return false;
84
+ if (heads &&
85
+ !heads.every(head => {
86
+ try {
87
+ bs58check.decode(head);
88
+ return true;
89
+ }
90
+ catch {
91
+ return false;
92
+ }
93
+ }))
94
+ return false;
95
+ return true;
51
96
  }
52
97
  catch {
53
98
  return false;
@@ -74,6 +119,8 @@ export const generateAutomergeUrl = () => {
74
119
  };
75
120
  export const documentIdToBinary = (docId) => bs58check.decodeUnsafe(docId);
76
121
  export const binaryToDocumentId = (docId) => bs58check.encode(docId);
122
+ export const encodeHeads = (heads) => heads.map(h => bs58check.encode(uint8ArrayFromHexString(h)));
123
+ export const decodeHeads = (heads) => heads.map(h => uint8ArrayToHexString(bs58check.decode(h)));
77
124
  export const parseLegacyUUID = (str) => {
78
125
  if (!Uuid.validate(str))
79
126
  return undefined;
@@ -1,6 +1,6 @@
1
1
  import * as A from "@automerge/automerge/slim/next";
2
2
  import { EventEmitter } from "eventemitter3";
3
- import type { AutomergeUrl, DocumentId, PeerId } from "./types.js";
3
+ import type { AutomergeUrl, DocumentId, PeerId, UrlHeads } from "./types.js";
4
4
  import { StorageId } from "./storage/types.js";
5
5
  /**
6
6
  * A DocHandle is a wrapper around a single Automerge document that lets us listen for changes and
@@ -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)
@@ -85,7 +92,61 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
85
92
  * This precisely defines the state of a document.
86
93
  * @returns the current document's heads, or undefined if the document is not ready
87
94
  */
88
- heads(): A.Heads | undefined;
95
+ heads(): UrlHeads | undefined;
96
+ begin(): void;
97
+ /**
98
+ * Returns an array of all past "heads" for the document in topological order.
99
+ *
100
+ * @remarks
101
+ * A point-in-time in an automerge document is an *array* of heads since there may be
102
+ * concurrent edits. This API just returns a topologically sorted history of all edits
103
+ * so every previous entry will be (in some sense) before later ones, but the set of all possible
104
+ * history views would be quite large under concurrency (every thing in each branch against each other).
105
+ * There might be a clever way to think about this, but we haven't found it yet, so for now at least
106
+ * we present a single traversable view which excludes concurrency.
107
+ * @returns UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].
108
+ */
109
+ history(): UrlHeads[] | undefined;
110
+ /**
111
+ * Creates a new DocHandle with a fixed "view" at the given point in time represented
112
+ * by the `heads` passed in. The return value is the same type as docSync() and will return
113
+ * undefined if the object hasn't finished loading.
114
+ *
115
+ * @remarks
116
+ * Note that our Typescript types do not consider change over time and the current version
117
+ * of Automerge doesn't check types at runtime, so if you go back to an old set of heads
118
+ * that doesn't match the heads here, Typescript will not save you.
119
+ *
120
+ * @argument heads - The heads to view the document at. See history().
121
+ * @returns DocHandle<T> at the time of `heads`
122
+ */
123
+ view(heads: UrlHeads): DocHandle<T>;
124
+ /**
125
+ * Returns a set of Patch operations that will move a materialized document from one state to another
126
+ * if applied.
127
+ *
128
+ * @remarks
129
+ * We allow specifying either:
130
+ * - Two sets of heads to compare directly
131
+ * - A single set of heads to compare against our current heads
132
+ * - Another DocHandle to compare against (which must share history with this document)
133
+ *
134
+ * @throws Error if the documents don't share history or if either document is not ready
135
+ * @returns Automerge patches that go from one document state to the other
136
+ */
137
+ diff(first: UrlHeads | DocHandle<T>, second?: UrlHeads): A.Patch[];
138
+ /**
139
+ * `metadata(head?)` allows you to look at the metadata for a change
140
+ * this can be used to build history graphs to find commit messages and edit times.
141
+ * this interface.
142
+ *
143
+ * @remarks
144
+ * I'm really not convinced this is the right way to surface this information so
145
+ * I'm leaving this API "hidden".
146
+ *
147
+ * @hidden
148
+ */
149
+ metadata(change?: string): A.DecodedChange | undefined;
89
150
  /**
90
151
  * `update` is called any time we have a new document state; could be
91
152
  * from a local change, a remote change, or a new document from storage.
@@ -103,9 +164,9 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
103
164
  * Called by the repo either when a doc handle changes or we receive new remote heads.
104
165
  * @hidden
105
166
  */
106
- setRemoteHeads(storageId: StorageId, heads: A.Heads): void;
167
+ setRemoteHeads(storageId: StorageId, heads: UrlHeads): void;
107
168
  /** Returns the heads of the storageId. */
108
- getRemoteHeads(storageId: StorageId): A.Heads | undefined;
169
+ getRemoteHeads(storageId: StorageId): UrlHeads | undefined;
109
170
  /**
110
171
  * All changes to an Automerge document should be made through this method.
111
172
  * Inside the callback, the document should be treated as mutable: all edits will be recorded
@@ -127,7 +188,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
127
188
  *
128
189
  * @returns A set of heads representing the concurrent change that was made.
129
190
  */
130
- changeAt(heads: A.Heads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): string[] | undefined;
191
+ changeAt(heads: UrlHeads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): UrlHeads[] | undefined;
131
192
  /**
132
193
  * Merges another document into this document. Any peers we are sharing changes with will be
133
194
  * notified of the changes resulting from the merge.
@@ -148,6 +209,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
148
209
  * @hidden
149
210
  * */
150
211
  request(): void;
212
+ /** Called by the repo to free memory used by the document. */
213
+ unload(): void;
214
+ /** Called by the repo to reuse an unloaded handle. */
215
+ reload(): void;
151
216
  /** Called by the repo when the document is deleted. */
152
217
  delete(): void;
153
218
  /**
@@ -158,6 +223,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
158
223
  * must have a unique PeerId.
159
224
  */
160
225
  broadcast(message: unknown): void;
226
+ metrics(): {
227
+ numOps: number;
228
+ numChanges: number;
229
+ };
161
230
  }
162
231
  /** @hidden */
163
232
  export type DocHandleOptions<T> = {
@@ -167,6 +236,7 @@ export type DocHandleOptions<T> = {
167
236
  initialValue?: T;
168
237
  } | {
169
238
  isNew?: false;
239
+ heads?: UrlHeads;
170
240
  /** The number of milliseconds before we mark this document as unavailable if we don't have it and nobody shares it with us. */
171
241
  timeoutDelay?: number;
172
242
  };
@@ -218,7 +288,7 @@ export interface DocHandleOutboundEphemeralMessagePayload<T> {
218
288
  /** Emitted when we have new remote heads for this document */
219
289
  export interface DocHandleRemoteHeadsPayload {
220
290
  storageId: StorageId;
221
- heads: A.Heads;
291
+ heads: UrlHeads;
222
292
  }
223
293
  /**
224
294
  * Possible internal states for a DocHandle
@@ -232,11 +302,13 @@ export declare const HandleState: {
232
302
  readonly REQUESTING: "requesting";
233
303
  /** The document is available */
234
304
  readonly READY: "ready";
305
+ /** The document has been unloaded from the handle, to free memory usage */
306
+ readonly UNLOADED: "unloaded";
235
307
  /** The document has been deleted from the repo */
236
308
  readonly DELETED: "deleted";
237
309
  /** The document was not available in storage or from any connected peers */
238
310
  readonly UNAVAILABLE: "unavailable";
239
311
  };
240
312
  export type HandleState = (typeof HandleState)[keyof typeof HandleState];
241
- export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", DELETED: "deleted", UNAVAILABLE: "unavailable";
313
+ export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", UNLOADED: "unloaded", DELETED: "deleted", UNAVAILABLE: "unavailable";
242
314
  //# 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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"}