@fluidframework/id-compressor Package

Interfaces

Interface	Alerts	Description
IdCreationRange	Legacy	Data describing a range of session-local IDs (from a remote or local session). A range is composed of local IDs that were generated.
IIdCompressor		A distributed UUID generator and compressor. IdCompressor offers the ability to generate arbitrary non-colliding v4 UUIDs, called stable IDs, while compressing them into small integers for efficient storage and transmission. It also provides the ability to decompress these integers back into their original UUIDs. The compressor is designed to be used in a distributed environment, where multiple clients may be generating IDs concurrently. IDs generated by a compressor, via calls to generateCompressedId, are created in the compressor's "local" session. These IDs are unique within the session, but may not be unique across sessions. In the context of Fluid, the scope of a session is the same as the scope of a container. This means that anytime IDs are transferred between sessions, they must be translated through a process called "normalization": - The scope of a local session (in which local IDs are unique) is called the "session space" of the client. - The context of persisted state (in Fluid, this is the context of ops and summaries) is called "op space". - SessionSpaceCompressedIds, 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) // Generate several local IDsconst localId1 = idCompressor.generateCompressedId();const localId2 = idCompressor.generateCompressedId();const localId3 = idCompressor.generateCompressedId();// Normalize these IDs to op space for inclusion in a messageconst 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 summaryconst message = { sessionID: idCompressor.localSessionId, ids: [opSpaceId1, opSpaceId2, opSpaceId3]}; ### Client B (Receiver) // Receive the message from Client Aconst receivedMessage = ...; // In Fluid, this would be an op or summary// Normalize the received IDs back to session space, utilizing the sender's session IDconst 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);

Types

TypeAlias	Alerts	Description
OpSpaceCompressedId		A compressed ID that has been normalized into "op space". Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require less normalizing when received by a remote client due to the fact that op space for a given compressor is session space for all other compressors.
SerializedIdCompressor	Legacy	The serialized contents of an IdCompressor, suitable for persistence in a summary.
SerializedIdCompressorWithNoSession	Legacy	The serialized contents of an IdCompressor, suitable for persistence in a summary.
SerializedIdCompressorWithOngoingSession	Legacy	The serialized contents of an IdCompressor, suitable for persistence in a summary.
SessionId		A StableId which is suitable for use as a session identifier
SessionSpaceCompressedId		A compressed ID that has been normalized into "session space" (see IdCompressor for more). Consumer-facing APIs and data structures should use session-space IDs as their lifetime and equality is stable and tied to the scope of the session (i.e. compressor) that produced them.
StableId		A version 4, variant 1 uuid. A 128-bit Universally Unique IDentifier. Represented here with a string of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x is a lowercase hex digit.

Functions

Function	Alerts	Return Type	Description
createIdCompressor(logger)	Legacy	IIdCompressor	Create a new IIdCompressor.
createIdCompressor(sessionId, logger)	Legacy	IIdCompressor	Create a new IIdCompressor.
createSessionId()	Legacy	SessionId	Generate a random session ID
deserializeIdCompressor(serialized, logger)	Legacy	IIdCompressor	Deserializes the supplied state into an ID compressor.
deserializeIdCompressor(serialized, newSessionId, logger)	Legacy	IIdCompressor	Deserializes the supplied state into an ID compressor.
serializeIdCompressor(compressor, withSession)	Legacy	SerializedIdCompressorWithOngoingSession	Serializes an ID compressor.
serializeIdCompressor(compressor, withSession)	Legacy	SerializedIdCompressorWithNoSession	Serializes an ID compressor.

Function Details

createIdCompressor

Create a new IIdCompressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function createIdCompressor(logger?: ITelemetryBaseLogger): IIdCompressor;

Parameters

Parameter	Modifiers	Type	Description
logger	optional	ITelemetryBaseLogger

Returns

Return type: IIdCompressor

createIdCompressor

Create a new IIdCompressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function createIdCompressor(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor;

Parameters

Parameter	Modifiers	Type	Description
sessionId		SessionId	The seed ID for the compressor.
logger	optional	ITelemetryBaseLogger

Returns

Return type: IIdCompressor

createSessionId

Generate a random session ID

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function createSessionId(): SessionId;

Returns

Return type: SessionId

deserializeIdCompressor

Deserializes the supplied state into an ID compressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession, logger?: ITelemetryLoggerExt): IIdCompressor;

Parameters

Parameter	Modifiers	Type	Description
serialized		SerializedIdCompressorWithOngoingSession
logger	optional	ITelemetryLoggerExt

Returns

Return type: IIdCompressor

deserializeIdCompressor

Deserializes the supplied state into an ID compressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId, logger?: ITelemetryLoggerExt): IIdCompressor;

Parameters

Parameter	Modifiers	Type	Description
serialized		SerializedIdCompressorWithNoSession
newSessionId		SessionId
logger	optional	ITelemetryLoggerExt

Returns

Return type: IIdCompressor

serializeIdCompressor

Serializes an ID compressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function serializeIdCompressor(compressor: IIdCompressor, withSession: true): SerializedIdCompressorWithOngoingSession;

Parameters

Parameter	Type	Description
compressor	IIdCompressor	The compressor to serialize.
withSession	true	If true, the serialized state will include local session state (for stashing). If false, only finalized state is included (for summaries).

Returns

Return type: SerializedIdCompressorWithOngoingSession

serializeIdCompressor

Serializes an ID compressor.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/id-compressor/legacy.

For more information about our API support guarantees, see here.

Signature

export declare function serializeIdCompressor(compressor: IIdCompressor, withSession: false): SerializedIdCompressorWithNoSession;

Parameters

Parameter	Type	Description
compressor	IIdCompressor	The compressor to serialize.
withSession	false	If true, the serialized state will include local session state (for stashing). If false, only finalized state is included (for summaries).

Returns

Return type: SerializedIdCompressorWithNoSession