@fluidframework/id-compressor 3.2.0 → 3.3.0

package/lib/types/idCompressor.js.map

@@ -1 +1 @@
-{"version":3,"file":"idCompressor.js","sourceRoot":"","sources":["../../src/types/idCompressor.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n\tStableId,\n} from \"./identifiers.js\";\nimport type {\n\tIdCreationRange,\n\tSerializedIdCompressorWithNoSession,\n\tSerializedIdCompressorWithOngoingSession,\n} from \"./persisted-types/index.js\";\n\n/**\n * A distributed UUID generator and compressor.\n *\n * Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple \"sessions\" (which can be distributed across the network),\n * providing each session with the ability to map these UUIDs to `numbers`.\n *\n * A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API\n * which should then be sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is\n * created it is said to be created by the compressor's \"local\" session.\n *\n * For each stable ID created, two numeric IDs are provided by the compressor:\n *\n * 1. A session-local ID, which is stable for the lifetime of the session (which could be longer than that of the compressor object, as it may\n * be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only\n * safely usable within the scope of the compressor that created it.\n *\n * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing\n * the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations.\n * Final IDs are known to and publicly usable by any compressor that has received them.\n *\n * Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed\n * to map the UUIDs to the numbers.\n *\n * The following invariants are upheld by IdCompressor:\n *\n * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.\n *\n * 2. Final IDs will always decompress to the same UUIDs.\n *\n * 3. After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be\n * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the\n * same final ID.\n *\n * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.\n *\n * Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*\n * be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.\n *\n * Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This\n * could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a\n * session-local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will\n * produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the\n * session-local IDs have been finalized, the compressor defines two \"spaces\" of IDs:\n *\n * 1. Session space: in this space, all IDs are normalized to their \"most local form\". This means that all IDs created by the local session\n * will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after\n * finalizing and will never have a local form for the compressor, will of course be final IDs. This space should be used with consumer APIs\n * and data structures, as the lifetime of the IDs is guaranteed to be the same as the compressor object. Care must be taken to not use\n * these IDs across compressor objects, as the local IDs are specific to the compressor that created them.\n *\n * 2. Op space: in this space, all IDs are normalized to their \"most final form\". This means that all IDs except session-local IDs that\n * have not yet been finalized will be in final ID form. This space is useful for serialization in ops (e.g. references), as other clients\n * that receive them need not do any work to normalize them to *their* session-space in the common case. Note that IDs in op space may move\n * out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a \"more final form\".\n * Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially\n * incorrect to use this type for a runtime variable. This is an asymmetry that does not affect session space, as local IDs are always as\n * \"local as possible\".\n *\n * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops\n * should use op-space IDs.\n *\n * @internal\n */\nexport interface IIdCompressorCore {\n\t/**\n\t * Returns a range of IDs created by this session in a format for sending to the server for finalizing.\n\t * The range will include all IDs generated via calls to `generateCompressedId` since the last time a\n\t * range was taken (via this method or `takeUnfinalizedCreationRange`).\n\t * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before\n\t * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.\n\t */\n\ttakeNextCreationRange(): IdCreationRange;\n\n\t/**\n\t * Returns a range of IDs created by this session in a format for sending to the server for finalizing.\n\t * The range will include all unfinalized IDs generated via calls to `generateCompressedId`.\n\t * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before\n\t * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.\n\t * Note: after finalizing the range returned by this method, finalizing any ranges that had been previously taken\n\t * will result in an error.\n\t */\n\ttakeUnfinalizedCreationRange(): IdCreationRange;\n\n\t/**\n\t * Resets the next creation range to include all unfinalized IDs.\n\t *\n\t * @remarks\n\t * IMPORTANT: This must only be called if it's CERTAIN that the unfinalized range will never be finalized as-is (e.g. by in-flight ops).\n\t *\n\t * After calling this, the next call to {@link IIdCompressorCore.takeNextCreationRange} will produce a range\n\t * covering all unfinalized IDs (equivalent to what {@link IIdCompressorCore.takeUnfinalizedCreationRange} would\n\t * have returned) plus any IDs generated after this call.\n\t *\n\t * Unlike {@link IIdCompressorCore.takeUnfinalizedCreationRange}, this method does not produce or return a range,\n\t * and does not advance the internal range counter. It is useful when the caller wants to\n\t * defer the actual range submission to the next natural {@link IIdCompressorCore.takeNextCreationRange} call.\n\t */\n\tresetUnfinalizedCreationRange(): void;\n\n\t/**\n\t * Finalizes the supplied range of IDs (which may be from either a remote or local session).\n\t * @param range - the range of session-local IDs to finalize.\n\t */\n\tfinalizeCreationRange(range: IdCreationRange): void;\n\n\t/**\n\t * Run a callback that is performed from the perspective of a special \"ghost\" session.\n\t * Any ids generated by this session will be immediately finalized on the local client as if\n\t * they were created by a remote client with `ghostSessionId`.\n\t *\n\t * *WARNING:* This API requires an external consensus mechanism to safely use:\n\t * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:\n\t * - They invoke this API starting from the same finalized creation ranges\n\t * - This API is invoked with the same ghost session id\n\t * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session\n\t * Failure to meet these requirements will result in divergence across clients and eventual consistency errors.\n\t * While the ghost session callback is running, IdCompressor does not support serialization.\n\t * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform\n\t * data in some format into data in a new format.\n\t * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed\n\t * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all\n\t * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.\n\t * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.\n\t * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.\n\t */\n\tbeginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;\n\n\t/**\n\t * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.\n\t * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.\n\t */\n\tserialize(withSession: true): SerializedIdCompressorWithOngoingSession;\n\n\t/**\n\t * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.\n\t * This only includes finalized state and is therefore suitable for use in summaries.\n\t */\n\tserialize(withSession: false): SerializedIdCompressorWithNoSession;\n}\n\n/**\n * A distributed UUID generator and compressor.\n * `IdCompressor` offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers\n * for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.\n *\n * The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently.\n * IDs generated by a compressor, via calls to `generateCompressedId`, are created in the compressor's \"local\" session.\n * These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session\n * is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated\n * through a process called \"normalization\":\n * - The scope of a local session (in which local IDs are unique) is called the \"session space\" of the client.\n * - The context of persisted state (in Fluid, this is the context of ops and summaries) is called \"op space\".\n * - `SessionSpaceCompressedId`s, generated via calls to `generateCompressedId`, should NEVER be serialized directly.\n * In Fluid, this means they should not be included in ops or summaries.\n * - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients.\n * - Upon receipt, IDs should be normalized back to session space before use.\n *\n * Example Usage:\n *\n * ### Client A (Sender)\n *\n * ```typescript\n * // Generate several local IDs\n * const localId1 = idCompressor.generateCompressedId();\n * const localId2 = idCompressor.generateCompressedId();\n * const localId3 = idCompressor.generateCompressedId();\n *\n * // Normalize these IDs to op space for inclusion in a message\n * const opSpaceId1 = idCompressor.normalizeToOpSpace(localId1);\n * const opSpaceId2 = idCompressor.normalizeToOpSpace(localId2);\n * const opSpaceId3 = idCompressor.normalizeToOpSpace(localId3);\n *\n * // Create and send a message containing these op space IDs along with the sender's session ID\n * // In Fluid, this would be an op or summary\n * const message = {\n *     sessionID: idCompressor.localSessionId,\n *     ids: [opSpaceId1, opSpaceId2, opSpaceId3]\n * };\n * ```\n *\n * ### Client B (Receiver)\n *\n * ```typescript\n * // Receive the message from Client A\n * const receivedMessage = ...; // In Fluid, this would be an op or summary\n *\n * // Normalize the received IDs back to session space, utilizing the sender's session ID\n * const sessionSpaceId1 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[0], receivedMessage.sessionID);\n * const sessionSpaceId2 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[1], receivedMessage.sessionID);\n * const sessionSpaceId3 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[2], receivedMessage.sessionID);\n * ```\n * @public\n * @sealed\n */\nexport interface IIdCompressor {\n\t/**\n\t * The local session ID.\n\t */\n\tlocalSessionId: SessionId;\n\n\t/**\n\t * Generates a new compressed ID.\n\t * The returned ID is in session space and should not be serialized directly. See `IIdCompressor` for more details.\n\t * @returns A new local ID in session space.\n\t */\n\tgenerateCompressedId(): SessionSpaceCompressedId;\n\n\t/**\n\t * Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any\n\t * normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).\n\t * In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probable in\n\t * scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and\n\t * this approach will often be superior to generating a UUID.\n\t * If small numbers are a requirement, `generateCompressedId` and normalization should be used instead.\n\t * See `IIdCompressor` for more details.\n\t * @returns A new local ID in session space.\n\t */\n\tgenerateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;\n\n\t/**\n\t * Normalizes a session space ID into op space.\n\t * The returned ID is in op space and can be safely serialized.\n\t * However, it should be {@link IIdCompressor.normalizeToSessionSpace|normalized back to session space} before use.\n\t * @param id - The local ID to normalize.\n\t * @returns The ID in op space.\n\t */\n\tnormalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;\n\n\t/**\n\t * Normalizes an ID into session space.\n\t * @param id - The ID to normalize.\n\t * @param originSessionId - The {@link IIdCompressor.localSessionId} of the compressor which {@link IIdCompressor.normalizeToOpSpace|encoded} `id`.\n\t * This might not be the client that created `id` in the first place, but rather the client that serialized it.\n\t * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.\n\t * @returns The session-space ID in the local session corresponding to `id`.\n\t * @remarks\n\t * For this to be valid, `originSessionId` must be the {@link IIdCompressor.localSessionId} of the compressor that normalized `id` to op space.\n\t * Additionally, this compressor must know about the relevant {@link IdCreationRange} from the encoding `IIdCompressor`.\n\t * This can be accomplished using creating the compressor using {@link (deserializeIdCompressor:1)},\n\t * or relying on something (like the Fluid runtime) to synchronize the range information using internal mechanisms.\n\t *\n\t * The {@link IIdCompressor} provided by the Fluid Framework runtime will automatically track {@link IdCreationRange| Id Creation Ranges} (via its own ops) from other clients in the container.\n\t * It is up to the user of the {@link IIdCompressor} to ensure the relevant session information is available,\n\t * either by depending on the originating client's session ID for ops, or by explicitly storing it alongside the data containing the {@link OpSpaceCompressedId}.\n\t *\n\t * Note that attachment summaries, while they are ops, are also interpreted as summaries without the context of their originating session,\n\t * so they should explicitly include session IDs if required to decode them just like regular summaries and exported data.\n\t */\n\tnormalizeToSessionSpace(\n\t\tid: OpSpaceCompressedId,\n\t\toriginSessionId: SessionId,\n\t): SessionSpaceCompressedId;\n\n\t/**\n\t * Attempts to normalize an op-space ID into session space without an originator session id.\n\t * This mainly exists for data recovery purposes, when the originator session id was lost.\n\t * When possible, use {@link IIdCompressor.normalizeToSessionSpace} instead.\n\t *\n\t * @remarks\n\t * When the id is a final ID, this will return the properly translated session-space ID,\n\t * or throw if it detects that the final id is not valid in this compressor.\n\t *\n\t * Returns `undefined` if `id` is a non-final op-space ID — those are local to the\n\t * originating session and require its session id to resolve. Callers which have the\n\t * originating session id should call {@link IIdCompressor.normalizeToSessionSpace} instead.\n\t *\n\t * @param id - The ID to normalize.\n\t * @returns The session-space ID corresponding to `id`, or `undefined` if `id` is\n\t * non-final and therefore requires an originator session id to resolve.\n\t * @throws If `id` is final but is not known to this compressor (i.e. it refers to\n\t * a final id that has never been observed as finalized).\n\t * Note that it is possible (even likely) for a finalized id from another id compressor to pass this check,\n\t * and return an incorrect session-space ID.\n\t * This error is thrown only in cases where it is possible to detect the input is invalid,\n\t * and intended to help with catching bugs where invalid identifiers are being provided.\n\t * It cannot be relied upon for validation.\n\t *\n\t * @privateRemarks\n\t * Currently this is only used for data recovery in the case of lost session ids,\n\t * but we could theoretically provide an API to determine if the session id is required when encoding data (some IDs were non-final):\n\t * in such a setup, this API, and/or a version of normalizeToSessionSpace where the session id is optional,\n\t * could be used for a regular non-recovery use-case.\n\t */\n\ttryNormalizeToSessionSpaceWithoutSession(\n\t\tid: OpSpaceCompressedId,\n\t): SessionSpaceCompressedId | undefined;\n\n\t/**\n\t * Decompresses a previously compressed ID into a UUID.\n\t * @param id - The compressed ID to be decompressed.\n\t * @returns The UUID associated with the compressed ID.\n\t * @throws If the ID was not generated by any session known to this compressor.\n\t */\n\tdecompress(id: SessionSpaceCompressedId): StableId;\n\n\t/**\n\t * Recompresses a UUID.\n\t * @param uncompressed - The UUID to recompress.\n\t * @returns The `CompressedId` associated with `uncompressed`.\n\t * @throws If the UUID was not generated by any session known to this compressor.\n\t */\n\trecompress(uncompressed: StableId): SessionSpaceCompressedId;\n\n\t/**\n\t * Attempts to recompress a UUID.\n\t * @param uncompressed - The UUID to recompress.\n\t * @returns The `CompressedId` associated with `uncompressed` or undefined if the UUID was not generated by any session known to this compressor.\n\t */\n\ttryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;\n}\n"]}
+{"version":3,"file":"idCompressor.js","sourceRoot":"","sources":["../../src/types/idCompressor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IACnC;;OAEG;IACH,EAAE,EAAE,CAAC;IACL;;OAEG;IACH,EAAE,EAAE,CAAC;CACI,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type {\n\tOpSpaceCompressedId,\n\tSessionId,\n\tSessionSpaceCompressedId,\n\tStableId,\n} from \"./identifiers.js\";\nimport type {\n\tIdCreationRange,\n\tSerializedIdCompressorWithNoSession,\n\tSerializedIdCompressorWithOngoingSession,\n} from \"./persisted-types/index.js\";\n\n/**\n * Serialization format versions for IdCompressor.\n * @internal\n */\nexport const SerializationVersion = {\n\t/**\n\t * Base format without sharding support\n\t */\n\tV2: 2,\n\t/**\n\t * Adds optional sharding state\n\t */\n\tV3: 3,\n} as const;\n\n/**\n * Type representing valid serialization version values.\n * @internal\n */\nexport type SerializationVersion =\n\t(typeof SerializationVersion)[keyof typeof SerializationVersion];\n\n/**\n * A distributed UUID generator and compressor.\n *\n * Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple \"sessions\" (which can be distributed across the network),\n * providing each session with the ability to map these UUIDs to `numbers`.\n *\n * A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API\n * which should then be sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is\n * created it is said to be created by the compressor's \"local\" session.\n *\n * For each stable ID created, two numeric IDs are provided by the compressor:\n *\n * 1. A session-local ID, which is stable for the lifetime of the session (which could be longer than that of the compressor object, as it may\n * be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only\n * safely usable within the scope of the compressor that created it.\n *\n * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing\n * the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations.\n * Final IDs are known to and publicly usable by any compressor that has received them.\n *\n * Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed\n * to map the UUIDs to the numbers.\n *\n * The following invariants are upheld by IdCompressor:\n *\n * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.\n *\n * 2. Final IDs will always decompress to the same UUIDs.\n *\n * 3. After a server-processed range of session-local IDs (from any session) is received by a compressor, any of those session-local IDs may be\n * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the\n * same final ID.\n *\n * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.\n *\n * Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*\n * be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.\n *\n * Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This\n * could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a\n * session-local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will\n * produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the\n * session-local IDs have been finalized, the compressor defines two \"spaces\" of IDs:\n *\n * 1. Session space: in this space, all IDs are normalized to their \"most local form\". This means that all IDs created by the local session\n * will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after\n * finalizing and will never have a local form for the compressor, will of course be final IDs. This space should be used with consumer APIs\n * and data structures, as the lifetime of the IDs is guaranteed to be the same as the compressor object. Care must be taken to not use\n * these IDs across compressor objects, as the local IDs are specific to the compressor that created them.\n *\n * 2. Op space: in this space, all IDs are normalized to their \"most final form\". This means that all IDs except session-local IDs that\n * have not yet been finalized will be in final ID form. This space is useful for serialization in ops (e.g. references), as other clients\n * that receive them need not do any work to normalize them to *their* session-space in the common case. Note that IDs in op space may move\n * out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a \"more final form\".\n * Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially\n * incorrect to use this type for a runtime variable. This is an asymmetry that does not affect session space, as local IDs are always as\n * \"local as possible\".\n *\n * These two spaces naturally define a rule: consumers of compressed IDs should use session-space IDs, but serialized forms such as ops\n * should use op-space IDs.\n *\n * @internal\n */\nexport interface IIdCompressorCore {\n\t/**\n\t * Returns a range of IDs created by this session in a format for sending to the server for finalizing.\n\t * The range will include all IDs generated via calls to `generateCompressedId` since the last time a\n\t * range was taken (via this method or `takeUnfinalizedCreationRange`).\n\t * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before\n\t * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.\n\t * @throws if called on a child (non-root) shard. All shards in a shard tree share a single session, and only\n\t * the root shard may finalize that session's IDs with the server; a child's IDs are instead reconciled with the\n\t * root via {@link IIdCompressorCore.synchronizeWithShard} / {@link IIdCompressorCore.disposeShard}.\n\t */\n\ttakeNextCreationRange(): IdCreationRange;\n\n\t/**\n\t * Returns a range of IDs created by this session in a format for sending to the server for finalizing.\n\t * The range will include all unfinalized IDs generated via calls to `generateCompressedId`.\n\t * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before\n\t * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.\n\t * Note: after finalizing the range returned by this method, finalizing any ranges that had been previously taken\n\t * will result in an error.\n\t */\n\ttakeUnfinalizedCreationRange(): IdCreationRange;\n\n\t/**\n\t * Resets the next creation range to include all unfinalized IDs.\n\t *\n\t * @remarks\n\t * IMPORTANT: This must only be called if it's CERTAIN that the unfinalized range will never be finalized as-is (e.g. by in-flight ops).\n\t *\n\t * After calling this, the next call to {@link IIdCompressorCore.takeNextCreationRange} will produce a range\n\t * covering all unfinalized IDs (equivalent to what {@link IIdCompressorCore.takeUnfinalizedCreationRange} would\n\t * have returned) plus any IDs generated after this call.\n\t *\n\t * Unlike {@link IIdCompressorCore.takeUnfinalizedCreationRange}, this method does not produce or return a range,\n\t * and does not advance the internal range counter. It is useful when the caller wants to\n\t * defer the actual range submission to the next natural {@link IIdCompressorCore.takeNextCreationRange} call.\n\t */\n\tresetUnfinalizedCreationRange(): void;\n\n\t/**\n\t * Finalizes the supplied range of IDs (which may be from either a remote or local session).\n\t * @param range - the range of session-local IDs to finalize.\n\t */\n\tfinalizeCreationRange(range: IdCreationRange): void;\n\n\t/**\n\t * Run a callback that is performed from the perspective of a special \"ghost\" session.\n\t * Any ids generated by this session will be immediately finalized on the local client as if\n\t * they were created by a remote client with `ghostSessionId`.\n\t *\n\t * *WARNING:* This API requires an external consensus mechanism to safely use:\n\t * In an attached container (i.e. multiple clients may have the document loaded), all clients must guarantee that:\n\t * - They invoke this API starting from the same finalized creation ranges\n\t * - This API is invoked with the same ghost session id\n\t * - `ghostSessionCallback` deterministically mints the same number of ids on each client within the ghost session\n\t * Failure to meet these requirements will result in divergence across clients and eventual consistency errors.\n\t * While the ghost session callback is running, IdCompressor does not support serialization.\n\t * @remarks This API is primarily intended for data migration scenarios which are able to deterministically transform\n\t * data in some format into data in a new format.\n\t * The first requirement (that all clients must invoke the API with the same finalized creation ranges) is guaranteed\n\t * for this scenario because the data transformation callback occurs at a specific ack within the op stream on all\n\t * clients, and clients don't finalize creation ranges for local changes they might have at this point in time.\n\t * @param ghostSessionId - The session id that minted ids generated within `ghostSessionCallback` should be attributed to.\n\t * @param ghostSessionCallback - Callback which mints ids attributed to the ghost session.\n\t */\n\tbeginGhostSession(ghostSessionId: SessionId, ghostSessionCallback: () => void): void;\n\n\t/**\n\t * Shards the ID space of this compressor such that multiple local compressors can safely share it without colliding.\n\t * This can allow multiple local instantiations of the same compressor to safely share an ID space in scenarios where\n\t * different threads do not have access to a central ID compressor.\n\t * @param newShardCount - The number of additional different shards to split this compressor into.\n\t * Must be a positive safe integer.\n\t * @throws If `newShardCount` is not a positive safe integer or the resulting stride exceeds the sharding limit.\n\t * @returns An array of serialized compressors of size `newShardCount`.\n\t * These can be passed across a marshalling boundary and rehydrated on the other side, and will safely share the ID space of `this`.\n\t * Note that this method should only be needed when multiple JS runtimes are in play, as sharded compressors essentially\n\t * attempt to emulate a single static compressor and any code running in the same JS runtime can simply use statics.\n\t */\n\tshard(newShardCount: number): SerializedIdCompressorWithOngoingSession[];\n\n\t/**\n\t * Synchronizes `this` compressor with a child shard. Synchronization will occur for the state of the child at the time `syncToken`\n\t * was generated, meaning that `this` compressor can use/ingest IDs generated up to that point. Attempts to use IDs from a child shard\n\t * without first synchronizing will result in an exception.\n\t *\n\t * If `syncToken` is a disposal token (its {@link ShardToken.disposed} flag is `true`, as produced by\n\t * {@link IIdCompressorCore.disposeShard}), this additionally deregisters the child shard and reclaims its subset of the ID space\n\t * into `this`. Once a shard has been disposed it is no longer safe to use the compressor the token came from, and a shard tree must\n\t * be disposed from the leaves upwards.\n\t * @param syncToken - The token for the shard, obtained by calling {@link IIdCompressorCore.getShardSyncToken} (non-destructive\n\t * synchronization) or {@link IIdCompressorCore.disposeShard} (synchronization plus reclamation of the disposed shard's ID space).\n\t */\n\tsynchronizeWithShard(syncToken: ShardSynchronizationToken): void;\n\n\t/**\n\t * Returns undefined if this compressor is not part of a shard group, and otherwise returns a synchronization token for this shard\n\t * that can be used when calling {@link IIdCompressorCore.synchronizeWithShard}. This does NOT dispose the shard.\n\t *\n\t * @returns The sync token if this compressor is part of a sharded group, otherwise undefined.\n\t * The returned token is serializable and can be passed across marshaling boundaries. This token can be used to synchronize a\n\t * parent with this compressor by calling {@link IIdCompressorCore.synchronizeWithShard}.\n\t * Unlike {@link IIdCompressorCore.disposeShard}, this is non-destructive and may be called on a shard that still has active\n\t * child shards, which allows an intermediate shard to propagate its progress upward to its own parent.\n\t * @throws If this compressor is the root of the shard tree (only non-root shards can produce a token).\n\t */\n\tgetShardSyncToken(): ShardSynchronizationToken | undefined;\n\n\t/**\n\t * Returns undefined if this compressor is not part of a shard group, and otherwise disposes this shard and returns\n\t * the disposal token for this compressor. If this compressor was part of a shard group, the compressor will no longer be usable.\n\t *\n\t * @returns The disposal token if this compressor is part of a sharded group, otherwise undefined.\n\t * The returned token is serializable and can be passed across marshaling boundaries. Passing it to\n\t * {@link IIdCompressorCore.synchronizeWithShard} on the parent reclaims this shard's subset of the ID space.\n\t * @throws If this shard has active child shards.\n\t * This means that a shard tree must be disposed from the leaves upwards.\n\t */\n\tdisposeShard(): ShardSynchronizationToken | undefined;\n\n\t/**\n\t * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `deserializeIdCompressor()`.\n\t * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.\n\t */\n\tserialize(withSession: true): SerializedIdCompressorWithOngoingSession;\n\n\t/**\n\t * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `deserializeIdCompressor()`.\n\t * This only includes finalized state and is therefore suitable for use in summaries.\n\t */\n\tserialize(withSession: false): SerializedIdCompressorWithNoSession;\n}\n\n/**\n * The state shared by all shard tokens: enough information to identify a shard and its progress\n * through its stride pattern. This is used to track which shard generated which IDs and to manage\n * reclamation of a disposed shard's ID space. The {@link ShardToken.disposed} flag distinguishes a\n * plain synchronization token from a disposal token. The branded {@link ShardSynchronizationToken}\n * is the concrete type handed to consumers.\n * @internal\n */\nexport interface ShardToken {\n\t/**\n\t * The number of positions filled in this shard's stride pattern.\n\t * This tracks progress through the stride cycle, not the count of IDs actually generated.\n\t * For example, when a shard is created, it backfills entries for positions in its stride,\n\t * so this value may be non-zero even if the shard hasn't generated any IDs yet.\n\t */\n\tlocalGenCount: number;\n\n\t/**\n\t * Unique identifier for this shard within its parent.\n\t */\n\tshardId: SessionId;\n\n\t/**\n\t * Whether this token also signals disposal of the originating shard. When `true`, passing the token to\n\t * {@link IIdCompressorCore.synchronizeWithShard} reclaims the shard's ID space in addition to synchronizing.\n\t * Produced as `false` by {@link IIdCompressorCore.getShardSyncToken} and `true` by {@link IIdCompressorCore.disposeShard}.\n\t */\n\tdisposed: boolean;\n}\n\n/**\n * A {@link ShardToken} that identifies a shard for synchronization (and, when {@link ShardToken.disposed} is `true`,\n * reclamation) via {@link IIdCompressorCore.synchronizeWithShard}.\n * @internal\n */\nexport type ShardSynchronizationToken = ShardToken & {\n\treadonly ShardSynchronizationToken: \"c79724e1-9103-4415-95b5-bebb932be404\";\n};\n\n/**\n * A distributed UUID generator and compressor.\n * `IdCompressor` offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers\n * for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs.\n *\n * The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently.\n * IDs generated by a compressor, via calls to `generateCompressedId`, are created in the compressor's \"local\" session.\n * These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session\n * is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated\n * through a process called \"normalization\":\n * - The scope of a local session (in which local IDs are unique) is called the \"session space\" of the client.\n * - The context of persisted state (in Fluid, this is the context of ops and summaries) is called \"op space\".\n * - `SessionSpaceCompressedId`s, generated via calls to `generateCompressedId`, should NEVER be serialized directly.\n * In Fluid, this means they should not be included in ops or summaries.\n * - Before serialization, IDs must be normalized to op space to ensure they are interpretable by other clients.\n * - Upon receipt, IDs should be normalized back to session space before use.\n *\n * Example Usage:\n *\n * ### Client A (Sender)\n *\n * ```typescript\n * // Generate several local IDs\n * const localId1 = idCompressor.generateCompressedId();\n * const localId2 = idCompressor.generateCompressedId();\n * const localId3 = idCompressor.generateCompressedId();\n *\n * // Normalize these IDs to op space for inclusion in a message\n * const opSpaceId1 = idCompressor.normalizeToOpSpace(localId1);\n * const opSpaceId2 = idCompressor.normalizeToOpSpace(localId2);\n * const opSpaceId3 = idCompressor.normalizeToOpSpace(localId3);\n *\n * // Create and send a message containing these op space IDs along with the sender's session ID\n * // In Fluid, this would be an op or summary\n * const message = {\n *     sessionID: idCompressor.localSessionId,\n *     ids: [opSpaceId1, opSpaceId2, opSpaceId3]\n * };\n * ```\n *\n * ### Client B (Receiver)\n *\n * ```typescript\n * // Receive the message from Client A\n * const receivedMessage = ...; // In Fluid, this would be an op or summary\n *\n * // Normalize the received IDs back to session space, utilizing the sender's session ID\n * const sessionSpaceId1 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[0], receivedMessage.sessionID);\n * const sessionSpaceId2 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[1], receivedMessage.sessionID);\n * const sessionSpaceId3 = idCompressor.normalizeToSessionSpace(receivedMessage.ids[2], receivedMessage.sessionID);\n * ```\n * @public\n * @sealed\n */\nexport interface IIdCompressor {\n\t/**\n\t * The local session ID.\n\t */\n\tlocalSessionId: SessionId;\n\n\t/**\n\t * Generates a new compressed ID.\n\t * The returned ID is in session space and should not be serialized directly. See `IIdCompressor` for more details.\n\t * @returns A new local ID in session space.\n\t */\n\tgenerateCompressedId(): SessionSpaceCompressedId;\n\n\t/**\n\t * Generates a new ID that is guaranteed to be unique across all sessions known to this compressor without the need for any\n\t * normalization. The returned ID is not guaranteed to be a compressed ID (small number); it may be a stable ID (UUID string).\n\t * In Fluid, the likelihood of generating the bulkier stable ID is dictated by network conditions and is highly probable in\n\t * scenarios such as offline. This is still useful for use cases where simplicity is more important than performance and\n\t * this approach will often be superior to generating a UUID.\n\t * If small numbers are a requirement, `generateCompressedId` and normalization should be used instead.\n\t * See `IIdCompressor` for more details.\n\t * @returns A new local ID in session space.\n\t */\n\tgenerateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;\n\n\t/**\n\t * Normalizes a session space ID into op space.\n\t * The returned ID is in op space and can be safely serialized.\n\t * However, it should be {@link IIdCompressor.normalizeToSessionSpace|normalized back to session space} before use.\n\t * @param id - The local ID to normalize.\n\t * @returns The ID in op space.\n\t */\n\tnormalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;\n\n\t/**\n\t * Normalizes an ID into session space.\n\t * @param id - The ID to normalize.\n\t * @param originSessionId - The {@link IIdCompressor.localSessionId} of the compressor which {@link IIdCompressor.normalizeToOpSpace|encoded} `id`.\n\t * This might not be the client that created `id` in the first place, but rather the client that serialized it.\n\t * This is an important distinction in the case of a reference, where a client might refer to an ID created by another client.\n\t * @returns The session-space ID in the local session corresponding to `id`.\n\t * @remarks\n\t * For this to be valid, `originSessionId` must be the {@link IIdCompressor.localSessionId} of the compressor that normalized `id` to op space.\n\t * Additionally, this compressor must know about the relevant {@link IdCreationRange} from the encoding `IIdCompressor`.\n\t * This can be accomplished using creating the compressor using {@link (deserializeIdCompressor:1)},\n\t * or relying on something (like the Fluid runtime) to synchronize the range information using internal mechanisms.\n\t *\n\t * The {@link IIdCompressor} provided by the Fluid Framework runtime will automatically track {@link IdCreationRange| Id Creation Ranges} (via its own ops) from other clients in the container.\n\t * It is up to the user of the {@link IIdCompressor} to ensure the relevant session information is available,\n\t * either by depending on the originating client's session ID for ops, or by explicitly storing it alongside the data containing the {@link OpSpaceCompressedId}.\n\t *\n\t * Note that attachment summaries, while they are ops, are also interpreted as summaries without the context of their originating session,\n\t * so they should explicitly include session IDs if required to decode them just like regular summaries and exported data.\n\t */\n\tnormalizeToSessionSpace(\n\t\tid: OpSpaceCompressedId,\n\t\toriginSessionId: SessionId,\n\t): SessionSpaceCompressedId;\n\n\t/**\n\t * Attempts to normalize an op-space ID into session space without an originator session id.\n\t * This mainly exists for data recovery purposes, when the originator session id was lost.\n\t * When possible, use {@link IIdCompressor.normalizeToSessionSpace} instead.\n\t *\n\t * @remarks\n\t * When the id is a final ID, this will return the properly translated session-space ID,\n\t * or throw if it detects that the final id is not valid in this compressor.\n\t *\n\t * Returns `undefined` if `id` is a non-final op-space ID — those are local to the\n\t * originating session and require its session id to resolve. Callers which have the\n\t * originating session id should call {@link IIdCompressor.normalizeToSessionSpace} instead.\n\t *\n\t * @param id - The ID to normalize.\n\t * @returns The session-space ID corresponding to `id`, or `undefined` if `id` is\n\t * non-final and therefore requires an originator session id to resolve.\n\t * @throws If `id` is final but is not known to this compressor (i.e. it refers to\n\t * a final id that has never been observed as finalized).\n\t * Note that it is possible (even likely) for a finalized id from another id compressor to pass this check,\n\t * and return an incorrect session-space ID.\n\t * This error is thrown only in cases where it is possible to detect the input is invalid,\n\t * and intended to help with catching bugs where invalid identifiers are being provided.\n\t * It cannot be relied upon for validation.\n\t *\n\t * @privateRemarks\n\t * Currently this is only used for data recovery in the case of lost session ids,\n\t * but we could theoretically provide an API to determine if the session id is required when encoding data (some IDs were non-final):\n\t * in such a setup, this API, and/or a version of normalizeToSessionSpace where the session id is optional,\n\t * could be used for a regular non-recovery use-case.\n\t */\n\ttryNormalizeToSessionSpaceWithoutSession(\n\t\tid: OpSpaceCompressedId,\n\t): SessionSpaceCompressedId | undefined;\n\n\t/**\n\t * Decompresses a previously compressed ID into a UUID.\n\t * @param id - The compressed ID to be decompressed.\n\t * @returns The UUID associated with the compressed ID.\n\t * @throws If the ID was not generated by any session known to this compressor.\n\t */\n\tdecompress(id: SessionSpaceCompressedId): StableId;\n\n\t/**\n\t * Recompresses a UUID.\n\t * @param uncompressed - The UUID to recompress.\n\t * @returns The `CompressedId` associated with `uncompressed`.\n\t * @throws If the UUID was not generated by any session known to this compressor.\n\t */\n\trecompress(uncompressed: StableId): SessionSpaceCompressedId;\n\n\t/**\n\t * Attempts to recompress a UUID.\n\t * @param uncompressed - The UUID to recompress.\n\t * @returns The `CompressedId` associated with `uncompressed` or undefined if the UUID was not generated by any session known to this compressor.\n\t */\n\ttryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;\n}\n"]}

package/lib/types/index.d.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 export type { IdCreationRange, SerializedIdCompressor, SerializedIdCompressorWithNoSession, SerializedIdCompressorWithOngoingSession, } from "./persisted-types/index.js";
-export type { IIdCompressorCore, IIdCompressor } from "./idCompressor.js";
+export type { IIdCompressorCore, IIdCompressor, ShardToken, ShardSynchronizationToken, } from "./idCompressor.js";
+export { SerializationVersion, type SerializationVersion as SerializationVersionType, } from "./idCompressor.js";
 export type { SessionSpaceCompressedId, OpSpaceCompressedId, SessionId, StableId, } from "./identifiers.js";
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACX,eAAe,EACf,sBAAsB,EACtB,mCAAmC,EACnC,wCAAwC,GACxC,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE1E,YAAY,EACX,wBAAwB,EACxB,mBAAmB,EACnB,SAAS,EACT,QAAQ,GACR,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACX,eAAe,EACf,sBAAsB,EACtB,mCAAmC,EACnC,wCAAwC,GACxC,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACX,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,yBAAyB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,oBAAoB,EACpB,KAAK,oBAAoB,IAAI,wBAAwB,GACrD,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACX,wBAAwB,EACxB,mBAAmB,EACnB,SAAS,EACT,QAAQ,GACR,MAAM,kBAAkB,CAAC"}

package/lib/types/index.js

@@ -2,5 +2,5 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-export {};
+export { SerializationVersion, } from "./idCompressor.js";
 //# sourceMappingURL=index.js.map

package/lib/types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type {\n\tIdCreationRange,\n\tSerializedIdCompressor,\n\tSerializedIdCompressorWithNoSession,\n\tSerializedIdCompressorWithOngoingSession,\n} from \"./persisted-types/index.js\";\n\nexport type { IIdCompressorCore, IIdCompressor } from \"./idCompressor.js\";\n\nexport type {\n\tSessionSpaceCompressedId,\n\tOpSpaceCompressedId,\n\tSessionId,\n\tStableId,\n} from \"./identifiers.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,OAAO,EACN,oBAAoB,GAEpB,MAAM,mBAAmB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nexport type {\n\tIdCreationRange,\n\tSerializedIdCompressor,\n\tSerializedIdCompressorWithNoSession,\n\tSerializedIdCompressorWithOngoingSession,\n} from \"./persisted-types/index.js\";\n\nexport type {\n\tIIdCompressorCore,\n\tIIdCompressor,\n\tShardToken,\n\tShardSynchronizationToken,\n} from \"./idCompressor.js\";\nexport {\n\tSerializationVersion,\n\ttype SerializationVersion as SerializationVersionType,\n} from \"./idCompressor.js\";\n\nexport type {\n\tSessionSpaceCompressedId,\n\tOpSpaceCompressedId,\n\tSessionId,\n\tStableId,\n} from \"./identifiers.js\";\n"]}

package/lib/types/persisted-types/0.0.1.d.ts

@@ -5,21 +5,21 @@
 import type { SessionId } from "../identifiers.js";
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
- * @legacy @beta
+ * @internal
  */
 export type SerializedIdCompressor = string & {
     readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5";
 };
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
- * @legacy @beta
+ * @internal
  */
 export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {
     readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb";
 };
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
- * @legacy @beta
+ * @internal
  */
 export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {
     readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb";
@@ -28,7 +28,7 @@ export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor &
  * Data describing a range of session-local IDs (from a remote or local session).
  *
  * A range is composed of local IDs that were generated.
- * @legacy @beta
+ * @internal
  */
 export interface IdCreationRange {
     readonly sessionId: SessionId;

package/lib/types/persisted-types/0.0.1.js.map

@@ -1 +1 @@
-{"version":3,"file":"0.0.1.js","sourceRoot":"","sources":["../../../src/types/persisted-types/0.0.1.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { SessionId } from \"../identifiers.js\";\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @legacy @beta\n */\nexport type SerializedIdCompressor = string & {\n\treadonly _serializedIdCompressor: \"8c73c57c-1cf4-4278-8915-6444cb4f6af5\";\n};\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @legacy @beta\n */\nexport type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {\n\treadonly _noLocalState: \"3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb\";\n};\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @legacy @beta\n */\nexport type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {\n\treadonly _hasLocalState: \"1281acae-6d14-47e7-bc92-71c8ee0819cb\";\n};\n\n/**\n * Data describing a range of session-local IDs (from a remote or local session).\n *\n * A range is composed of local IDs that were generated.\n * @legacy @beta\n */\nexport interface IdCreationRange {\n\treadonly sessionId: SessionId;\n\treadonly ids?: {\n\t\t/**\n\t\t * The gen count of the first ID in the range created by `sessionId.`\n\t\t */\n\t\treadonly firstGenCount: number;\n\n\t\t/**\n\t\t * The number of IDs created in the range created by `sessionId.`\n\t\t */\n\t\treadonly count: number;\n\n\t\t/**\n\t\t * The size of the ID cluster to create if `count` overflows the existing cluster for\n\t\t * `sessionId`, if one exists. This request will be respected, and the size of the cluster\n\t\t * will be equal to overflow + `requestedClusterSize`.\n\t\t */\n\t\treadonly requestedClusterSize: number;\n\n\t\t/**\n\t\t * The ranges of IDs that were allocated as local IDs in the range created by `sessionId.`\n\t\t */\n\t\treadonly localIdRanges: [genCount: number, count: number][];\n\t};\n}\n"]}
+{"version":3,"file":"0.0.1.js","sourceRoot":"","sources":["../../../src/types/persisted-types/0.0.1.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { SessionId } from \"../identifiers.js\";\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @internal\n */\nexport type SerializedIdCompressor = string & {\n\treadonly _serializedIdCompressor: \"8c73c57c-1cf4-4278-8915-6444cb4f6af5\";\n};\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @internal\n */\nexport type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {\n\treadonly _noLocalState: \"3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb\";\n};\n\n/**\n * The serialized contents of an IdCompressor, suitable for persistence in a summary.\n * @internal\n */\nexport type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {\n\treadonly _hasLocalState: \"1281acae-6d14-47e7-bc92-71c8ee0819cb\";\n};\n\n/**\n * Data describing a range of session-local IDs (from a remote or local session).\n *\n * A range is composed of local IDs that were generated.\n * @internal\n */\nexport interface IdCreationRange {\n\treadonly sessionId: SessionId;\n\treadonly ids?: {\n\t\t/**\n\t\t * The gen count of the first ID in the range created by `sessionId.`\n\t\t */\n\t\treadonly firstGenCount: number;\n\n\t\t/**\n\t\t * The number of IDs created in the range created by `sessionId.`\n\t\t */\n\t\treadonly count: number;\n\n\t\t/**\n\t\t * The size of the ID cluster to create if `count` overflows the existing cluster for\n\t\t * `sessionId`, if one exists. This request will be respected, and the size of the cluster\n\t\t * will be equal to overflow + `requestedClusterSize`.\n\t\t */\n\t\treadonly requestedClusterSize: number;\n\n\t\t/**\n\t\t * The ranges of IDs that were allocated as local IDs in the range created by `sessionId.`\n\t\t */\n\t\treadonly localIdRanges: [genCount: number, count: number][];\n\t};\n}\n"]}

package/lib/utilities.d.ts

@@ -6,7 +6,7 @@ import type { LocalCompressedId, NumericUuid } from "./identifiers.js";
 import type { SessionId, StableId } from "./types/index.js";
 /**
  * Generate a random session ID
- * @legacy @beta
+ * @internal
  */
 export declare function createSessionId(): SessionId;
 /**

package/lib/utilities.js

@@ -13,7 +13,7 @@ function isHexadecimalCharacter(charCode) {
 }
 /**
  * Generate a random session ID
- * @legacy @beta
+ * @internal
  */
 export function createSessionId() {
     return assertIsStableId(v4());

package/lib/utilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../src/utilities.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 no-bitwise */\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { v4 } from \"uuid\";\n\nimport type { LocalCompressedId, NumericUuid } from \"./identifiers.js\";\nimport type { SessionId, StableId } from \"./types/index.js\";\n\nconst hexadecimalCharCodes = [...\"09afAF\"].map((c) => c.codePointAt(0)) as [\n\tzero: number,\n\tnine: number,\n\ta: number,\n\tf: number,\n\tA: number,\n\tF: number,\n];\n\nfunction isHexadecimalCharacter(charCode: number): boolean {\n\treturn (\n\t\t(charCode >= hexadecimalCharCodes[0] && charCode <= hexadecimalCharCodes[1]) ||\n\t\t(charCode >= hexadecimalCharCodes[2] && charCode <= hexadecimalCharCodes[3]) ||\n\t\t(charCode >= hexadecimalCharCodes[4] && charCode <= hexadecimalCharCodes[5])\n\t);\n}\n\n/**\n * Generate a random session ID\n * @legacy @beta\n */\nexport function createSessionId(): SessionId {\n\treturn assertIsStableId(v4()) as SessionId;\n}\n\n/**\n * Asserts that the given string is a stable ID.\n * @internal\n */\nexport function assertIsStableId(stableId: string): StableId {\n\tassert(isStableId(stableId), 0x4a3 /* Expected a StableId */);\n\treturn stableId;\n}\n\n/**\n * Asserts that the given string is a stable ID.\n */\nexport function assertIsSessionId(stableId: string): SessionId {\n\tassertIsStableId(stableId);\n\treturn stableId as SessionId;\n}\n\n/**\n * Generate a random stable ID\n * @internal\n */\nexport function generateStableId(): StableId {\n\treturn assertIsStableId(v4());\n}\n\n/**\n * Returns true iff the given string is a valid Version 4, variant 2 UUID\n * 'xxxxxxxx-xxxx-4xxx-vxxx-xxxxxxxxxxxx'\n * @internal\n */\nexport function isStableId(str: string): str is StableId {\n\tif (str.length !== 36) {\n\t\treturn false;\n\t}\n\n\tfor (let i = 0; i < str.length; i++) {\n\t\tswitch (i) {\n\t\t\tcase 8:\n\t\t\tcase 13:\n\t\t\tcase 18:\n\t\t\tcase 23: {\n\t\t\t\tif (str.charAt(i) !== \"-\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase 14: {\n\t\t\t\tif (str.charAt(i) !== \"4\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase 19: {\n\t\t\t\tconst char = str.charAt(i);\n\t\t\t\tif (char !== \"8\" && char !== \"9\" && char !== \"a\" && char !== \"b\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tdefault: {\n\t\t\t\tconst codePoint = str.codePointAt(i);\n\t\t\t\tassert(codePoint !== undefined, 0xaaf /* Unexpected undefined code point */);\n\t\t\t\tif (!isHexadecimalCharacter(codePoint)) {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/**\n * A numeric comparator used for sorting in ascending order.\n *\n * Handles +/-0 like Map: -0 is equal to +0.\n */\nexport function compareFiniteNumbers<T extends number>(a: T, b: T): number {\n\treturn a - b;\n}\n\n/**\n * Compares strings lexically to form a strict partial ordering.\n */\nexport function compareStrings<T extends string>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n\n/**\n * Compares bigints to form a strict partial ordering.\n */\nexport function compareBigints<T extends bigint>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n\nexport function genCountFromLocalId(localId: LocalCompressedId): number {\n\t// eslint-disable-next-line @typescript-eslint/no-unsafe-unary-minus\n\treturn -localId;\n}\n\nexport function localIdFromGenCount(genCount: number): LocalCompressedId {\n\treturn -genCount as LocalCompressedId;\n}\n\n// xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx\nconst versionMask = 0x4n << (19n * 4n); // Version 4\nconst variantMask = 0x8n << (15n * 4n); // Variant RFC4122 (1 0 x x)\nconst upperMask = 0xffffffffffffn << (20n * 4n);\n// Upper mask when version/variant bits are removed\nconst strippedUpperMask = upperMask >> 6n;\nconst middieBittiesMask = 0xfffn << (16n * 4n);\n// Middie mask when version/variant bits are removed\nconst strippedMiddieBittiesMask = middieBittiesMask >> 2n;\n// Note: leading character should be 3 to mask at 0011\n// The more-significant half of the N nibble is used to denote the variant (10xx)\nconst lowerMask = 0x3fffffffffffffffn;\n\nexport function numericUuidFromStableId(stableId: StableId): NumericUuid {\n\tconst uuidU128 = BigInt(`0x${stableId.replace(/-/g, \"\")}`);\n\tconst upperMasked = uuidU128 & upperMask;\n\tconst middieBittiesMasked = uuidU128 & middieBittiesMask;\n\tconst lowerMasked = uuidU128 & lowerMask;\n\n\tconst upperMaskedPlaced = upperMasked >> 6n;\n\tconst middieBittiesMaskedPlaced = middieBittiesMasked >> 2n;\n\n\tconst id = upperMaskedPlaced | middieBittiesMaskedPlaced | lowerMasked;\n\treturn id as NumericUuid;\n}\n\nexport function stableIdFromNumericUuid(numericUuid: NumericUuid): StableId {\n\t// bitwise reverse transform\n\tconst upperMasked = (numericUuid & strippedUpperMask) << 6n;\n\tconst middieBittiesMasked = (numericUuid & strippedMiddieBittiesMask) << 2n;\n\tconst lowerMasked = numericUuid & lowerMask;\n\tconst uuidU128 = upperMasked | versionMask | middieBittiesMasked | variantMask | lowerMasked;\n\t// Pad to 32 characters, inserting leading zeroes if needed\n\tconst uuidString = uuidU128.toString(16).padStart(32, \"0\");\n\treturn `${uuidString.slice(0, 8)}-${uuidString.slice(8, 12)}-${uuidString.slice(\n\t\t12,\n\t\t16,\n\t)}-${uuidString.slice(16, 20)}-${uuidString.slice(20, 32)}` as StableId;\n}\n\nexport function offsetNumericUuid(numericUuid: NumericUuid, offset: number): NumericUuid {\n\treturn (numericUuid + BigInt(offset)) as NumericUuid;\n}\n\nexport function subtractNumericUuids(a: NumericUuid, b: NumericUuid): NumericUuid {\n\treturn (a - b) as NumericUuid;\n}\n\nexport function addNumericUuids(a: NumericUuid, b: NumericUuid): NumericUuid {\n\treturn (a + b) as NumericUuid;\n}\n"]}
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../src/utilities.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 no-bitwise */\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { v4 } from \"uuid\";\n\nimport type { LocalCompressedId, NumericUuid } from \"./identifiers.js\";\nimport type { SessionId, StableId } from \"./types/index.js\";\n\nconst hexadecimalCharCodes = [...\"09afAF\"].map((c) => c.codePointAt(0)) as [\n\tzero: number,\n\tnine: number,\n\ta: number,\n\tf: number,\n\tA: number,\n\tF: number,\n];\n\nfunction isHexadecimalCharacter(charCode: number): boolean {\n\treturn (\n\t\t(charCode >= hexadecimalCharCodes[0] && charCode <= hexadecimalCharCodes[1]) ||\n\t\t(charCode >= hexadecimalCharCodes[2] && charCode <= hexadecimalCharCodes[3]) ||\n\t\t(charCode >= hexadecimalCharCodes[4] && charCode <= hexadecimalCharCodes[5])\n\t);\n}\n\n/**\n * Generate a random session ID\n * @internal\n */\nexport function createSessionId(): SessionId {\n\treturn assertIsStableId(v4()) as SessionId;\n}\n\n/**\n * Asserts that the given string is a stable ID.\n * @internal\n */\nexport function assertIsStableId(stableId: string): StableId {\n\tassert(isStableId(stableId), 0x4a3 /* Expected a StableId */);\n\treturn stableId;\n}\n\n/**\n * Asserts that the given string is a stable ID.\n */\nexport function assertIsSessionId(stableId: string): SessionId {\n\tassertIsStableId(stableId);\n\treturn stableId as SessionId;\n}\n\n/**\n * Generate a random stable ID\n * @internal\n */\nexport function generateStableId(): StableId {\n\treturn assertIsStableId(v4());\n}\n\n/**\n * Returns true iff the given string is a valid Version 4, variant 2 UUID\n * 'xxxxxxxx-xxxx-4xxx-vxxx-xxxxxxxxxxxx'\n * @internal\n */\nexport function isStableId(str: string): str is StableId {\n\tif (str.length !== 36) {\n\t\treturn false;\n\t}\n\n\tfor (let i = 0; i < str.length; i++) {\n\t\tswitch (i) {\n\t\t\tcase 8:\n\t\t\tcase 13:\n\t\t\tcase 18:\n\t\t\tcase 23: {\n\t\t\t\tif (str.charAt(i) !== \"-\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase 14: {\n\t\t\t\tif (str.charAt(i) !== \"4\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tcase 19: {\n\t\t\t\tconst char = str.charAt(i);\n\t\t\t\tif (char !== \"8\" && char !== \"9\" && char !== \"a\" && char !== \"b\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\tdefault: {\n\t\t\t\tconst codePoint = str.codePointAt(i);\n\t\t\t\tassert(codePoint !== undefined, 0xaaf /* Unexpected undefined code point */);\n\t\t\t\tif (!isHexadecimalCharacter(codePoint)) {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t}\n\n\treturn true;\n}\n\n/**\n * A numeric comparator used for sorting in ascending order.\n *\n * Handles +/-0 like Map: -0 is equal to +0.\n */\nexport function compareFiniteNumbers<T extends number>(a: T, b: T): number {\n\treturn a - b;\n}\n\n/**\n * Compares strings lexically to form a strict partial ordering.\n */\nexport function compareStrings<T extends string>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n\n/**\n * Compares bigints to form a strict partial ordering.\n */\nexport function compareBigints<T extends bigint>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n\nexport function genCountFromLocalId(localId: LocalCompressedId): number {\n\t// eslint-disable-next-line @typescript-eslint/no-unsafe-unary-minus\n\treturn -localId;\n}\n\nexport function localIdFromGenCount(genCount: number): LocalCompressedId {\n\treturn -genCount as LocalCompressedId;\n}\n\n// xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx\nconst versionMask = 0x4n << (19n * 4n); // Version 4\nconst variantMask = 0x8n << (15n * 4n); // Variant RFC4122 (1 0 x x)\nconst upperMask = 0xffffffffffffn << (20n * 4n);\n// Upper mask when version/variant bits are removed\nconst strippedUpperMask = upperMask >> 6n;\nconst middieBittiesMask = 0xfffn << (16n * 4n);\n// Middie mask when version/variant bits are removed\nconst strippedMiddieBittiesMask = middieBittiesMask >> 2n;\n// Note: leading character should be 3 to mask at 0011\n// The more-significant half of the N nibble is used to denote the variant (10xx)\nconst lowerMask = 0x3fffffffffffffffn;\n\nexport function numericUuidFromStableId(stableId: StableId): NumericUuid {\n\tconst uuidU128 = BigInt(`0x${stableId.replace(/-/g, \"\")}`);\n\tconst upperMasked = uuidU128 & upperMask;\n\tconst middieBittiesMasked = uuidU128 & middieBittiesMask;\n\tconst lowerMasked = uuidU128 & lowerMask;\n\n\tconst upperMaskedPlaced = upperMasked >> 6n;\n\tconst middieBittiesMaskedPlaced = middieBittiesMasked >> 2n;\n\n\tconst id = upperMaskedPlaced | middieBittiesMaskedPlaced | lowerMasked;\n\treturn id as NumericUuid;\n}\n\nexport function stableIdFromNumericUuid(numericUuid: NumericUuid): StableId {\n\t// bitwise reverse transform\n\tconst upperMasked = (numericUuid & strippedUpperMask) << 6n;\n\tconst middieBittiesMasked = (numericUuid & strippedMiddieBittiesMask) << 2n;\n\tconst lowerMasked = numericUuid & lowerMask;\n\tconst uuidU128 = upperMasked | versionMask | middieBittiesMasked | variantMask | lowerMasked;\n\t// Pad to 32 characters, inserting leading zeroes if needed\n\tconst uuidString = uuidU128.toString(16).padStart(32, \"0\");\n\treturn `${uuidString.slice(0, 8)}-${uuidString.slice(8, 12)}-${uuidString.slice(\n\t\t12,\n\t\t16,\n\t)}-${uuidString.slice(16, 20)}-${uuidString.slice(20, 32)}` as StableId;\n}\n\nexport function offsetNumericUuid(numericUuid: NumericUuid, offset: number): NumericUuid {\n\treturn (numericUuid + BigInt(offset)) as NumericUuid;\n}\n\nexport function subtractNumericUuids(a: NumericUuid, b: NumericUuid): NumericUuid {\n\treturn (a - b) as NumericUuid;\n}\n\nexport function addNumericUuids(a: NumericUuid, b: NumericUuid): NumericUuid {\n\treturn (a + b) as NumericUuid;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/id-compressor",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "ID compressor",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -61,24 +61,24 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": "~3.2.0",
-    "@fluidframework/core-interfaces": "~3.2.0",
-    "@fluidframework/core-utils": "~3.2.0",
-    "@fluidframework/telemetry-utils": "~3.2.0",
+    "@fluid-internal/client-utils": "~3.3.0",
+    "@fluidframework/core-interfaces": "~3.3.0",
+    "@fluidframework/core-utils": "~3.3.0",
+    "@fluidframework/telemetry-utils": "~3.3.0",
     "@tylerbu/sorted-btree-es6": "^2.1.1",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "~2.4.5",
-    "@fluid-internal/mocha-test-setup": "~3.2.0",
-    "@fluid-private/stochastic-test-utils": "~3.2.0",
+    "@fluid-internal/mocha-test-setup": "~3.3.0",
+    "@fluid-private/stochastic-test-utils": "~3.3.0",
     "@fluid-tools/benchmark": "^0.59.0",
     "@fluid-tools/build-cli": "^0.67.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.67.0",
     "@fluidframework/eslint-config-fluid": "^14.0.0",
-    "@fluidframework/id-compressor-previous": "npm:@fluidframework/id-compressor@3.1.0",
+    "@fluidframework/id-compressor-previous": "npm:@fluidframework/id-compressor@3.2.0",
     "@microsoft/api-extractor": "7.58.1",
     "@types/mocha": "^10.0.10",
     "@types/node": "~22.19.17",
@@ -94,7 +94,40 @@
     "typescript": "~6.0.3"
   },
   "typeValidation": {
-    "broken": {},
+    "broken": {
+      "Function_createIdCompressor": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "Function_deserializeIdCompressor": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "Function_createSessionId": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "Function_serializeIdCompressor": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "Interface_IdCreationRange": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_SerializedIdCompressor": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_SerializedIdCompressorWithNoSession": {
+        "backCompat": false,
+        "forwardCompat": false
+      },
+      "TypeAlias_SerializedIdCompressorWithOngoingSession": {
+        "backCompat": false,
+        "forwardCompat": false
+      }
+    },
     "entrypoint": "legacy"
   },
   "scripts": {