IIdCompressor Interface

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 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)

// 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);

Signature

export interface IIdCompressor

Properties

Property	Type	Description
localSessionId	SessionId	The local session ID.

Methods

Method	Return Type	Description
decompress(id)	StableId	Decompresses a previously compressed ID into a UUID.
generateCompressedId()	SessionSpaceCompressedId	Generates a new compressed ID. The returned ID is in session space and should not be serialized directly. See IIdCompressor for more details.
generateDocumentUniqueId()	(SessionSpaceCompressedId & OpSpaceCompressedId) | StableId	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.
normalizeToOpSpace(id)	OpSpaceCompressedId	Normalizes a session space ID into 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.
normalizeToSessionSpace(id, originSessionId)	SessionSpaceCompressedId	Normalizes an ID into session space.
recompress(uncompressed)	SessionSpaceCompressedId	Recompresses a UUID.
tryRecompress(uncompressed)	SessionSpaceCompressedId | undefined	Attempts to recompress a UUID.

Property Details

localSessionId

The local session ID.

Signature

localSessionId: SessionId;

Type: SessionId

Method Details

decompress

Decompresses a previously compressed ID into a UUID.

Signature

decompress(id: SessionSpaceCompressedId): StableId;

Parameters

Parameter	Type	Description
id	SessionSpaceCompressedId	The compressed ID to be decompressed.

Returns

The UUID associated with the compressed ID.

Return type: StableId

Error Handling

If the ID was not generated by any session known to this compressor.

generateCompressedId

Generates a new compressed ID. The returned ID is in session space and should not be serialized directly. See IIdCompressor for more details.

Signature

generateCompressedId(): SessionSpaceCompressedId;

Returns

A new local ID in session space.

Return type: SessionSpaceCompressedId

generateDocumentUniqueId

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.

Signature

generateDocumentUniqueId(): (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId;

Returns

A new local ID in session space.

Return type: (SessionSpaceCompressedId & OpSpaceCompressedId) | StableId

normalizeToOpSpace

Normalizes a session space ID into 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.

Signature

normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;

Parameters

Parameter	Type	Description
id	SessionSpaceCompressedId	The local ID to normalize.

Returns

The ID in op space.

Return type: OpSpaceCompressedId

normalizeToSessionSpace

Normalizes an ID into session space.

Signature

normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;

Parameters

Parameter	Type	Description
id	OpSpaceCompressedId	The ID to normalize.
originSessionId	SessionId	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.

Return type: SessionSpaceCompressedId

recompress

Recompresses a UUID.

Signature

recompress(uncompressed: StableId): SessionSpaceCompressedId;

Parameters

Parameter	Type	Description
uncompressed	StableId	The UUID to recompress.

Returns

The CompressedId associated with uncompressed.

Return type: SessionSpaceCompressedId

Error Handling

If the UUID was not generated by any session known to this compressor.

tryRecompress

Attempts to recompress a UUID.

Signature

tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;

Parameters

Parameter	Type	Description
uncompressed	StableId	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.

Return type: SessionSpaceCompressedId | undefined