@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. 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 Example Usage: ### Client A (Sender)
### Client B (Receiver)
|
|
IIdCompressorCore | Legacy |
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 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:
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:
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:
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. |
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 & IIdCompressorCore | Create a new IIdCompressor. |
createIdCompressor(sessionId, logger) | Legacy |
IIdCompressor & IIdCompressorCore | Create a new IIdCompressor. |
createSessionId() | Legacy |
SessionId | Generate a random session ID |
deserializeIdCompressor(serialized, logger) | Legacy |
IIdCompressor & IIdCompressorCore | Deserializes the supplied state into an ID compressor. |
deserializeIdCompressor(serialized, newSessionId, logger) | Legacy |
IIdCompressor & IIdCompressorCore | Deserializes the supplied state into an ID compressor. |
Function Details
createIdCompressor
Create a new IIdCompressor. \
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 & IIdCompressorCore;
Parameters
Parameter | Modifiers | Type | Description |
---|---|---|---|
logger | optional | ITelemetryBaseLogger |
Returns
Return type: IIdCompressor & IIdCompressorCore
createIdCompressor
Create a new IIdCompressor.
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 & IIdCompressorCore;
Parameters
Parameter | Modifiers | Type | Description |
---|---|---|---|
sessionId | SessionId | The seed ID for the compressor. |
|
logger | optional | ITelemetryBaseLogger |
Returns
Return type: IIdCompressor & IIdCompressorCore
createSessionId
Generate a random session ID \
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. \
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 & IIdCompressorCore;
Parameters
Parameter | Modifiers | Type | Description |
---|---|---|---|
serialized | SerializedIdCompressorWithOngoingSession | ||
logger | optional | ITelemetryLoggerExt |
Returns
Return type: IIdCompressor & IIdCompressorCore
deserializeIdCompressor
Deserializes the supplied state into an ID compressor. \
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 & IIdCompressorCore;
Parameters
Parameter | Modifiers | Type | Description |
---|---|---|---|
serialized | SerializedIdCompressorWithNoSession | ||
newSessionId | SessionId | ||
logger | optional | ITelemetryLoggerExt |
Returns
Return type: IIdCompressor & IIdCompressorCore