@fluidframework/id-compressor 2.0.0-rc.1.0.4 → 2.0.0-rc.2.0.0

package/src/test/index.ts

@@ -0,0 +1,10 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Exports for test utilities for `id-compressor`
+ */
+
+export { createAlwaysFinalizedIdCompressor } from "./idCompressorTestUtilities.js";

package/src/test/snapshots/dirname.cts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// Problem:
+//   - `__dirname` is not defined in ESM
+//   - `import.meta.url` is not defined in CJS
+// Solution:
+//   - Export '__dirname' from a .cjs file in the same directory.
+//
+// Note that *.cjs files are always CommonJS, but can be imported from ESM.
+export const _dirname = __dirname;

package/src/test/snapshots/files/compressor-with-finalized-range-from-one-client

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAPA/AAAAAAAA8D/pXqCZfUEHBR2USVl4/AABAAAAAAAAAAAAAAAAAFCAQAAAAAAAACRA

package/src/test/snapshots/files/compressor-with-finalized-range-from-one-client-client2

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

package/src/test/snapshots/files/compressors-with-finalized-ranges-from-two-clients

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAEDpXqCZfUEHBR2USVl4/AAB3r8WOsPYt3ejBGppnQksAQAAAAAAAAAAAAAAAABQgEAAAAAAAAAkQAAAAAAAAPA/AAAAAABQgEAAAAAAAAAkQA==

package/src/test/snapshots/files/compressors-with-finalized-ranges-from-two-clients-client2

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAEDevxY6w9i3d6MEammdCSwB6V6gmX1BBwUdlElZePwAAQAAAAAAAPA/AAAAAABQgEAAAAAAAAAkQAAAAAAAAAAAAAAAAABQgEAAAAAAAAAkQA==

package/src/test/snapshots/files/empty-compressor-summary

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=

package/src/test/snapshots/files/expansion-semantics

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAPA/AAAAAAAA8D/pXqCZfUEHBR2USVl4/AABAAAAAAAAAAAAAAAAAAAYQAAAAAAAABBA

package/src/test/snapshots/files/expansion-semantics-client2

@@ -0,0 +1 @@
+AAAAAAAAAEAAAAAAAAAAAAAAAAAAAPA/AAAAAAAA8D/pXqCZfUEHBR2USVl4/AABAAAAAAAAAAAAAAAAAAAYQAAAAAAAABBA

package/src/test/testCommon.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils";
+import { SessionSpaceCompressedId, StableId, OpSpaceCompressedId } from "..//index.js";
+import {
+	numericUuidFromStableId,
+	offsetNumericUuid,
+	stableIdFromNumericUuid,
+} from "../utilities.js";
+import { IdCompressor } from "../idCompressor.js";
+
+/**
+ * An identifier (v4 UUID) that has been shortened by a distributed compression algorithm.
+ * Lacks a space (session/op), meaning its scope is the same as the space-specific ID from which it was derived.
+ * @alpha
+ */
+export type CompressedId =
+	| SessionSpaceCompressedId
+	| OpSpaceCompressedId
+	| FinalCompressedId
+	| LocalCompressedId;
+
+/**
+ * A compressed ID that is stable and unique within the scope of network of compressors (i.e. a document).
+ * It can only be used/decompressed in the context of the originating document.
+ * @alpha
+ */
+export type FinalCompressedId = number & {
+	readonly FinalCompressedId: "5d83d1e2-98b7-4e4e-a889-54c855cfa73d";
+
+	// Same brand as OpNormalizedCompressedId, as final IDs are always finally normalized
+	readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+};
+
+/**
+ * A compressed ID that is local to a session (can only be decompressed when paired with a SessionId).
+ * Internally, it should not be persisted outside a scope annotated with the originating SessionId in order to be unambiguous.
+ * If external persistence is needed (e.g. by a client), a StableId should be used instead.
+ * @alpha
+ */
+export type LocalCompressedId = number & {
+	readonly LocalCompressedId: "6fccb42f-e2a4-4243-bd29-f13d12b9c6d1";
+} & SessionSpaceCompressedId; // Same brand as CompressedId, as local IDs are always locally normalized
+
+/**
+ * @returns true if the supplied ID is a final ID.
+ */
+export function isFinalId(id: CompressedId): id is FinalCompressedId {
+	return id >= 0;
+}
+
+/**
+ * @returns true if the supplied ID is a local ID.
+ */
+export function isLocalId(id: CompressedId): id is LocalCompressedId {
+	return id < 0;
+}
+
+/**
+ * Turns a negative integer into a local compressed ID. For testing only.
+ */
+export function makeLocalId(negativeInteger: number): LocalCompressedId {
+	const id = negativeInteger as CompressedId;
+	assert(isLocalId(id), "Not a negative integer.");
+	return id;
+}
+
+/**
+ * Remove `readonly` from all fields.
+ */
+export type Mutable<T> = { -readonly [P in keyof T]: T[P] };
+
+/**
+ * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.
+ * @param map - The map to query/update
+ * @param key - The key to lookup in the map
+ * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists
+ * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)
+ */
+export function getOrCreate<K, V>(map: Map<K, V>, key: K, defaultValue: (key: K) => V): V {
+	let value = map.get(key);
+	if (value === undefined) {
+		value = defaultValue(key);
+		map.set(key, value);
+	}
+	return value;
+}
+
+export function incrementStableId(stableId: StableId, offset: number): StableId {
+	return stableIdFromNumericUuid(offsetNumericUuid(numericUuidFromStableId(stableId), offset));
+}
+
+/** An immutable view of an `IdCompressor` */
+export type ReadonlyIdCompressor = Omit<
+	IdCompressor,
+	| "generateCompressedId"
+	| "generateCompressedIdRange"
+	| "takeNextCreationRange"
+	| "finalizeCreationRange"
+>;
+
+/**
+ * Asserts a value is not undefined, and returns the value.
+ * Use when violations are logic errors in the program.
+ *
+ * @remarks
+ * When practical, prefer the pattern `x ?? fail('message')` over `assertNotUndefined(x, 'message')`.
+ * Using `?? fail` allows for message formatting without incurring the cost of formatting the message
+ * in the non failing case.
+ *
+ * Example:
+ * ```typescript
+ * x ?? fail(`x should exist for ${y}`)
+ * ```
+ *
+ * Additionally the `?? fail` avoids an extra call/stack frame in the non failing case.
+ *
+ * Another pattern to prefer over `assertNotUndefined(x, 'message')` is `assert(x !== undefined)`.
+ * This pattern is preferred because it is more general (same approach works with typeof, instance of,
+ * comparison to other values etc.).
+ *
+ * @param value - Value to assert against is non undefined.
+ * @param message - Message to be printed if assertion fails.
+ */
+export function assertNotUndefined<T>(
+	value: T | undefined,
+	message = "value must not be undefined",
+): T {
+	assert(value !== undefined, message);
+	return value;
+}
+
+/**
+ * Fails an assertion. Throws an Error that the assertion failed.
+ * Use when violations are logic errors in the program.
+ * @param message - Message to be printed if assertion fails.
+ */
+export function fail(message: string): never {
+	assert(false, message);
+}

package/src/test/tsconfig.cjs.json

@@ -0,0 +1,12 @@
+{
+	// This config must be used in a "type": "commonjs" environment. (Use fluid-tsc commonjs.)
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "../../dist/test",
+	},
+	"references": [
+		{
+			"path": "../../tsconfig.cjs.json",
+		},
+	],
+}

package/src/test/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"extends": "../../../../../common/build/build-common/tsconfig.test.node16.json",
+	"compilerOptions": {
+		"rootDir": "./",
+		"outDir": "../../lib/test",
+		"types": ["mocha"],
+
+		// The package exports utilities for test code from the test folder, so we need to build types for test files, which we typically
+		// don't do.
+		"declaration": true,
+		"declarationMap": true,
+		"noImplicitAny": false,
+	},
+	"include": ["./**/*"],
+	"references": [
+		{
+			"path": "../..",
+		},
+	],
+}

package/src/types/idCompressor.ts

@@ -3,65 +3,17 @@
  * Licensed under the MIT License.
  */
 
-import { SessionSpaceCompressedId, OpSpaceCompressedId, SessionId, StableId } from "./identifiers";
+import {
+	SessionSpaceCompressedId,
+	OpSpaceCompressedId,
+	SessionId,
+	StableId,
+} from "./identifiers.js";
 import {
 	IdCreationRange,
 	SerializedIdCompressorWithNoSession,
 	SerializedIdCompressorWithOngoingSession,
-} from "./persisted-types";
-
-/**
- * @alpha
- */
-export interface IIdCompressorCore {
-	/**
-	 * Returns a range of IDs created by this session in a format for sending to the server for finalizing.
-	 * The range will include all IDs generated via calls to `generateCompressedId` since the last time this method was called.
-	 * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before
-	 * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
-	 */
-	takeNextCreationRange(): IdCreationRange;
-
-	/**
-	 * Finalizes the supplied range of IDs (which may be from either a remote or local session).
-	 * @param range - the range of session-local IDs to finalize.
-	 */
-	finalizeCreationRange(range: IdCreationRange): void;
-
-	/**
-	 * Run a callback that is performed from the perspective of a special "ghost" session.
-	 * Any ids generated by this session will be immediately finalized on the local client as if
-	 * they were created by a remote client with `ghostSessionId`.
-	 *
-	 * *WARNING:* This API requires an external consensus mechanism to safely use:
-	 * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:
-	 * - They invoke this API starting from the same finalized creation ranges
-	 * - This API is invoked with the same ghost session id
-	 * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session
-	 * Failure to meet these requirement will result in divergence across clients and eventual consistency errors.
-	 * While the ghost sesion callback is running, IdCompressor does not support serialization.
-	 * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform
-	 * data in some format into data in a new format.
-	 * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed
-	 * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all
-	 * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.
-	 * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.
-	 * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.
-	 */
-	beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void);
-
-	/**
-	 * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
-	 * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
-	 */
-	serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
-
-	/**
-	 * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
-	 * This only includes finalized state and is therefore suitable for use in summaries.
-	 */
-	serialize(withSession: false): SerializedIdCompressorWithNoSession;
-}
+} from "./persisted-types/index.js";
 
 /**
  * A distributed UUID generator and compressor.
@@ -123,31 +75,152 @@ export interface IIdCompressorCore {
  *
  * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops
  * should use op-space IDs.
+ * @alpha
+ */
+export interface IIdCompressorCore {
+	/**
+	 * Returns a range of IDs created by this session in a format for sending to the server for finalizing.
+	 * The range will include all IDs generated via calls to `generateCompressedId` since the last time this method was called.
+	 * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before
+	 * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
+	 */
+	takeNextCreationRange(): IdCreationRange;
+
+	/**
+	 * Finalizes the supplied range of IDs (which may be from either a remote or local session).
+	 * @param range - the range of session-local IDs to finalize.
+	 */
+	finalizeCreationRange(range: IdCreationRange): void;
+
+	/**
+	 * Run a callback that is performed from the perspective of a special "ghost" session.
+	 * Any ids generated by this session will be immediately finalized on the local client as if
+	 * they were created by a remote client with `ghostSessionId`.
+	 *
+	 * *WARNING:* This API requires an external consensus mechanism to safely use:
+	 * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:
+	 * - They invoke this API starting from the same finalized creation ranges
+	 * - This API is invoked with the same ghost session id
+	 * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session
+	 * Failure to meet these requirement will result in divergence across clients and eventual consistency errors.
+	 * While the ghost sesion callback is running, IdCompressor does not support serialization.
+	 * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform
+	 * data in some format into data in a new format.
+	 * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed
+	 * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all
+	 * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.
+	 * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.
+	 * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.
+	 */
+	beginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void);
+
+	/**
+	 * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
+	 * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
+	 */
+	serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
+
+	/**
+	 * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
+	 * This only includes finalized state and is therefore suitable for use in summaries.
+	 */
+	serialize(withSession: false): SerializedIdCompressorWithNoSession;
+}
+
+/**
+ * A distributed UUID generator and compressor.
+ * `IdCompressor` offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers
+ * for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.
+ *
+ * The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently.
+ * IDs generated by a compressor, via calls to `generateCompressedId`, are created in the compressor's "local" session.
+ * These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session
+ * is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated
+ * through a process called "normalization":
+ * - The scope of a local session (in which local IDs are unique) is called the "session space" of the client.
+ * - The context of persisted state (in Fluid, this is the context of ops and summaries) is called "op space".
+ * - `SessionSpaceCompressedId`s, generated via calls to `generateCompressedId`, should NEVER be serialized directly.
+ * In Fluid, this means they should not be included in ops or summaries.
+ * - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients.
+ * - Upon receipt, IDs should be normalized back to session space before use.
+ *
+ * Example Usage:
+ *
+ * ### Client A (Sender)
+ *
+ * ```typescript
+ * // Generate several local IDs
+ * const localId1 = idCompressor.generateCompressedId();
+ * const localId2 = idCompressor.generateCompressedId();
+ * const localId3 = idCompressor.generateCompressedId();
+ *
+ * // Normalize these IDs to op space for inclusion in a message
+ * const opSpaceId1 = idCompressor.normalizeToOpSpace(localId1);
+ * const opSpaceId2 = idCompressor.normalizeToOpSpace(localId2);
+ * const opSpaceId3 = idCompressor.normalizeToOpSpace(localId3);
+ *
+ * // Create and send a message containing these op space IDs along with the sender's session ID
+ * // In Fluid, this would be an op or summary
+ * const message = {
+ *     sessionID: idCompressor.localSessionId,
+ *     ids: [opSpaceId1, opSpaceId2, opSpaceId3]
+ * };
+ * ```
+ *
+ * ### Client B (Receiver)
+ *
+ * ```typescript
+ * // Receive the message from Client A
+ * const receivedMessage = ...; // In Fluid, this would be an op or summary
+ *
+ * // Normalize the received IDs back to session space, utilizing the sender's session ID
+ * const sessionSpaceId1 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[0], receivedMessage.sessionID);
+ * const sessionSpaceId2 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[1], receivedMessage.sessionID);
+ * const sessionSpaceId3 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[2], receivedMessage.sessionID);
+ * ```
  * @public
  */
 export interface IIdCompressor {
+	/**
+	 * The local session ID.
+	 */
 	localSessionId: SessionId;
 
 	/**
-	 * Generates a new compressed ID or returns an existing one.
-	 * This should ONLY be called to generate IDs for local operations.
+	 * Generates a new compressed ID.
+	 * The returned ID is in session space and should not be serialized directly. See `IIdCompressor` for more details.
 	 * @returns A new local ID in session space.
 	 */
 	generateCompressedId(): SessionSpaceCompressedId;
+
+	/**
+	 * Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any
+	 * normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).
+	 * In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probably in
+	 * scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and
+	 * this approach will often be superior to generating a UUID.
+	 * If small numbers are a requirement, `generateCompressedId` and normalization should be used instead.
+	 * See `IIdCompressor` for more details.
+	 * @returns A new local ID in session space.
+	 */
+	generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;
+
 	/**
 	 * Normalizes a session space ID into op space.
-	 * @param id - the local ID to normalize.
-	 * @returns the ID in op space.
+	 * The returned ID is in op space and can be safely serialized. However, it should be normalized back to session space before use.
+	 * See `IIdCompressor` for more details.
+	 * @param id - The local ID to normalize.
+	 * @returns The ID in op space.
 	 */
 	normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
+
 	/**
 	 * Normalizes an ID into session space.
-	 * @param id - the ID to normalize. If it is a local ID, it is assumed to have been created by the session corresponding
-	 * to `sessionId`.
-	 * @param originSessionId - the session from which `id` originated
-	 * @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
-	 * 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
-	 * range that contained it from the server.
+	 * @param id - The ID to normalize.
+	 * @param originSessionId - The session from which `id` originated. This should be the ID of the client that normalized `id` to op space.
+	 * This means that it may not be the client that created `id` in the first place, but rather the client that serialized it.
+	 * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.
+	 * @returns The session-space ID in the local session corresponding to `id`.
 	 */
 	normalizeToSessionSpace(
 		id: OpSpaceCompressedId,
@@ -156,22 +229,24 @@ export interface IIdCompressor {
 
 	/**
 	 * Decompresses a previously compressed ID into a UUID.
-	 * @param id - the compressed ID to be decompressed.
-	 * @returns the UUID associated with the compressed ID. Fails if the ID was not generated by this compressor.
+	 * @param id - The compressed ID to be decompressed.
+	 * @returns The UUID associated with the compressed ID.
+	 * @throws If the ID was not generated by any session known to this compressor.
 	 */
 	decompress(id: SessionSpaceCompressedId): StableId;
 
 	/**
 	 * Recompresses a UUID.
-	 * @param uncompressed - the UUID to recompress.
-	 * @returns the `CompressedId` associated with `uncompressed`. Fails if it has not been previously compressed by this compressor.
+	 * @param uncompressed - The UUID to recompress.
+	 * @returns The `CompressedId` associated with `uncompressed`.
+	 * @throws If the UUID was not generated by any session known to this compressor.
 	 */
 	recompress(uncompressed: StableId): SessionSpaceCompressedId;
 
 	/**
-	 * Attempts to recompresses a UUID.
-	 * @param uncompressed - the UUID to recompress,
-	 * @returns the `CompressedId` associated with `uncompressed` or undefined if it has not been previously compressed by this compressor.
+	 * Attempts to recompress a UUID.
+	 * @param uncompressed - The UUID to recompress.
+	 * @returns The `CompressedId` associated with `uncompressed` or undefined if the UUID was not generated by any session known to this compressor.
 	 */
 	tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
 }

package/src/types/index.ts

@@ -8,8 +8,13 @@ export {
 	SerializedIdCompressor,
 	SerializedIdCompressorWithNoSession,
 	SerializedIdCompressorWithOngoingSession,
-} from "./persisted-types";
+} from "./persisted-types/index.js";
 
-export { IIdCompressorCore, IIdCompressor } from "./idCompressor";
+export { IIdCompressorCore, IIdCompressor } from "./idCompressor.js";
 
-export { SessionSpaceCompressedId, OpSpaceCompressedId, SessionId, StableId } from "./identifiers";
+export {
+	SessionSpaceCompressedId,
+	OpSpaceCompressedId,
+	SessionId,
+	StableId,
+} from "./identifiers.js";

package/src/types/persisted-types/0.0.1.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import type { SessionId } from "../identifiers";
+import type { SessionId } from "../identifiers.js";
 
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.

package/src/types/persisted-types/index.ts

@@ -8,4 +8,4 @@ export {
 	SerializedIdCompressor,
 	SerializedIdCompressorWithNoSession,
 	SerializedIdCompressorWithOngoingSession,
-} from "./0.0.1";
+} from "./0.0.1.js";

package/src/utilities.ts

@@ -6,8 +6,8 @@
 /* eslint-disable no-bitwise */
 import { assert } from "@fluidframework/core-utils";
 import { v4 } from "uuid";
-import { SessionId, StableId } from "./types";
-import { LocalCompressedId, NumericUuid } from "./identifiers";
+import { SessionId, StableId } from "./types/index.js";
+import { LocalCompressedId, NumericUuid } from "./identifiers.js";
 
 const hexadecimalCharCodes = Array.from("09afAF").map((c) => c.charCodeAt(0)) as [
 	zero: number,

package/tsconfig.cjs.json

@@ -0,0 +1,7 @@
+{
+	// This config must be used in a "type": "commonjs" environment. (Use fluid-tsc commonjs.)
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "./dist",
+	},
+}

package/tsconfig.json

@@ -1,11 +1,8 @@
 {
-	"extends": [
-		"../../../common/build/build-common/tsconfig.base.json",
-		"../../../common/build/build-common/tsconfig.cjs.json",
-	],
+	"extends": "../../../common/build/build-common/tsconfig.node16.json",
 	"compilerOptions": {
 		"rootDir": "./src",
-		"outDir": "./dist",
+		"outDir": "./lib",
 	},
 	"include": ["src/**/*"],
 	"exclude": ["src/test/**/*"],

package/lib/appendOnlySortedMap.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"appendOnlySortedMap.d.mts","sourceRoot":"","sources":["../src/appendOnlySortedMap.ts"],"names":[],"mappings":"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"}

package/lib/appendOnlySortedMap.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"appendOnlySortedMap.mjs","sourceRoot":"","sources":["../src/appendOnlySortedMap.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/* eslint-disable tsdoc/syntax */\n/* eslint-disable no-bitwise */\nimport { assert } from \"@fluidframework/core-utils\";\n\n/**\n * A map in which entries are always added in key-sorted order.\n * Supports appending and searching.\n */\nexport class AppendOnlySortedMap<K, V> {\n\tprotected readonly elements: (K | V)[] = [];\n\n\t/**\n\t * @param comparator - a comparator for keys\n\t */\n\tpublic constructor(protected readonly comparator: (a: K, b: K) => number) {}\n\n\t/**\n\t * @returns the number of entries in this map\n\t */\n\tpublic get size(): number {\n\t\treturn this.elements.length / 2;\n\t}\n\n\t/**\n\t * @returns the min key in the map.\n\t */\n\tpublic minKey(): K | undefined {\n\t\treturn this.elements[0] as K | undefined;\n\t}\n\n\t/**\n\t * @returns the max key in the map.\n\t */\n\tpublic maxKey(): K | undefined {\n\t\treturn this.elements[this.elements.length - 2] as K | undefined;\n\t}\n\n\t/**\n\t * @returns the min value in the map.\n\t */\n\tpublic minValue(): V | undefined {\n\t\treturn this.elements[1] as V | undefined;\n\t}\n\n\t/**\n\t * @returns the min value in the map.\n\t */\n\tpublic maxValue(): V | undefined {\n\t\treturn this.elements[this.elements.length - 1] as V | undefined;\n\t}\n\n\t/**\n\t * @returns the min key in the map.\n\t */\n\tpublic first(): [K, V] | undefined {\n\t\tconst { elements } = this;\n\t\tconst { length } = elements;\n\t\tif (length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn [elements[0] as K, elements[1] as V];\n\t}\n\n\t/**\n\t * @returns the max key in the map.\n\t */\n\tpublic last(): [K, V] | undefined {\n\t\tconst { elements } = this;\n\t\tconst { length } = elements;\n\t\tif (length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tconst lastKeyIndex = length - 2;\n\t\treturn [elements[lastKeyIndex] as K, elements[lastKeyIndex + 1] as V];\n\t}\n\n\t/**\n\t * Returns the element at the insertion index.\n\t */\n\tpublic getAtIndex(index: number): [K, V] | undefined {\n\t\tconst realIndex = index * 2;\n\t\tconst { elements } = this;\n\t\tif (realIndex < 0 || realIndex > elements.length - 1) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn [elements[realIndex] as K, elements[realIndex + 1] as V];\n\t}\n\n\t/**\n\t * @returns an iterable of the entries in the map.\n\t */\n\tpublic *entries(): IterableIterator<readonly [K, V]> {\n\t\tconst { elements } = this;\n\t\tfor (let i = 0; i < elements.length; i += 2) {\n\t\t\tyield [elements[i] as K, elements[i + 1] as V];\n\t\t}\n\t}\n\n\t/**\n\t * @returns an iterable of the keys in the map.\n\t */\n\tpublic *keys(): IterableIterator<K> {\n\t\tconst { elements } = this;\n\t\tfor (let i = 0; i < elements.length; i += 2) {\n\t\t\tyield elements[i] as K;\n\t\t}\n\t}\n\n\t/**\n\t * @returns an iterable of the values in the map.\n\t */\n\tpublic *values(): IterableIterator<V> {\n\t\tconst { elements } = this;\n\t\tfor (let i = 0; i < elements.length; i += 2) {\n\t\t\tyield elements[i + 1] as V;\n\t\t}\n\t}\n\n\t/**\n\t * @returns an iterable of the entries in the map, reversed.\n\t */\n\tpublic *entriesReversed(): IterableIterator<readonly [K, V]> {\n\t\tconst { elements } = this;\n\t\tfor (let i = elements.length - 2; i >= 0; i -= 2) {\n\t\t\tyield [elements[i] as K, elements[i + 1] as V];\n\t\t}\n\t}\n\n\t/**\n\t * Adds a new key/value pair to the map. `key` must be > to all keys in the map.\n\t * @param key - the key to add.\n\t * @param value - the value to add.\n\t */\n\tpublic append(key: K, value: V): void {\n\t\tconst { elements } = this;\n\t\tconst { length } = elements;\n\t\tif (length !== 0 && this.comparator(key, this.maxKey() as K) <= 0) {\n\t\t\tthrow new Error(\"Inserted key must be > all others in the map.\");\n\t\t}\n\t\telements.push(key);\n\t\telements.push(value);\n\t}\n\n\t/**\n\t * Replaces the last key/value pair with the given one. If the map is empty, it simply appends.\n\t * `key` must be > to all keys in the map prior to the one replaced.\n\t * @param key - the key to add.\n\t * @param value - the value to add.\n\t */\n\tpublic replaceLast(key: K, value: V): void {\n\t\tconst { elements, comparator } = this;\n\t\tconst { length } = elements;\n\t\tif (length !== 0) {\n\t\t\telements.pop();\n\t\t\telements.pop();\n\t\t\tif (comparator(key, this.maxKey() as K) <= 0) {\n\t\t\t\tthrow new Error(\"Inserted key must be > all others in the map.\");\n\t\t\t}\n\t\t}\n\t\telements.push(key);\n\t\telements.push(value);\n\t}\n\n\t/**\n\t * @param key - the key to lookup.\n\t * @returns the value associated with `key` if such an entry exists, and undefined otherwise.\n\t */\n\tpublic get(key: K): V | undefined {\n\t\tconst index = AppendOnlySortedMap.keyIndexOf(this.elements, key, this.comparator);\n\t\tif (index < 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\treturn this.elements[index + 1] as V;\n\t}\n\n\t/**\n\t * @param key - the key to lookup.\n\t * @returns the entry associated with `key` if such an entry exists, the entry associated with the next lower key if such an entry\n\t * exists, and undefined otherwise.\n\t */\n\tpublic getPairOrNextLower(key: K): readonly [K, V] | undefined {\n\t\treturn this.getPairOrNextLowerBy(key, this.comparator);\n\t}\n\n\t/**\n\t * @param key - the key to lookup.\n\t * @returns the entry associated with `key` if such an entry exists, the entry associated with the next higher key if such an entry\n\t * exists, and undefined otherwise.\n\t */\n\tpublic getPairOrNextHigher(key: K): readonly [K, V] | undefined {\n\t\treturn this.getPairOrNextHigherBy(key, this.comparator);\n\t}\n\n\t/**\n\t * Compares two `AppendOnlySortedMap`s.\n\t */\n\tpublic equals(\n\t\tother: AppendOnlySortedMap<K, V>,\n\t\tcompareValues: (a: V, b: V) => boolean,\n\t): boolean {\n\t\tif (other === this) {\n\t\t\treturn true;\n\t\t}\n\n\t\tif (this.elements.length !== other.elements.length) {\n\t\t\treturn false;\n\t\t}\n\n\t\tfor (let i = this.elements.length - 2; i >= 0; i -= 2) {\n\t\t\tconst keyThis = this.elements[i] as K;\n\t\t\tconst valueThis = this.elements[i + 1] as V;\n\t\t\tconst keyOther = other.elements[i] as K;\n\t\t\tconst valueOther = other.elements[i + 1] as V;\n\t\t\tif (this.comparator(keyThis, keyOther) !== 0) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tif (!compareValues(valueThis, valueOther)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * Test-only expensive assertions to check the internal validity of the data structure.\n\t */\n\tpublic assertValid(): void {\n\t\tlet prev: readonly [K, unknown] | undefined;\n\t\tfor (const kv of this.entries()) {\n\t\t\tif (prev !== undefined) {\n\t\t\t\tassert(\n\t\t\t\t\tthis.comparator(kv[0], prev[0]) > 0,\n\t\t\t\t\t0x752 /* Keys in map must be sorted. */,\n\t\t\t\t);\n\t\t\t}\n\t\t\tprev = kv;\n\t\t}\n\t}\n\n\t/**\n\t * Queries a range of entries.\n\t * @param from - the key to start the range query at, inclusive.\n\t * @param to - the key to end the range query at, inclusive.\n\t * @returns the range of entries.\n\t */\n\tpublic *getRange(from: K, to: K): IterableIterator<readonly [K, V]> {\n\t\tconst keyIndexFrom = this.getKeyIndexOfOrNextHigher(from, this.comparator);\n\t\tif (keyIndexFrom === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst keyIndexTo = this.getKeyIndexOfOrNextLower(to, this.comparator);\n\t\tif (keyIndexTo === undefined) {\n\t\t\treturn;\n\t\t}\n\n\t\tfor (let i = keyIndexFrom; i <= keyIndexTo; i += 2) {\n\t\t\tyield [this.elements[i] as K, this.elements[i + 1] as V];\n\t\t}\n\t}\n\n\tprotected getPairOrNextLowerBy<T>(\n\t\tsearch: T,\n\t\tcomparator: (search: T, key: K, value: V) => number,\n\t): readonly [K, V] | undefined {\n\t\tconst keyIndex = this.getKeyIndexOfOrNextLower(search, comparator);\n\t\tif (keyIndex === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn [this.elements[keyIndex] as K, this.elements[keyIndex + 1] as V];\n\t}\n\n\tprivate getKeyIndexOfOrNextLower<T>(\n\t\tsearch: T,\n\t\tcomparator: (search: T, key: K, value: V) => number,\n\t): number | undefined {\n\t\tconst { elements } = this;\n\t\tif (elements.length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tlet keyIndex = AppendOnlySortedMap.keyIndexOf(elements, search, comparator);\n\t\tif (keyIndex < 0) {\n\t\t\tkeyIndex ^= AppendOnlySortedMap.failureXor;\n\t\t\tif (keyIndex > 0) {\n\t\t\t\treturn keyIndex - 2;\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\t\treturn keyIndex;\n\t}\n\n\tprotected getPairOrNextHigherBy<T>(\n\t\tsearch: T,\n\t\tcomparator: (search: T, key: K, value: V) => number,\n\t): readonly [K, V] | undefined {\n\t\tconst keyIndex = this.getKeyIndexOfOrNextHigher(search, comparator);\n\t\tif (keyIndex === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\treturn [this.elements[keyIndex] as K, this.elements[keyIndex + 1] as V];\n\t}\n\n\tprivate getKeyIndexOfOrNextHigher<T>(\n\t\tsearch: T,\n\t\tcomparator: (search: T, key: K, value: V) => number,\n\t): number | undefined {\n\t\tconst { elements } = this;\n\t\tconst { length } = elements;\n\t\tif (length === 0) {\n\t\t\treturn undefined;\n\t\t}\n\t\tlet keyIndex = AppendOnlySortedMap.keyIndexOf(elements, search, comparator);\n\t\tif (keyIndex < 0) {\n\t\t\tkeyIndex ^= AppendOnlySortedMap.failureXor;\n\t\t\tif (keyIndex < length) {\n\t\t\t\treturn keyIndex;\n\t\t\t}\n\t\t\treturn undefined;\n\t\t}\n\t\treturn keyIndex;\n\t}\n\n\t/**\n\t * The value xor'd with the result index when a search fails.\n\t */\n\tpublic static readonly failureXor = -1;\n\n\t/**\n\t * Performs a binary search on the sorted array.\n\t * @returns the index of the key for `search`, or (if not present) the index it would have been inserted into xor'd\n\t * with `failureXor`. Note that negating is not an adequate solution as that could result in -0.\n\t */\n\tpublic static keyIndexOf<T, K, V>(\n\t\telements: readonly (K | V)[],\n\t\tsearch: T,\n\t\tcomparator: (search: T, key: K, value: V) => number,\n\t): number {\n\t\t// Low, high, and mid are addresses of [K,V] pairs and *not* key indices\n\t\tlet low = 0;\n\t\tlet high = elements.length / 2;\n\t\tlet mid = high >> 1;\n\t\twhile (low < high) {\n\t\t\tconst keyIndex = mid * 2;\n\t\t\tconst c = comparator(search, elements[keyIndex] as K, elements[keyIndex + 1] as V);\n\t\t\tif (c > 0) {\n\t\t\t\tlow = mid + 1;\n\t\t\t} else if (c < 0) {\n\t\t\t\thigh = mid;\n\t\t\t} else if (c === 0) {\n\t\t\t\treturn keyIndex;\n\t\t\t} else {\n\t\t\t\tthrow new Error(\"Invalid comparator.\");\n\t\t\t}\n\t\t\tmid = (low + high) >> 1;\n\t\t}\n\t\treturn (mid * 2) ^ AppendOnlySortedMap.failureXor;\n\t}\n}\n"]}

package/lib/finalSpace.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"finalSpace.d.mts","sourceRoot":"","sources":["../src/finalSpace.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAGI,EAAE,SAAS,EAAyD;OACpE,EAAE,iBAAiB,EAAE;AAE5B;;;;GAIG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAE/C,IAAW,QAAQ,IAAI,SAAS,SAAS,EAAE,CAE1C;IAEM,cAAc,IAAI,SAAS,GAAG,SAAS;IAIvC,UAAU,CAAC,UAAU,EAAE,SAAS;IAWvC;;;OAGG;IACI,mBAAmB,IAAI,iBAAiB;IAO/C;;;OAGG;IACI,mBAAmB,IAAI,iBAAiB;IAOxC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO;CAQzC"}

package/lib/finalSpace.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"finalSpace.mjs","sourceRoot":"","sources":["../src/finalSpace.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EAAE,MAAM,EAAE,MAAM,4BAA4B;OAC5C,EAAa,aAAa,EAAE,kBAAkB,EAAE,kBAAkB,EAAE;AAG3E;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAAvB;QACkB,gBAAW,GAAgB,EAAE,CAAC;IAmDhD,CAAC;IAjDA,IAAW,QAAQ;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC;IACzB,CAAC;IAEM,cAAc;QACpB,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAEM,UAAU,CAAC,UAAqB;QACtC,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC1C,MAAM,CACL,WAAW,KAAK,SAAS;YACxB,qEAAqE;YACrE,UAAU,CAAC,WAAW,KAAK,WAAW,CAAC,WAAW,GAAG,WAAW,CAAC,QAAQ,EAC1E,KAAK,CAAC,oDAAoD,CAC1D,CAAC;QACF,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACzB,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,WAAW,KAAK,SAAS;YAC/B,CAAC,CAAE,CAAuB;YAC1B,CAAC,CAAE,CAAE,kBAAkB,CAAC,WAAW,CAAY,GAAG,CAAC,CAAuB,CAAC;IAC7E,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACzB,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,WAAW,KAAK,SAAS;YAC/B,CAAC,CAAE,CAAuB;YAC1B,CAAC,CAAE,CAAE,kBAAkB,CAAC,WAAW,CAAY,GAAG,CAAC,CAAuB,CAAC;IAC7E,CAAC;IAEM,MAAM,CAAC,KAAiB;QAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;YACjD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE;gBAC9D,OAAO,KAAK,CAAC;aACb;SACD;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC;IAC7D,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils\";\nimport { IdCluster, clustersEqual, lastAllocatedFinal, lastFinalizedFinal } from \"./sessions\";\nimport { FinalCompressedId } from \"./identifiers\";\n\n/**\n * All IDs that have been finalized (acked), grouped into clusters sorted by their base final IDs.\n * These clusters span the positive integer space and are not sparse, meaning a cluster's base final\n * ID will always be one greater than the last final ID in the previous cluster (or 0 if there is not one).\n */\nexport class FinalSpace {\n\tprivate readonly clusterList: IdCluster[] = [];\n\n\tpublic get clusters(): readonly IdCluster[] {\n\t\treturn this.clusterList;\n\t}\n\n\tpublic getLastCluster(): IdCluster | undefined {\n\t\treturn this.clusterList[this.clusterList.length - 1];\n\t}\n\n\tpublic addCluster(newCluster: IdCluster) {\n\t\tconst lastCluster = this.getLastCluster();\n\t\tassert(\n\t\t\tlastCluster === undefined ||\n\t\t\t\t// eslint-disable-next-line @typescript-eslint/restrict-plus-operands\n\t\t\t\tnewCluster.baseFinalId === lastCluster.baseFinalId + lastCluster.capacity,\n\t\t\t0x753 /* Cluster insert to final_space is out of order. */,\n\t\t);\n\t\tthis.clusterList.push(newCluster);\n\t}\n\n\t/**\n\t * @returns the upper bound (exclusive) of finalized IDs in final space, i.e. one greater than the last final ID in the last cluster.\n\t * Note: this does not include allocated but unfinalized space in clusters.\n\t */\n\tpublic getFinalizedIdLimit(): FinalCompressedId {\n\t\tconst lastCluster = this.getLastCluster();\n\t\treturn lastCluster === undefined\n\t\t\t? (0 as FinalCompressedId)\n\t\t\t: (((lastFinalizedFinal(lastCluster) as number) + 1) as FinalCompressedId);\n\t}\n\n\t/**\n\t * @returns the upper bound (exclusive) of allocated IDs in final space, i.e. one greater than the last final ID in the last cluster.\n\t * Note: this does includes all allocated IDs in clusters.\n\t */\n\tpublic getAllocatedIdLimit(): FinalCompressedId {\n\t\tconst lastCluster = this.getLastCluster();\n\t\treturn lastCluster === undefined\n\t\t\t? (0 as FinalCompressedId)\n\t\t\t: (((lastAllocatedFinal(lastCluster) as number) + 1) as FinalCompressedId);\n\t}\n\n\tpublic equals(other: FinalSpace): boolean {\n\t\tfor (let i = 0; i < this.clusterList.length; i++) {\n\t\t\tif (!clustersEqual(this.clusterList[i], other.clusterList[i])) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\treturn this.clusterList.length === other.clusterList.length;\n\t}\n}\n"]}