@fluidframework/id-compressor 2.0.0-dev-rc.1.0.0.224419

package/.eslintrc.js

@@ -0,0 +1,27 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	extends: [require.resolve("@fluidframework/eslint-config-fluid/minimal"), "prettier"],
+	parserOptions: {
+		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
+	},
+	rules: {
+		"@typescript-eslint/strict-boolean-expressions": "off",
+
+		// This library is used in the browser, so we don't want dependencies on most node libraries.
+		"import/no-nodejs-modules": ["error", { allow: ["events"] }],
+	},
+	overrides: [
+		{
+			// Rules only for test files
+			files: ["*.spec.ts", "src/test/**"],
+			rules: {
+				// Test files are run in node only so additional node libraries can be used.
+				"import/no-nodejs-modules": ["error", { allow: ["assert", "crypto", "events"] }],
+			},
+		},
+	],
+};

package/.mocharc.js

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+"use strict";
+
+const getFluidTestMochaConfig = require("@fluidframework/mocha-test-setup/mocharc-common");
+
+const packageDir = __dirname;
+const config = getFluidTestMochaConfig(packageDir);
+module.exports = config;

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @fluidframework/id-compressor
+
+## 2.0.0-internal.8.0.0
+
+Dependency updates only.
+
+## 2.0.0-internal.7.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @fluidframework/id-compressor
+
+A library which generates small number representations of arbitrary non-colliding Version 4 UUIDs ("stable IDs") across multiple sessions in a network. This scheme enables a distributed application to utilize the global uniqueness guarantees of UUIDs while maintaining the performance advantages of small integers.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_INSTALLATION_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Installation
+
+To get started, install the package by running the following command:
+
+```bash
+npm i @fluidframework/id-compressor
+```
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+<!-- AUTO-GENERATED-CONTENT:START (README_DEPENDENCY_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Using Fluid Framework libraries
+
+When taking a dependency on a Fluid Framework library, we recommend using a `^` (caret) version range, such as `^1.3.4`.
+While Fluid Framework libraries may use different ranges with interdependencies between other Fluid Framework libraries,
+library consumers should always prefer `^`.
+
+Note that when depending on a library version of the form `2.0.0-internal.x.y.z`, called the Fluid internal version scheme,
+you must use a `>= <` dependency range (such as `>=2.0.0-internal.x.y.z <2.0.0-internal.w.0.0` where `w` is `x+1`).
+Standard `^` and `~` ranges will not work as expected.
+See the [@fluid-tools/version-tools](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/version-tools/README.md)
+package for more information including tools to convert between version schemes.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+## Overview
+
+The distributed ID allocation scheme allows clients to use, store, and reference small numbers that map to UUIDs rather than the UUIDs themselves. The primary benefits are improved memory efficiency and reduced storage size, as well as improved runtime performance when used as keys in collections.
+
+The scheme requires a total order for ID allocation, so the allocator is designed to work within a service that provides centralized total order broadcast.
+
+### Sessions
+
+A session can be thought of as a unique identifier for a single allocator. Even if an allocator is taken offline, serialized to disk, and rehydrated back, it's considered the same session if it has the same session ID.
+
+### Document
+
+The set of IDs generated by all Sessions contributing to the same distributed collection (e.g. an individual collaborative document). Uniqueness of allocated IDs is limited to the document context (unless in their UUID form), and thus IDs in their compressed form are not portable between documents.
+
+### Generation API
+
+New IDs are generated via a synchronous API on the allocator. The API returns a small number representation of the UUID with the following guarantees:
+
+-   The ID can be synchronously converted into a full UUID at any time. This is required if global uniqueness (across documents) is needed.
+-   Prior to the service being notified of the ID's creation, it is unique within the scope of the session (i.e. the new ID will not collide with other IDs from the same allocator, but it can collide with IDs from a different allocator in the same network).
+-   After the service has been notified of the ID's creation and has determined a total ordering between all clients creating IDs, the ID will have a "final" form that is a small number representation that is unique across the [document](#document).
+
+### ID Spaces
+
+The allocation scheme separates the small-number IDs into two "spaces":
+
+1. Session space: IDs are unique within the session scope, but are not guaranteed to be [document](#document) unique without the accompanying context of their session ID.
+2. Op space: IDs are in their most final form, as unique as possible within the entire system. IDs that have been ordered by the central service ("finalized") are represented in their final form, while any other IDs that have not yet been finalized are left in their "session space" form.
+
+Each of these spaces is represented by a discrete type. This allows for the direct encoding of an ID's uniqueness guarantees without contextual ambiguity. An ID can be "normalized" from one space to the other with a sychronous call.
+
+### Usage Guidelines
+
+When delivering Allocated IDs to application authors for use in place of V4 UUIDs, follow these guidelines:
+
+-   Expose only session space IDs to application authors. This means that application developers don't need to manage multiple ID spaces or worry about converting IDs between session space and op space. This simplifies the data management process and reduces the chances of errors or inconsistencies.
+
+    -   **Note:** Session space IDs are only unique within the originating session (for most applications this will mean within each individual client's app instance, as it is rare to hold handles to more than one allocator). This constrains usage to scopes where IDs are unique; for instance, application developers should never persist these IDs and should instead be directed to convert them to stable IDs first.
+
+-   Use op space IDs for serialized forms, such as sending information over the wire or storing it in a file. Op space IDs are always generated in their _final_ form when possible, which imparts a performance benefit by reducing normalization work when a client receives a network operation or rehydrates an allocator.
+-   When serializing op space IDs, annotate the entire context (e.g., file or network operation) with the session ID. This is necessary because not all IDs in op space are in their final form. Any non-finalized IDs will still be in their session space form, unique only within that specific session. Annotating the entire context with the session ID ensures that recipients of the serialized data can correctly interpret and process the non-finalized IDs.
+
+### Efficiency Properties
+
+#### UUID Generation
+
+The allocator generates UUIDs in non-random ways to reduce entropy, optimizing storage of data. A session begins with a random UUID, and subsequent IDs are allocated sequentially. UUIDs generated with this strategy are less likely to collide than fully random UUIDs, and this fact can be leveraged to compact the on-disk and in-memory representations of the allocator.
+
+UUID generation is O(1).
+
+#### Decompression/recompression
+
+Converting an allocated ID into its UUID form (decompression) and the reverse (recompression) are both O(log<sub>n</sub>) in the number of IDs created by the originating session.
+
+#### Clustering
+
+The sequential allocation approach allows the system to implement a clustering scheme.
+
+As allocators across the network create IDs, they reserve blocks of positive ID space (clusters) for that allocator. The positive integer space is sharded across different clients, and session space IDs are mapped into these clusters.
+
+Clusters are efficient to store, requiring only two integers: the base positive integer in the cluster and the count of reserved IDs in that cluster.
+
+#### Normalization
+
+Normalization is O(log<sub>n</sub>) in the number of IDs created by the originating session, as it requires a simple binary search on the clusters owned by that session.
+
+<!-- AUTO-GENERATED-CONTENT:START (README_CONTRIBUTION_GUIDELINES_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Contribution Guidelines
+
+There are many ways to [contribute](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md) to Fluid.
+
+-   Participate in Q&A in our [GitHub Discussions](https://github.com/microsoft/FluidFramework/discussions).
+-   [Submit bugs](https://github.com/microsoft/FluidFramework/issues) and help us verify fixes as they are checked in.
+-   Review the [source code changes](https://github.com/microsoft/FluidFramework/pulls).
+-   [Contribute bug fixes](https://github.com/microsoft/FluidFramework/blob/main/CONTRIBUTING.md).
+
+Detailed instructions for working in the repo can be found in the [Wiki](https://github.com/microsoft/FluidFramework/wiki).
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+Use of these trademarks or logos must follow Microsoft’s [Trademark & Brand Guidelines](https://www.microsoft.com/trademarks).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+<!-- AUTO-GENERATED-CONTENT:START (README_HELP_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Help
+
+Not finding what you're looking for in this README? Check out our [GitHub
+Wiki](https://github.com/microsoft/FluidFramework/wiki) or [fluidframework.com](https://fluidframework.com/docs/).
+
+Still not finding what you're looking for? Please [file an
+issue](https://github.com/microsoft/FluidFramework/wiki/Submitting-Bugs-and-Feature-Requests).
+
+Thank you!
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->
+
+<!-- AUTO-GENERATED-CONTENT:START (README_TRADEMARK_SECTION:includeHeading=TRUE) -->
+
+<!-- prettier-ignore-start -->
+<!-- NOTE: This section is automatically generated using @fluid-tools/markdown-magic. Do not update these generated contents directly. -->
+
+## Trademark
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services.
+
+Use of these trademarks or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+
+<!-- prettier-ignore-end -->
+
+<!-- AUTO-GENERATED-CONTENT:END -->

package/api-extractor-lint.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+}

package/api-extractor.json

@@ -0,0 +1,4 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.json"
+}

package/api-report/id-compressor.api.md

@@ -0,0 +1,139 @@
+## API Report File for "@fluidframework/id-compressor"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+
+// @internal
+export function assertIsStableId(stableId: string): StableId;
+
+// @alpha
+export function createIdCompressor(logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
+
+// @alpha
+export function createIdCompressor(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
+
+// @alpha
+export function createSessionId(): SessionId;
+
+// @alpha
+export function deserializeIdCompressor(serialized: SerializedIdCompressorWithOngoingSession): IIdCompressor & IIdCompressorCore;
+
+// @alpha
+export function deserializeIdCompressor(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IIdCompressor & IIdCompressorCore;
+
+// @internal
+export function generateStableId(): StableId;
+
+// @alpha @deprecated
+export class IdCompressor implements IIdCompressor, IIdCompressorCore {
+    // @deprecated (undocumented)
+    static create(logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
+    // @deprecated (undocumented)
+    static create(sessionId: SessionId, logger?: ITelemetryBaseLogger): IIdCompressor & IIdCompressorCore;
+    // (undocumented)
+    decompress(id: SessionSpaceCompressedId): StableId;
+    // (undocumented)
+    static deserialize(serialized: SerializedIdCompressorWithOngoingSession): IdCompressor;
+    // (undocumented)
+    static deserialize(serialized: SerializedIdCompressorWithNoSession, newSessionId: SessionId): IdCompressor;
+    // (undocumented)
+    equals(other: IdCompressor, includeLocalState: boolean): boolean;
+    // (undocumented)
+    finalizeCreationRange(range: IdCreationRange): void;
+    // (undocumented)
+    generateCompressedId(): SessionSpaceCompressedId;
+    // (undocumented)
+    readonly localSessionId: SessionId;
+    static readonly maxClusterSize: number;
+    // (undocumented)
+    normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
+    // (undocumented)
+    normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
+    // (undocumented)
+    recompress(uncompressed: StableId): SessionSpaceCompressedId;
+    // (undocumented)
+    serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
+    // (undocumented)
+    serialize(withSession: false): SerializedIdCompressorWithNoSession;
+    // (undocumented)
+    takeNextCreationRange(): IdCreationRange;
+    // (undocumented)
+    tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
+}
+
+// @alpha
+export interface IdCreationRange {
+    // (undocumented)
+    readonly ids?: {
+        readonly firstGenCount: number;
+        readonly count: number;
+        readonly requestedClusterSize: number;
+    };
+    // (undocumented)
+    readonly sessionId: SessionId;
+}
+
+// @public
+export interface IIdCompressor {
+    decompress(id: SessionSpaceCompressedId): StableId;
+    generateCompressedId(): SessionSpaceCompressedId;
+    // (undocumented)
+    localSessionId: SessionId;
+    normalizeToOpSpace(id: SessionSpaceCompressedId): OpSpaceCompressedId;
+    normalizeToSessionSpace(id: OpSpaceCompressedId, originSessionId: SessionId): SessionSpaceCompressedId;
+    recompress(uncompressed: StableId): SessionSpaceCompressedId;
+    tryRecompress(uncompressed: StableId): SessionSpaceCompressedId | undefined;
+}
+
+// @alpha (undocumented)
+export interface IIdCompressorCore {
+    finalizeCreationRange(range: IdCreationRange): void;
+    serialize(withSession: true): SerializedIdCompressorWithOngoingSession;
+    serialize(withSession: false): SerializedIdCompressorWithNoSession;
+    takeNextCreationRange(): IdCreationRange;
+}
+
+// @internal
+export function isStableId(str: string): str is StableId;
+
+// @public
+export type OpSpaceCompressedId = number & {
+    readonly OpNormalized: "9209432d-a959-4df7-b2ad-767ead4dbcae";
+};
+
+// @alpha
+export type SerializedIdCompressor = string & {
+    readonly _serializedIdCompressor: "8c73c57c-1cf4-4278-8915-6444cb4f6af5";
+};
+
+// @alpha
+export type SerializedIdCompressorWithNoSession = SerializedIdCompressor & {
+    readonly _noLocalState: "3aa2e1e8-cc28-4ea7-bc1a-a11dc3f26dfb";
+};
+
+// @alpha
+export type SerializedIdCompressorWithOngoingSession = SerializedIdCompressor & {
+    readonly _hasLocalState: "1281acae-6d14-47e7-bc92-71c8ee0819cb";
+};
+
+// @public
+export type SessionId = StableId & {
+    readonly SessionId: "4498f850-e14e-4be9-8db0-89ec00997e58";
+};
+
+// @public
+export type SessionSpaceCompressedId = number & {
+    readonly SessionUnique: "cea55054-6b82-4cbf-ad19-1fa645ea3b3e";
+};
+
+// @public
+export type StableId = string & {
+    readonly StableId: "53172b0d-a3d5-41ea-bd75-b43839c97f5a";
+};
+
+// (No @packageDocumentation comment for this package)
+
+```