@fluidframework/runtime-definitions 2.0.0-internal.6.1.0 → 2.0.0-internal.6.2.0

package/src/id-compressor/idCompressor.ts

@@ -3,13 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
-	SessionSpaceCompressedId,
-	OpSpaceCompressedId,
-	SessionId,
-	FinalCompressedId,
-	StableId,
-} from "./identifiers";
+import { SessionSpaceCompressedId, OpSpaceCompressedId, SessionId, StableId } from "./identifiers";
 import {
 	IdCreationRange,
 	SerializedIdCompressorWithNoSession,
@@ -17,7 +11,13 @@ import {
 } from "./persisted-types";
 
 export interface IIdCompressorCore {
-	clusterCapacity: number;
+	/**
+	 * Returns a range of IDs created by this session in a format for sending to the server for finalizing.
+	 * The range will include all IDs generated via calls to `generateCompressedId` since the last time this method was called.
+	 * @returns the range of IDs, which may be empty. This range must be sent to the server for ordering before
+	 * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
+	 */
+	takeNextCreationRange(): IdCreationRange;
 
 	/**
 	 * Finalizes the supplied range of IDs (which may be from either a remote or local session).
@@ -25,14 +25,6 @@ export interface IIdCompressorCore {
 	 */
 	finalizeCreationRange(range: IdCreationRange): void;
 
-	/**
-	 * Returns a range of local IDs created by this session in a format for sending to the server for finalizing.
-	 * The range will include all local IDs generated via calls to `generateCompressedId` since the last time this method was called.
-	 * @returns the range of session-local IDs, which may be empty. This range must be sent to the server for ordering before
-	 * it is finalized. Ranges must be sent to the server in the order that they are taken via calls to this method.
-	 */
-	takeNextCreationRange(): IdCreationRange;
-
 	/**
 	 * Returns a persistable form of the current state of this `IdCompressor` which can be rehydrated via `IdCompressor.deserialize()`.
 	 * This includes finalized state as well as un-finalized state and is therefore suitable for use in offline scenarios.
@@ -58,38 +50,35 @@ export interface IIdCompressorCore {
  *
  * For each stable ID created, two numeric IDs are provided by the compressor:
  *
- * 1. A 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. Local IDs are session-unique and are thus only
- * publicly usable by the compressor that created the stable ID.
+ * 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 local ID is totally ordered (via consensus) with respect to other sessions' allocations.
+ * 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.
  *
- * A client may optionally supply an "override" for any generated ID, associating an arbitrary string with the local/final ID rather than
- * the UUID that would otherwise be created.
- *
  * The following invariants are upheld by IdCompressor:
  *
- * 1. Local IDs will always decompress to the same UUIDs (or override string) for the lifetime of the session.
+ * 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 (or override string).
+ * 2. Final IDs will always decompress to the same UUIDs.
  *
- * 3. After a server-processed range of local IDs (from any session) is received by a compressor, any of those local IDs may be
- * translated by the compressor into the corresponding final ID. For any given local ID, this translation will always yield the
+ * 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 (or override string) will always compress into the same session-space ID for the lifetime of the session.
+ * 4. A UUID will always compress into the same session-local ID for the lifetime of the session.
  *
- * Local IDs are sent across the wire in efficiently-represented ranges. These ranges are created by querying the compressor, and *must*
+ * 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 (the local and final) difficult. For example, if a cache is keyed off of a
- * local ID but is later queried using the final ID (which is semantically equal, as it decompresses to the same UUID/string) it will
+ * 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:
  *
@@ -102,7 +91,7 @@ export interface IIdCompressorCore {
  * 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 local ID in this space becomes finalized, and thereafter has a "more final form".
+ * 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".
@@ -117,11 +106,9 @@ export interface IIdCompressor {
 	/**
 	 * Generates a new compressed ID or returns an existing one.
 	 * This should ONLY be called to generate IDs for local operations.
-	 * @param override - Specifies a specific string to be associated with the returned compressed ID.
-	 * Performance note: assigning override strings incurs a performance overhead.
-	 * @returns an existing ID if one already exists for `override`, and a new local ID otherwise. The returned ID is in session space.
+	 * @returns A new local ID in session space.
 	 */
-	generateCompressedId(override?: string): SessionSpaceCompressedId;
+	generateCompressedId(): SessionSpaceCompressedId;
 	/**
 	 * Normalizes a session space ID into op space.
 	 * @param id - the local ID to normalize.
@@ -143,37 +130,23 @@ export interface IIdCompressor {
 	): SessionSpaceCompressedId;
 
 	/**
-	 * Normalizes a final ID into session space.
-	 * @param id - the final ID to normalize.
-	 * @returns the session-space ID corresponding to `id`.
-	 */
-	normalizeToSessionSpace(id: FinalCompressedId): SessionSpaceCompressedId;
-
-	/**
-	 * Decompresses a previously compressed ID into a UUID or override string.
-	 * @param id - the compressed ID to be decompressed.
-	 * @returns the UUID or override string associated with the compressed ID. Fails if the ID was not generated by this compressor.
-	 */
-	decompress(id: SessionSpaceCompressedId | FinalCompressedId): StableId | string;
-
-	/**
-	 * Attempts to decompress a previously compressed ID into a UUID or override string.
+	 * Decompresses a previously compressed ID into a UUID.
 	 * @param id - the compressed ID to be decompressed.
-	 * @returns the UUID or override string associated with the compressed ID, or undefined if the ID was not generated by this compressor.
+	 * @returns the UUID associated with the compressed ID. Fails if the ID was not generated by this compressor.
 	 */
-	tryDecompress(id: SessionSpaceCompressedId | FinalCompressedId): StableId | string | undefined;
+	decompress(id: SessionSpaceCompressedId): StableId;
 
 	/**
-	 * Recompresses a decompressed ID, which could be a UUID or an override string.
-	 * @param uncompressed - the UUID or override string to recompress.
+	 * 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.
 	 */
-	recompress(uncompressed: string): SessionSpaceCompressedId;
+	recompress(uncompressed: StableId): SessionSpaceCompressedId;
 
 	/**
-	 * Attempts to recompresses a decompressed ID, which could be a UUID or an override string.
-	 * @param uncompressed - the UUID or override string to recompress,
+	 * 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.
 	 */
-	tryRecompress(uncompressed: string): SessionSpaceCompressedId | undefined;
+	tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
 }

package/src/id-compressor/identifiers.ts

@@ -3,79 +3,31 @@
  * Licensed under the MIT License.
  */
 
-/**
- * An identifier (UUID) that has been shortened by a distributed compression algorithm.
- * @alpha
- */
-export type CompressedId = FinalCompressedId | LocalCompressedId;
-
-/**
- * A brand for identity types that are unique within a particular session (SharedTree instance).
- */
-export interface SessionUnique {
-	readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
-}
-
 /**
  * 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
- * compressor that produced them.
- * @alpha
+ * 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.
  */
-export type SessionSpaceCompressedId = CompressedId & SessionUnique;
-
-/**
- * A compressed ID that has been normalized into "op space" (see `IdCompressor` for more).
- * Serialized/persisted structures (e.g. ops) should use op-space IDs as a performance optimization, as they require no 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.
- */
-export type OpSpaceCompressedId = CompressedId & {
-	readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+export type SessionSpaceCompressedId = number & {
+	readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
 };
 
 /**
- * A compressed ID that is local to a document. Stable across all revisions of a document starting from the one in which it was created.
- * It should not be persisted outside of the history as it can only be decompressed in the context of the originating document.
- * If external persistence is needed (e.g. by a client), a StableId should be used instead.
- * @alpha
+ * 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.
  */
-export type FinalCompressedId = number & {
-	readonly FinalCompressedId: "5d83d1e2-98b7-4e4e-a889-54c855cfa73d";
-
-	// Same brand as OpNormalizedCompressedId, as final IDs are always finally normalized
+export type OpSpaceCompressedId = number & {
 	readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
 };
 
 /**
- * A compressed ID that is local to a session (can only be decompressed when paired with a SessionId).
- * It should not be persisted outside of the history as it can only be decompressed in the context of the originating session.
- * If external persistence is needed (e.g. by a client), a StableId should be used instead.
- * @alpha
- */
-export type LocalCompressedId = number & {
-	readonly LocalCompressedId: "6fccb42f-e2a4-4243-bd29-f13d12b9c6d1";
-} & SessionUnique; // Same brand as CompressedId, as local IDs are always locally normalized
-
-export interface NodeIdBrand {
-	readonly NodeId: "e53e7d6b-c8b9-431a-8805-4843fc639342";
-}
-
-/**
- * Type-safe identifiers for specific use cases.
- */
-
-/**
+ * A version 4, variant 1 uuid (https://datatracker.ietf.org/doc/html/rfc4122).
  * 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.
- * @public
- */
-export type UuidString = string & { readonly UuidString: "9d40d0ae-90d9-44b1-9482-9f55d59d5465" };
-
-/**
- * A version 4, variant 2 uuid (https://datatracker.ietf.org/doc/html/rfc4122).
  */
-export type StableId = UuidString & { readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a" };
+export type StableId = string & { readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a" };
 
 /**
  * A StableId which is suitable for use as a session identifier

package/src/id-compressor/index.ts

@@ -5,30 +5,13 @@
 
 export {
 	IdCreationRange,
-	SerializedCluster,
-	SerializedClusterOverrides,
 	SerializedIdCompressor,
 	SerializedIdCompressorWithNoSession,
 	SerializedIdCompressorWithOngoingSession,
-	SerializedLocalOverrides,
-	SerializedLocalState,
-	SerializedSessionData,
-	SerializedSessionIdNormalizer,
-	UnackedLocalId,
-	VersionedSerializedIdCompressor,
 	IdCreationRangeWithStashedState,
+	initialClusterCapacity,
 } from "./persisted-types";
 
 export { IIdCompressorCore, IIdCompressor } from "./idCompressor";
 
-export {
-	SessionSpaceCompressedId,
-	OpSpaceCompressedId,
-	SessionId,
-	FinalCompressedId,
-	StableId,
-	UuidString,
-	CompressedId,
-	SessionUnique,
-	LocalCompressedId,
-} from "./identifiers";
+export { SessionSpaceCompressedId, OpSpaceCompressedId, SessionId, StableId } from "./identifiers";

package/src/id-compressor/persisted-types/0.0.1.ts

@@ -3,188 +3,47 @@
  * Licensed under the MIT License.
  */
 
-import type {
-	FinalCompressedId,
-	LocalCompressedId,
-	OpSpaceCompressedId,
-	SessionId,
-} from "../identifiers";
-
-/**
- * A serialized ID allocation session for an `IdCompressor`.
- */
-export type SerializedSessionData = readonly [
-	/**
-	 * The ID of the session.
-	 */
-	sessionId: SessionId,
-];
-
-export type SerializedClusterOverrides = readonly [
-	/** The overridden final ID, represented as an index into the cluster's ID range */
-	overriddenFinalIndex: number, // A cluster with base UUID '...beef' and an `overriddenFinalIndex` of 3 would correspond to '...bef2'
-	/** The override string */
-	override: string,
-	/** The first ID that was finalized and associated with this override, set only if different than the `overriddenFinalIndex` */
-	overriddenId?: FinalCompressedId,
-][];
-
-/**
- * A serialized final ID cluster.
- */
-export type SerializedCluster = readonly [
-	/**
-	 * Index into the serialized sessions array. Can be converted into a baseUuid via its order in `clusters`.
-	 * If negative, then this cluster was created by the local session.
-	 */
-	sessionIndex: number,
-
-	/**
-	 * The capacity of the cluster.
-	 */
-	capacity: number,
-
-	/**
-	 * The number of IDs in the cluster. Omitted if count === capacity.
-	 * --OR--
-	 * The overrides in this cluster. Omitted if no overrides exist in the cluster.
-	 */
-	countOrOverrides?: number | SerializedClusterOverrides,
-
-	/**
-	 * Overrides in this cluster. Omitted if no overrides exist in the cluster.
-	 */
-	overrides?: SerializedClusterOverrides,
-];
-
-export type SerializedLocalOverrides = readonly (readonly [LocalCompressedId, string])[];
-
-export interface SerializedLocalState {
-	/**
-	 * The total number of local IDs created by this session
-	 */
-	readonly localIdCount: number;
-	/**
-	 * Overrides generated by this session. Omitted if no local overrides exist in the session.
-	 */
-	readonly overrides?: SerializedLocalOverrides;
-
-	/**
-	 * The most recent local ID in a range returned by `takeNextCreationRange`.
-	 */
-	readonly lastTakenLocalId: LocalCompressedId | undefined;
-
-	/**
-	 * Serialized table for normalizing IDs made by the local session.
-	 */
-	readonly sessionNormalizer: SerializedSessionIdNormalizer;
-}
-
-/**
- * Serialized table for normalizing IDs made by the local session.
- */
-export interface SerializedSessionIdNormalizer {
-	readonly nextLocalId: LocalCompressedId;
-	readonly localRanges: readonly (readonly [
-		firstLocal: LocalCompressedId,
-		lastLocal: LocalCompressedId,
-		finalRanges?: readonly (readonly [
-			alignedLocal: LocalCompressedId,
-			firstFinal: FinalCompressedId,
-			lastFinal: FinalCompressedId,
-		])[],
-	])[];
-}
-
-/**
- * The minimal required contents of a serialized IdCompressor.
- */
-export interface VersionedSerializedIdCompressor {
-	readonly _versionedSerializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5";
-	readonly version: string;
-}
+import type { SessionId } from "../identifiers";
 
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
  */
-export interface SerializedIdCompressor extends VersionedSerializedIdCompressor {
-	/** The cluster capacity of this compressor */
-	readonly clusterCapacity: number;
-	/** All sessions except the local session. */
-	readonly sessions: readonly SerializedSessionData[];
-	/** All clusters in the compressor in the order they were created. */
-	readonly clusters: readonly SerializedCluster[];
-}
+export type SerializedIdCompressor = string & {
+	readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5";
+};
 
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
  */
-export interface SerializedIdCompressorWithNoSession extends SerializedIdCompressor {
+export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {
 	readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb";
-}
+};
 
 /**
  * The serialized contents of an IdCompressor, suitable for persistence in a summary.
  */
-export interface SerializedIdCompressorWithOngoingSession extends SerializedIdCompressor {
+export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {
 	readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb";
-	/** The session ID of the local session, by index into `sessions`. */
-	readonly localSessionIndex: number;
-	/** This is only present if the local session made any IDs. */
-	readonly localState?: SerializedLocalState;
-}
+};
 
 /**
  * Data describing a range of session-local IDs (from a remote or local session).
  *
- * A range is composed of local IDs that were generated. Some of these may have overrides.
- *
- * @example
- * Suppose an IdCompressor generated a sequence of local IDs as follows:
- * ```
- * compressor.generateLocalId()
- * compressor.generateLocalId('0093cf29-9454-4034-8940-33b1077b41c3')
- * compressor.generateLocalId()
- * compressor.generateLocalId('0ed545f8-e97e-4dc1-acf9-c4a783258bdf')
- * compressor.generateLocalId()
- * compressor.generateLocalId()
- * compressor.takeNextCreationRange()
- * ```
- * This would result in the following range:
- * ```
- * {
- *     first: localId1,
- *     last: localId6,
- *     overrides: [[localId2, '0093cf29-9454-4034-8940-33b1077b41c3'], [localId4, '0ed545f8-e97e-4dc1-acf9-c4a783258bdf']]
- * }
- * ```
+ * A range is composed of local IDs that were generated.
  */
 export interface IdCreationRange {
 	readonly sessionId: SessionId;
-	readonly ids?: IdCreationRange.Ids;
+	readonly ids?: {
+		readonly firstGenCount: number;
+		readonly count: number;
+	};
 }
 
-export type UnackedLocalId = LocalCompressedId & OpSpaceCompressedId;
-
-// eslint-disable-next-line @typescript-eslint/no-namespace
-export namespace IdCreationRange {
-	export type Ids =
-		| {
-				readonly first: UnackedLocalId;
-				readonly last: UnackedLocalId;
-		  }
-		| ({
-				readonly first?: UnackedLocalId;
-				readonly last?: UnackedLocalId;
-		  } & HasOverrides);
-
-	export interface HasOverrides {
-		readonly overrides: Overrides;
-	}
-
-	export type Override = readonly [id: UnackedLocalId, override: string];
-	export type Overrides = readonly [Override, ...Override[]];
-}
+/**
+ * Roughly equates to a minimum of 1M sessions before we start allocating 64 bit IDs.
+ * This value must *NOT* change without careful consideration to compatibility.
+ */
+export const initialClusterCapacity = 512;
 
 export type IdCreationRangeWithStashedState = IdCreationRange & {
 	stashedState: SerializedIdCompressorWithOngoingSession;

package/src/id-compressor/persisted-types/index.ts

@@ -5,16 +5,9 @@
 
 export {
 	IdCreationRange,
-	SerializedCluster,
-	SerializedClusterOverrides,
 	SerializedIdCompressor,
 	SerializedIdCompressorWithNoSession,
 	SerializedIdCompressorWithOngoingSession,
-	SerializedLocalOverrides,
-	SerializedLocalState,
-	SerializedSessionData,
-	SerializedSessionIdNormalizer,
-	UnackedLocalId,
-	VersionedSerializedIdCompressor,
 	IdCreationRangeWithStashedState,
+	initialClusterCapacity,
 } from "./0.0.1";

package/src/index.ts

@@ -74,20 +74,8 @@ export {
 	SessionSpaceCompressedId,
 	OpSpaceCompressedId,
 	SessionId,
-	FinalCompressedId,
 	StableId,
-	UuidString,
-	CompressedId,
-	SessionUnique,
-	LocalCompressedId,
 	IdCreationRange,
-	VersionedSerializedIdCompressor,
-	SerializedCluster,
-	SerializedSessionData,
-	SerializedLocalState,
-	SerializedClusterOverrides,
-	SerializedLocalOverrides,
-	SerializedSessionIdNormalizer,
-	UnackedLocalId,
 	IdCreationRangeWithStashedState,
+	initialClusterCapacity,
 } from "./id-compressor";