@fluidframework/id-compressor 2.0.0-rc.1.0.6 → 2.0.0-rc.2.0.1

package/dist/id-compressor-beta.d.ts

@@ -1,4 +1,5 @@
 import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
 
 /* Excluded from this release type: assertIsStableId */
 
@@ -10,112 +11,118 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: generateStableId */
 
-/* Excluded from this release type: IdCompressor */
-
 /* Excluded from this release type: IdCreationRange */
 
 /**
  * A distributed UUID generator and compressor.
- *
- * Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple "sessions" (which can be distributed across the network),
- * providing each session with the ability to map these UUIDs to `numbers`.
- *
- * A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API
- * which should then sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is
- * created it is said to be created by the compressor's "local" session.
- *
- * For each stable ID created, two numeric IDs are provided by the compressor:
- *
- * 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
- * be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only
- * safely usable within the scope of the compressor that created it.
- *
- * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing
- * the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations.
- * Final IDs are known to and publicly usable by any compressor that has received them.
- *
- * Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed
- * to map the UUIDs to the numbers.
- *
- * The following invariants are upheld by IdCompressor:
- *
- * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.
- *
- * 2. Final IDs will always decompress to the same UUIDs.
- *
- * 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
- * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the
- * same final ID.
- *
- * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.
- *
- * Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*
- * be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.
- *
- * Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This
- * could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a
- * 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
- * produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the
- * session-local IDs have been finalized, the compressor defines two "spaces" of IDs:
- *
- * 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
- * will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after
- * 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
- * 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
- * these IDs across compressor objects, as the local IDs are specific to the compressor that created them.
- *
- * 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
- * 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
- * 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
- * out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a "more final form".
- * Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially
- * 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
- * "local as possible".
- *
- * 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.
+ * `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 declare 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, originSessionId: SessionId): SessionSpaceCompressedId;
     /**
      * 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/dist/id-compressor-public.d.ts

@@ -1,4 +1,5 @@
 import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import { ITelemetryLoggerExt } from '@fluidframework/telemetry-utils';
 
 /* Excluded from this release type: assertIsStableId */
 
@@ -10,112 +11,118 @@ import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
 
 /* Excluded from this release type: generateStableId */
 
-/* Excluded from this release type: IdCompressor */
-
 /* Excluded from this release type: IdCreationRange */
 
 /**
  * A distributed UUID generator and compressor.
- *
- * Generates arbitrary non-colliding v4 UUIDs, called stable IDs, for multiple "sessions" (which can be distributed across the network),
- * providing each session with the ability to map these UUIDs to `numbers`.
- *
- * A session is a unique identifier that denotes a single compressor. New IDs are created through a single compressor API
- * which should then sent in ranges to the server for total ordering (and are subsequently relayed to other clients). When a new ID is
- * created it is said to be created by the compressor's "local" session.
- *
- * For each stable ID created, two numeric IDs are provided by the compressor:
- *
- * 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
- * be serialized for offline usage). Available as soon as the stable ID is allocated. These IDs are session-unique and are thus only
- * safely usable within the scope of the compressor that created it.
- *
- * 2. A final ID, which is stable across serialization and deserialization of an IdCompressor. Available as soon as the range containing
- * the corresponding session-local ID is totally ordered (via consensus) with respect to other sessions' allocations.
- * Final IDs are known to and publicly usable by any compressor that has received them.
- *
- * Compressors will allocate UUIDs in non-random ways to reduce entropy allowing for optimized storage of the data needed
- * to map the UUIDs to the numbers.
- *
- * The following invariants are upheld by IdCompressor:
- *
- * 1. Session-local IDs will always decompress to the same UUIDs for the lifetime of the session.
- *
- * 2. Final IDs will always decompress to the same UUIDs.
- *
- * 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
- * translated by the compressor into the corresponding final ID. For any given session-local ID, this translation will always yield the
- * same final ID.
- *
- * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.
- *
- * Session-local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*
- * be ordered (i.e. sent to the server) in the order they are created in order to preserve the above invariants.
- *
- * Session-local IDs can be used immediately after creation, but will eventually (after being sequenced) have a corresponding final ID. This
- * could make reasoning about equality of those two forms difficult. For example, if a cache is keyed off of a
- * 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
- * produce a cache miss. In order to make using collections of both remotely created and locally created IDs easy, regardless of whether the
- * session-local IDs have been finalized, the compressor defines two "spaces" of IDs:
- *
- * 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
- * will be in local form, regardless of if they have been finalized. Remotely created IDs, which could only have been received after
- * 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
- * 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
- * these IDs across compressor objects, as the local IDs are specific to the compressor that created them.
- *
- * 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
- * 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
- * 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
- * out of Op space over time, namely, when a session-local ID in this space becomes finalized, and thereafter has a "more final form".
- * Consequentially, it may be useful to restrict parameters of a persisted type to this space (to optimize perf), but it is potentially
- * 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
- * "local as possible".
- *
- * 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.
+ * `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 declare 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, originSessionId: SessionId): SessionSpaceCompressedId;
     /**
      * 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;
 }