@fluidframework/id-compressor 2.0.0-dev-rc.1.0.0.228517 → 2.0.0-dev-rc.2.0.0.245554

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 (264) hide show
  1. package/{.eslintrc.js → .eslintrc.cjs} +5 -5
  2. package/{.mocharc.js → .mocharc.cjs} +1 -1
  3. package/CHANGELOG.md +8 -0
  4. package/{api-extractor-esm.json → api-extractor-cjs.json} +5 -1
  5. package/api-extractor-lint.json +1 -1
  6. package/api-extractor.json +1 -1
  7. package/api-report/id-compressor.api.md +5 -42
  8. package/dist/finalSpace.d.ts +2 -2
  9. package/dist/finalSpace.d.ts.map +1 -1
  10. package/dist/finalSpace.js +4 -4
  11. package/dist/finalSpace.js.map +1 -1
  12. package/dist/id-compressor-alpha.d.ts +117 -112
  13. package/dist/id-compressor-beta.d.ts +84 -77
  14. package/dist/id-compressor-public.d.ts +84 -77
  15. package/dist/id-compressor-untrimmed.d.ts +117 -112
  16. package/dist/idCompressor.d.ts +15 -19
  17. package/dist/idCompressor.d.ts.map +1 -1
  18. package/dist/idCompressor.js +107 -94
  19. package/dist/idCompressor.js.map +1 -1
  20. package/dist/identifiers.d.ts +1 -1
  21. package/dist/identifiers.d.ts.map +1 -1
  22. package/dist/identifiers.js.map +1 -1
  23. package/dist/index.d.ts +3 -3
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +9 -10
  26. package/dist/index.js.map +1 -1
  27. package/dist/package.json +3 -0
  28. package/dist/packageVersion.d.ts +1 -1
  29. package/dist/packageVersion.js +1 -1
  30. package/dist/packageVersion.js.map +1 -1
  31. package/dist/persistanceUtilities.d.ts +1 -1
  32. package/dist/persistanceUtilities.d.ts.map +1 -1
  33. package/dist/persistanceUtilities.js.map +1 -1
  34. package/dist/sessionSpaceNormalizer.d.ts +2 -2
  35. package/dist/sessionSpaceNormalizer.d.ts.map +1 -1
  36. package/dist/sessionSpaceNormalizer.js +4 -4
  37. package/dist/sessionSpaceNormalizer.js.map +1 -1
  38. package/dist/sessions.d.ts +2 -2
  39. package/dist/sessions.d.ts.map +1 -1
  40. package/dist/sessions.js +12 -12
  41. package/dist/sessions.js.map +1 -1
  42. package/dist/test/appendOnlySortedMap.perf.spec.d.ts +6 -0
  43. package/dist/test/appendOnlySortedMap.perf.spec.d.ts.map +1 -0
  44. package/dist/test/appendOnlySortedMap.perf.spec.js.map +1 -0
  45. package/dist/test/appendOnlySortedMap.spec.d.ts +6 -0
  46. package/dist/test/appendOnlySortedMap.spec.d.ts.map +1 -0
  47. package/dist/test/appendOnlySortedMap.spec.js.map +1 -0
  48. package/dist/test/idCompressor.perf.spec.d.ts +6 -0
  49. package/dist/test/idCompressor.perf.spec.d.ts.map +1 -0
  50. package/dist/test/idCompressor.perf.spec.js.map +1 -0
  51. package/dist/test/idCompressor.spec.d.ts +6 -0
  52. package/dist/test/idCompressor.spec.d.ts.map +1 -0
  53. package/dist/test/idCompressor.spec.js.map +1 -0
  54. package/dist/test/idCompressorTestUtilities.d.ts +245 -0
  55. package/dist/test/idCompressorTestUtilities.d.ts.map +1 -0
  56. package/dist/test/idCompressorTestUtilities.js +589 -0
  57. package/dist/test/idCompressorTestUtilities.js.map +1 -0
  58. package/dist/test/index.d.ts +9 -0
  59. package/dist/test/index.d.ts.map +1 -0
  60. package/dist/test/index.js +13 -0
  61. package/dist/test/index.js.map +1 -0
  62. package/dist/test/numericUuid.spec.d.ts +6 -0
  63. package/dist/test/numericUuid.spec.d.ts.map +1 -0
  64. package/dist/test/numericUuid.spec.js.map +1 -0
  65. package/dist/test/sessionSpaceNormalizer.spec.d.ts +6 -0
  66. package/dist/test/sessionSpaceNormalizer.spec.d.ts.map +1 -0
  67. package/dist/test/sessionSpaceNormalizer.spec.js.map +1 -0
  68. package/dist/test/snapshots/dirname.cjs +16 -0
  69. package/dist/test/snapshots/dirname.cjs.map +1 -0
  70. package/dist/test/snapshots/dirname.d.cts +6 -0
  71. package/dist/test/snapshots/dirname.d.cts.map +1 -0
  72. package/{lib/types/idCompressor.mjs → dist/test/snapshots/summary.spec.d.ts} +1 -1
  73. package/dist/test/snapshots/summary.spec.d.ts.map +1 -0
  74. package/dist/test/snapshots/summary.spec.js.map +1 -0
  75. package/dist/test/testCommon.d.ts +90 -0
  76. package/dist/test/testCommon.d.ts.map +1 -0
  77. package/dist/test/testCommon.js +90 -0
  78. package/dist/test/testCommon.js.map +1 -0
  79. package/dist/tsdoc-metadata.json +1 -1
  80. package/dist/types/idCompressor.d.ts +134 -67
  81. package/dist/types/idCompressor.d.ts.map +1 -1
  82. package/dist/types/idCompressor.js.map +1 -1
  83. package/dist/types/index.d.ts +3 -3
  84. package/dist/types/index.d.ts.map +1 -1
  85. package/dist/types/index.js.map +1 -1
  86. package/dist/types/persisted-types/0.0.1.d.ts +1 -1
  87. package/dist/types/persisted-types/0.0.1.d.ts.map +1 -1
  88. package/dist/types/persisted-types/0.0.1.js.map +1 -1
  89. package/dist/types/persisted-types/index.d.ts +1 -1
  90. package/dist/types/persisted-types/index.d.ts.map +1 -1
  91. package/dist/types/persisted-types/index.js.map +1 -1
  92. package/dist/utilities.d.ts +2 -2
  93. package/dist/utilities.d.ts.map +1 -1
  94. package/dist/utilities.js.map +1 -1
  95. package/lib/{appendOnlySortedMap.d.mts → appendOnlySortedMap.d.ts} +1 -1
  96. package/lib/appendOnlySortedMap.d.ts.map +1 -0
  97. package/lib/{appendOnlySortedMap.mjs → appendOnlySortedMap.js} +3 -1
  98. package/lib/appendOnlySortedMap.js.map +1 -0
  99. package/lib/{finalSpace.d.mts → finalSpace.d.ts} +3 -3
  100. package/lib/finalSpace.d.ts.map +1 -0
  101. package/lib/{finalSpace.mjs → finalSpace.js} +2 -2
  102. package/lib/finalSpace.js.map +1 -0
  103. package/lib/{id-compressor-alpha.d.mts → id-compressor-alpha.d.ts} +117 -112
  104. package/lib/id-compressor-beta.d.ts +179 -0
  105. package/lib/id-compressor-public.d.ts +179 -0
  106. package/lib/{id-compressor-untrimmed.d.mts → id-compressor-untrimmed.d.ts} +117 -112
  107. package/lib/{idCompressor.d.mts → idCompressor.d.ts} +16 -20
  108. package/lib/idCompressor.d.ts.map +1 -0
  109. package/lib/{idCompressor.mjs → idCompressor.js} +54 -41
  110. package/lib/idCompressor.js.map +1 -0
  111. package/lib/{identifiers.d.mts → identifiers.d.ts} +2 -2
  112. package/lib/identifiers.d.ts.map +1 -0
  113. package/lib/{identifiers.mjs → identifiers.js} +1 -1
  114. package/lib/identifiers.js.map +1 -0
  115. package/lib/{index.d.mts → index.d.ts} +7 -4
  116. package/lib/index.d.ts.map +1 -0
  117. package/lib/index.js +10 -0
  118. package/lib/index.js.map +1 -0
  119. package/lib/{packageVersion.d.mts → packageVersion.d.ts} +2 -2
  120. package/lib/packageVersion.d.ts.map +1 -0
  121. package/lib/{packageVersion.mjs → packageVersion.js} +2 -2
  122. package/lib/packageVersion.js.map +1 -0
  123. package/lib/{persistanceUtilities.d.mts → persistanceUtilities.d.ts} +2 -2
  124. package/lib/persistanceUtilities.d.ts.map +1 -0
  125. package/lib/{persistanceUtilities.mjs → persistanceUtilities.js} +1 -1
  126. package/lib/persistanceUtilities.js.map +1 -0
  127. package/lib/{sessionSpaceNormalizer.d.mts → sessionSpaceNormalizer.d.ts} +3 -3
  128. package/lib/sessionSpaceNormalizer.d.ts.map +1 -0
  129. package/lib/{sessionSpaceNormalizer.mjs → sessionSpaceNormalizer.js} +3 -3
  130. package/lib/sessionSpaceNormalizer.js.map +1 -0
  131. package/lib/{sessions.d.mts → sessions.d.ts} +3 -3
  132. package/lib/sessions.d.ts.map +1 -0
  133. package/lib/{sessions.mjs → sessions.js} +2 -2
  134. package/lib/sessions.js.map +1 -0
  135. package/lib/test/appendOnlySortedMap.perf.spec.d.ts +6 -0
  136. package/lib/test/appendOnlySortedMap.perf.spec.d.ts.map +1 -0
  137. package/lib/test/appendOnlySortedMap.perf.spec.js +49 -0
  138. package/lib/test/appendOnlySortedMap.perf.spec.js.map +1 -0
  139. package/lib/test/appendOnlySortedMap.spec.d.ts +6 -0
  140. package/lib/test/appendOnlySortedMap.spec.d.ts.map +1 -0
  141. package/lib/test/appendOnlySortedMap.spec.js +166 -0
  142. package/lib/test/appendOnlySortedMap.spec.js.map +1 -0
  143. package/lib/test/idCompressor.perf.spec.d.ts +6 -0
  144. package/lib/test/idCompressor.perf.spec.d.ts.map +1 -0
  145. package/lib/test/idCompressor.perf.spec.js +281 -0
  146. package/lib/test/idCompressor.perf.spec.js.map +1 -0
  147. package/lib/test/idCompressor.spec.d.ts +6 -0
  148. package/lib/test/idCompressor.spec.d.ts.map +1 -0
  149. package/lib/test/idCompressor.spec.js +953 -0
  150. package/lib/test/idCompressor.spec.js.map +1 -0
  151. package/lib/test/idCompressorTestUtilities.d.ts +245 -0
  152. package/lib/test/idCompressorTestUtilities.d.ts.map +1 -0
  153. package/lib/test/idCompressorTestUtilities.js +576 -0
  154. package/lib/test/idCompressorTestUtilities.js.map +1 -0
  155. package/lib/test/index.d.ts +9 -0
  156. package/lib/test/index.d.ts.map +1 -0
  157. package/lib/test/index.js +9 -0
  158. package/lib/test/index.js.map +1 -0
  159. package/lib/test/numericUuid.spec.d.ts +6 -0
  160. package/lib/test/numericUuid.spec.d.ts.map +1 -0
  161. package/lib/test/numericUuid.spec.js +74 -0
  162. package/lib/test/numericUuid.spec.js.map +1 -0
  163. package/lib/test/sessionSpaceNormalizer.spec.d.ts +6 -0
  164. package/lib/test/sessionSpaceNormalizer.spec.d.ts.map +1 -0
  165. package/lib/test/sessionSpaceNormalizer.spec.js +43 -0
  166. package/lib/test/sessionSpaceNormalizer.spec.js.map +1 -0
  167. package/lib/test/snapshots/dirname.cjs +16 -0
  168. package/lib/test/snapshots/dirname.cjs.map +1 -0
  169. package/lib/test/snapshots/dirname.d.cts +6 -0
  170. package/lib/test/snapshots/dirname.d.cts.map +1 -0
  171. package/lib/test/snapshots/summary.spec.d.ts +6 -0
  172. package/lib/test/snapshots/summary.spec.d.ts.map +1 -0
  173. package/lib/test/snapshots/summary.spec.js +127 -0
  174. package/lib/test/snapshots/summary.spec.js.map +1 -0
  175. package/lib/test/testCommon.d.ts +90 -0
  176. package/lib/test/testCommon.d.ts.map +1 -0
  177. package/lib/test/testCommon.js +80 -0
  178. package/lib/test/testCommon.js.map +1 -0
  179. package/lib/types/{idCompressor.d.mts → idCompressor.d.ts} +135 -68
  180. package/lib/types/idCompressor.d.ts.map +1 -0
  181. package/lib/types/{identifiers.mjs → idCompressor.js} +1 -1
  182. package/lib/types/idCompressor.js.map +1 -0
  183. package/lib/types/{identifiers.d.mts → identifiers.d.ts} +1 -1
  184. package/lib/types/identifiers.d.ts.map +1 -0
  185. package/lib/types/identifiers.js +6 -0
  186. package/lib/types/identifiers.js.map +1 -0
  187. package/lib/types/{index.d.mts → index.d.ts} +4 -4
  188. package/lib/types/index.d.ts.map +1 -0
  189. package/lib/types/{persisted-types/0.0.1.mjs → index.js} +1 -1
  190. package/lib/types/index.js.map +1 -0
  191. package/lib/types/persisted-types/{0.0.1.d.mts → 0.0.1.d.ts} +2 -2
  192. package/lib/types/persisted-types/0.0.1.d.ts.map +1 -0
  193. package/lib/types/persisted-types/{index.mjs → 0.0.1.js} +1 -1
  194. package/lib/types/persisted-types/0.0.1.js.map +1 -0
  195. package/lib/types/persisted-types/{index.d.mts → index.d.ts} +2 -2
  196. package/lib/types/persisted-types/index.d.ts.map +1 -0
  197. package/lib/types/{index.mjs → persisted-types/index.js} +1 -1
  198. package/lib/types/persisted-types/index.js.map +1 -0
  199. package/lib/{utilities.d.mts → utilities.d.ts} +3 -3
  200. package/lib/utilities.d.ts.map +1 -0
  201. package/lib/{utilities.mjs → utilities.js} +2 -1
  202. package/lib/utilities.js.map +1 -0
  203. package/package.json +88 -21
  204. package/src/finalSpace.ts +2 -2
  205. package/src/idCompressor.ts +75 -59
  206. package/src/identifiers.ts +1 -1
  207. package/src/index.ts +3 -3
  208. package/src/packageVersion.ts +1 -1
  209. package/src/persistanceUtilities.ts +1 -1
  210. package/src/sessionSpaceNormalizer.ts +3 -3
  211. package/src/sessions.ts +3 -3
  212. package/src/test/idCompressorTestUtilities.ts +921 -0
  213. package/src/test/index.ts +10 -0
  214. package/src/test/snapshots/dirname.cts +13 -0
  215. package/src/test/snapshots/files/compressor-with-finalized-range-from-one-client +1 -0
  216. package/src/test/snapshots/files/compressor-with-finalized-range-from-one-client-client2 +1 -0
  217. package/src/test/snapshots/files/compressors-with-finalized-ranges-from-two-clients +1 -0
  218. package/src/test/snapshots/files/compressors-with-finalized-ranges-from-two-clients-client2 +1 -0
  219. package/src/test/snapshots/files/empty-compressor-summary +1 -0
  220. package/src/test/snapshots/files/expansion-semantics +1 -0
  221. package/src/test/snapshots/files/expansion-semantics-client2 +1 -0
  222. package/src/test/testCommon.ts +143 -0
  223. package/src/test/tsconfig.cjs.json +12 -0
  224. package/src/test/tsconfig.json +20 -0
  225. package/src/types/idCompressor.ts +147 -72
  226. package/src/types/index.ts +8 -3
  227. package/src/types/persisted-types/0.0.1.ts +1 -1
  228. package/src/types/persisted-types/index.ts +1 -1
  229. package/src/utilities.ts +2 -2
  230. package/tsconfig.cjs.json +7 -0
  231. package/tsconfig.json +2 -5
  232. package/lib/appendOnlySortedMap.d.mts.map +0 -1
  233. package/lib/appendOnlySortedMap.mjs.map +0 -1
  234. package/lib/finalSpace.d.mts.map +0 -1
  235. package/lib/finalSpace.mjs.map +0 -1
  236. package/lib/id-compressor-beta.d.mts +0 -172
  237. package/lib/id-compressor-public.d.mts +0 -172
  238. package/lib/idCompressor.d.mts.map +0 -1
  239. package/lib/idCompressor.mjs.map +0 -1
  240. package/lib/identifiers.d.mts.map +0 -1
  241. package/lib/identifiers.mjs.map +0 -1
  242. package/lib/index.d.mts.map +0 -1
  243. package/lib/index.mjs +0 -7
  244. package/lib/index.mjs.map +0 -1
  245. package/lib/packageVersion.d.mts.map +0 -1
  246. package/lib/packageVersion.mjs.map +0 -1
  247. package/lib/persistanceUtilities.d.mts.map +0 -1
  248. package/lib/persistanceUtilities.mjs.map +0 -1
  249. package/lib/sessionSpaceNormalizer.d.mts.map +0 -1
  250. package/lib/sessionSpaceNormalizer.mjs.map +0 -1
  251. package/lib/sessions.d.mts.map +0 -1
  252. package/lib/sessions.mjs.map +0 -1
  253. package/lib/types/idCompressor.d.mts.map +0 -1
  254. package/lib/types/idCompressor.mjs.map +0 -1
  255. package/lib/types/identifiers.d.mts.map +0 -1
  256. package/lib/types/identifiers.mjs.map +0 -1
  257. package/lib/types/index.d.mts.map +0 -1
  258. package/lib/types/index.mjs.map +0 -1
  259. package/lib/types/persisted-types/0.0.1.d.mts.map +0 -1
  260. package/lib/types/persisted-types/0.0.1.mjs.map +0 -1
  261. package/lib/types/persisted-types/index.d.mts.map +0 -1
  262. package/lib/types/persisted-types/index.mjs.map +0 -1
  263. package/lib/utilities.d.mts.map +0 -1
  264. package/lib/utilities.mjs.map +0 -1
@@ -1,4 +1,5 @@
1
1
  import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
2
+ import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
2
3
 
3
4
  /**
4
5
  * Asserts that the given string is a stable ID.
@@ -29,13 +30,13 @@ export declare function createSessionId(): SessionId;
29
30
  * Deserializes the supplied state into an ID compressor.
30
31
  * @alpha
31
32
  */
32
- export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession): IIdCompressor & IIdCompressorCore;
33
+ export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession, logger?: ITelemetryLoggerExt): IIdCompressor & IIdCompressorCore;
33
34
 
34
35
  /**
35
36
  * Deserializes the supplied state into an ID compressor.
36
37
  * @alpha
37
38
  */
38
- export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IIdCompressor & IIdCompressorCore;
39
+ export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId, logger?: ITelemetryLoggerExt): IIdCompressor & IIdCompressorCore;
39
40
 
40
41
  /**
41
42
  * Generate a random stable ID
@@ -43,69 +44,6 @@ export declare function deserializeIdCompressor(serialized: SerializedIdCompress
43
44
  */
44
45
  export declare function generateStableId(): StableId;
45
46
 
46
- /**
47
- * See {@link IIdCompressor} and {@link IIdCompressorCore}
48
- *
49
- * @alpha
50
- *
51
- * @deprecated Not intended for public use and will be removed from the public API in the future.
52
- * Use `createIdCompressor` instead.
53
- */
54
- export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
55
- private readonly logger?;
56
- /**
57
- * Max allowed initial cluster size.
58
- */
59
- static readonly maxClusterSize: number;
60
- readonly localSessionId: SessionId;
61
- private readonly localSession;
62
- private readonly normalizer;
63
- private localGenCount;
64
- private nextRangeBaseGenCount;
65
- private readonly sessions;
66
- private readonly finalSpace;
67
- /**
68
- * Roughly equates to a minimum of 1M sessions before we start allocating 64 bit IDs.
69
- * Eventually, this can be adjusted dynamically to have cluster reservation policies that
70
- * optimize the number of eager finals.
71
- * It is not readonly as it is accessed by tests for clear-box testing.
72
- */
73
- private nextRequestedClusterSize;
74
- private telemetryLocalIdCount;
75
- private telemetryEagerFinalIdCount;
76
- private ongoingGhostSession?;
77
- private constructor();
78
- /**
79
- * @deprecated Use `createIdCompressor` instead.
80
- */
81
- static create(logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
82
- /**
83
- * @deprecated Use `createIdCompressor` instead.
84
- */
85
- static create(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
86
- generateCompressedId(): SessionSpaceCompressedId;
87
- /**
88
- * {@inheritdoc IIdCompressorCore.beginGhostSession}
89
- */
90
- beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;
91
- private generateNextLocalId;
92
- takeNextCreationRange(): IdCreationRange;
93
- private static assertValidRange;
94
- finalizeCreationRange(range: IdCreationRange): void;
95
- private addEmptyCluster;
96
- normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
97
- normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
98
- decompress(id: SessionSpaceCompressedId): StableId;
99
- recompress(uncompressed: StableId): SessionSpaceCompressedId;
100
- tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
101
- serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
102
- serialize(withSession: false): SerializedIdCompressorWithNoSession;
103
- static deserialize(serialized: SerializedIdCompressorWithOngoingSession): IdCompressor;
104
- static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IdCompressor;
105
- private static deserialize2_0;
106
- equals(other: IdCompressor, includeLocalState: boolean): boolean;
107
- }
108
-
109
47
  /**
110
48
  * Data describing a range of session-local IDs (from a remote or local session).
111
49
  *
@@ -132,6 +70,120 @@ export declare interface IdCreationRange {
132
70
  };
133
71
  }
134
72
 
73
+ /**
74
+ * A distributed UUID generator and compressor.
75
+ * `IdCompressor` offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers
76
+ * for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.
77
+ *
78
+ * The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently.
79
+ * IDs generated by a compressor, via calls to `generateCompressedId`, are created in the compressor's "local" session.
80
+ * These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session
81
+ * is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated
82
+ * through a process called "normalization":
83
+ * - The scope of a local session (in which local IDs are unique) is called the "session space" of the client.
84
+ * - The context of persisted state (in Fluid, this is the context of ops and summaries) is called "op space".
85
+ * - `SessionSpaceCompressedId`s, generated via calls to `generateCompressedId`, should NEVER be serialized directly.
86
+ * In Fluid, this means they should not be included in ops or summaries.
87
+ * - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients.
88
+ * - Upon receipt, IDs should be normalized back to session space before use.
89
+ *
90
+ * Example Usage:
91
+ *
92
+ * ### Client A (Sender)
93
+ *
94
+ * ```typescript
95
+ * // Generate several local IDs
96
+ * const localId1 = idCompressor.generateCompressedId();
97
+ * const localId2 = idCompressor.generateCompressedId();
98
+ * const localId3 = idCompressor.generateCompressedId();
99
+ *
100
+ * // Normalize these IDs to op space for inclusion in a message
101
+ * const opSpaceId1 = idCompressor.normalizeToOpSpace(localId1);
102
+ * const opSpaceId2 = idCompressor.normalizeToOpSpace(localId2);
103
+ * const opSpaceId3 = idCompressor.normalizeToOpSpace(localId3);
104
+ *
105
+ * // Create and send a message containing these op space IDs along with the sender's session ID
106
+ * // In Fluid, this would be an op or summary
107
+ * const message = {
108
+ * sessionID: idCompressor.localSessionId,
109
+ * ids: [opSpaceId1, opSpaceId2, opSpaceId3]
110
+ * };
111
+ * ```
112
+ *
113
+ * ### Client B (Receiver)
114
+ *
115
+ * ```typescript
116
+ * // Receive the message from Client A
117
+ * const receivedMessage = ...; // In Fluid, this would be an op or summary
118
+ *
119
+ * // Normalize the received IDs back to session space, utilizing the sender's session ID
120
+ * const sessionSpaceId1 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[0], receivedMessage.sessionID);
121
+ * const sessionSpaceId2 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[1], receivedMessage.sessionID);
122
+ * const sessionSpaceId3 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[2], receivedMessage.sessionID);
123
+ * ```
124
+ * @public
125
+ */
126
+ export declare interface IIdCompressor {
127
+ /**
128
+ * The local session ID.
129
+ */
130
+ localSessionId: SessionId;
131
+ /**
132
+ * Generates a new compressed ID.
133
+ * The returned ID is in session space and should not be serialized directly. See `IIdCompressor` for more details.
134
+ * @returns A new local ID in session space.
135
+ */
136
+ generateCompressedId(): SessionSpaceCompressedId;
137
+ /**
138
+ * Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any
139
+ * normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).
140
+ * In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probably in
141
+ * scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and
142
+ * this approach will often be superior to generating a UUID.
143
+ * If small numbers are a requirement, `generateCompressedId` and normalization should be used instead.
144
+ * See `IIdCompressor` for more details.
145
+ * @returns A new local ID in session space.
146
+ */
147
+ generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;
148
+ /**
149
+ * Normalizes a session space ID into op space.
150
+ * The returned ID is in op space and can be safely serialized. However, it should be normalized back to session space before use.
151
+ * See `IIdCompressor` for more details.
152
+ * @param id - The local ID to normalize.
153
+ * @returns The ID in op space.
154
+ */
155
+ normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
156
+ /**
157
+ * Normalizes an ID into session space.
158
+ * @param id - The ID to normalize.
159
+ * @param originSessionId - The session from which `id` originated. This should be the ID of the client that normalized `id` to op space.
160
+ * This means that it may not be the client that created `id` in the first place, but rather the client that serialized it.
161
+ * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.
162
+ * @returns The session-space ID in the local session corresponding to `id`.
163
+ */
164
+ normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
165
+ /**
166
+ * Decompresses a previously compressed ID into a UUID.
167
+ * @param id - The compressed ID to be decompressed.
168
+ * @returns The UUID associated with the compressed ID.
169
+ * @throws If the ID was not generated by any session known to this compressor.
170
+ */
171
+ decompress(id: SessionSpaceCompressedId): StableId;
172
+ /**
173
+ * Recompresses a UUID.
174
+ * @param uncompressed - The UUID to recompress.
175
+ * @returns The `CompressedId` associated with `uncompressed`.
176
+ * @throws If the UUID was not generated by any session known to this compressor.
177
+ */
178
+ recompress(uncompressed: StableId): SessionSpaceCompressedId;
179
+ /**
180
+ * Attempts to recompress a UUID.
181
+ * @param uncompressed - The UUID to recompress.
182
+ * @returns The `CompressedId` associated with `uncompressed` or undefined if the UUID was not generated by any session known to this compressor.
183
+ */
184
+ tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
185
+ }
186
+
135
187
  /**
136
188
  * A distributed UUID generator and compressor.
137
189
  *
@@ -192,53 +244,6 @@ export declare interface IdCreationRange {
192
244
  *
193
245
  * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops
194
246
  * should use op-space IDs.
195
- * @public
196
- */
197
- export declare interface IIdCompressor {
198
- localSessionId: SessionId;
199
- /**
200
- * Generates a new compressed ID or returns an existing one.
201
- * This should ONLY be called to generate IDs for local operations.
202
- * @returns A new local ID in session space.
203
- */
204
- generateCompressedId(): SessionSpaceCompressedId;
205
- /**
206
- * Normalizes a session space ID into op space.
207
- * @param id - the local ID to normalize.
208
- * @returns the ID in op space.
209
- */
210
- normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
211
- /**
212
- * Normalizes an ID into session space.
213
- * @param id - the ID to normalize. If it is a local ID, it is assumed to have been created by the session corresponding
214
- * to `sessionId`.
215
- * @param originSessionId - the session from which `id` originated
216
- * @returns the session-space ID corresponding to `id`, which might not have been a final ID if the client that created it had not yet
217
- * finalized it. This can occur when a client references an ID during the window of time in which it is waiting to receive the ordered
218
- * range that contained it from the server.
219
- */
220
- normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
221
- /**
222
- * Decompresses a previously compressed ID into a UUID.
223
- * @param id - the compressed ID to be decompressed.
224
- * @returns the UUID associated with the compressed ID. Fails if the ID was not generated by this compressor.
225
- */
226
- decompress(id: SessionSpaceCompressedId): StableId;
227
- /**
228
- * Recompresses a UUID.
229
- * @param uncompressed - the UUID to recompress.
230
- * @returns the `CompressedId` associated with `uncompressed`. Fails if it has not been previously compressed by this compressor.
231
- */
232
- recompress(uncompressed: StableId): SessionSpaceCompressedId;
233
- /**
234
- * Attempts to recompresses a UUID.
235
- * @param uncompressed - the UUID to recompress,
236
- * @returns the `CompressedId` associated with `uncompressed` or undefined if it has not been previously compressed by this compressor.
237
- */
238
- tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
239
- }
240
-
241
- /**
242
247
  * @alpha
243
248
  */
244
249
  export declare interface IIdCompressorCore {
@@ -3,14 +3,12 @@
3
3
  * Licensed under the MIT License.
4
4
  */
5
5
  import { ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
6
- import { IdCreationRange, IIdCompressor, IIdCompressorCore, OpSpaceCompressedId, SerializedIdCompressorWithNoSession, SerializedIdCompressorWithOngoingSession, SessionId, SessionSpaceCompressedId, StableId } from "./types";
6
+ import { ITelemetryLoggerExt } from "@fluidframework/telemetry-utils";
7
+ import { IdCreationRange, IIdCompressor, IIdCompressorCore, OpSpaceCompressedId, SerializedIdCompressorWithNoSession, SerializedIdCompressorWithOngoingSession, SessionId, SessionSpaceCompressedId, StableId } from "./types/index.js";
8
+ import { Index } from "./persistanceUtilities.js";
9
+ import { Sessions } from "./sessions.js";
7
10
  /**
8
11
  * See {@link IIdCompressor} and {@link IIdCompressorCore}
9
- *
10
- * @alpha
11
- *
12
- * @deprecated Not intended for public use and will be removed from the public API in the future.
13
- * Use `createIdCompressor` instead.
14
12
  */
15
13
  export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
16
14
  private readonly logger?;
@@ -35,16 +33,14 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
35
33
  private telemetryLocalIdCount;
36
34
  private telemetryEagerFinalIdCount;
37
35
  private ongoingGhostSession?;
38
- private constructor();
39
- /**
40
- * @deprecated Use `createIdCompressor` instead.
41
- */
42
- static create(logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
36
+ constructor(localSessionIdOrDeserialized: SessionId | Sessions, logger?: ITelemetryLoggerExt | undefined);
37
+ generateCompressedId(): SessionSpaceCompressedId;
38
+ generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;
43
39
  /**
44
- * @deprecated Use `createIdCompressor` instead.
40
+ * Starts a ghost session. Only exposed for test purposes (this class is not exported from the package).
41
+ * @param ghostSessionId - The session ID to start the ghost session with.
45
42
  */
46
- static create(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
47
- generateCompressedId(): SessionSpaceCompressedId;
43
+ startGhostSession(ghostSessionId: SessionId): void;
48
44
  /**
49
45
  * {@inheritdoc IIdCompressorCore.beginGhostSession}
50
46
  */
@@ -61,9 +57,9 @@ export declare class IdCompressor implements IIdCompressor, IIdCompressorCore {
61
57
  tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
62
58
  serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
63
59
  serialize(withSession: false): SerializedIdCompressorWithNoSession;
64
- static deserialize(serialized: SerializedIdCompressorWithOngoingSession): IdCompressor;
65
- static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IdCompressor;
66
- private static deserialize2_0;
60
+ static deserialize(serialized: SerializedIdCompressorWithOngoingSession, logger?: ITelemetryLoggerExt): IdCompressor;
61
+ static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId, logger?: ITelemetryLoggerExt): IdCompressor;
62
+ static deserialize2_0(index: Index, sessionId?: SessionId, logger?: ITelemetryLoggerExt): IdCompressor;
67
63
  equals(other: IdCompressor, includeLocalState: boolean): boolean;
68
64
  }
69
65
  /**
@@ -81,10 +77,10 @@ export declare function createIdCompressor(sessionId: SessionId, logger?: ITelem
81
77
  * Deserializes the supplied state into an ID compressor.
82
78
  * @alpha
83
79
  */
84
- export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession): IIdCompressor & IIdCompressorCore;
80
+ export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession, logger?: ITelemetryLoggerExt): IIdCompressor & IIdCompressorCore;
85
81
  /**
86
82
  * Deserializes the supplied state into an ID compressor.
87
83
  * @alpha
88
84
  */
89
- export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IIdCompressor & IIdCompressorCore;
85
+ export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId, logger?: ITelemetryLoggerExt): IIdCompressor & IIdCompressorCore;
90
86
  //# sourceMappingURL=idCompressor.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"idCompressor.d.ts","sourceRoot":"","sources":["../src/idCompressor.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"idCompressor.d.ts","sourceRoot":"","sources":["../src/idCompressor.ts"],"names":[],"mappings":"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"}