@fluidframework/tree 2.23.0 → 2.30.0

package/lib/feature-libraries/node-key/nodeKeyManager.d.ts

@@ -1,37 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import type { LocalNodeKey, StableNodeKey } from "./nodeKey.js";
-/**
- * An object which handles the generation of node keys as well as conversion between their two types ({@link StableNodeKey} and {@link LocalNodeKey}).
- */
-export interface NodeKeyManager {
-    /**
-     * Generate a {@link StableNodeKey}.
-     */
-    generateLocalNodeKey(): LocalNodeKey;
-    /**
-     * Convert the given {@link StableNodeKey} into its {@link LocalNodeKey} form.
-     */
-    localizeNodeKey(key: StableNodeKey): LocalNodeKey;
-    /**
-     * Convert the given {@link LocalNodeKey} into its {@link StableNodeKey} form.
-     */
-    stabilizeNodeKey(key: LocalNodeKey): StableNodeKey;
-    /**
-     * Attempts to recompress a StableNodeKey.
-     * @param key - The key that is attempted to recompress.
-     * @returns The `LocalNodeKey` associated with `key` or undefined if the key was not generated by any session known to this compressor.
-     */
-    tryLocalizeNodeKey(key: string): LocalNodeKey | undefined;
-}
-/**
- * Creates a {@link NodeKeyManager} from the given {@link IIdCompressor}.
- * @param idCompressor - the compressor to use for key generation, compression, and decompression.
- * If undefined, then attempts to generate or convert keys will throw an error.
- */
-export declare function createNodeKeyManager(idCompressor?: IIdCompressor | undefined): NodeKeyManager;
-export declare function isStableNodeKey(key: string): key is StableNodeKey;
-//# sourceMappingURL=nodeKeyManager.d.ts.map

package/lib/feature-libraries/node-key/nodeKeyManager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nodeKeyManager.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/node-key/nodeKeyManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKnE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B;;OAEG;IACH,oBAAoB,IAAI,YAAY,CAAC;IAErC;;OAEG;IACH,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAAC;IAElD;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa,CAAC;IAEnD;;;;OAIG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CACnC,YAAY,CAAC,EAAE,aAAa,GAAG,SAAS,GACtC,cAAc,CAyChB;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,aAAa,CAEjE"}

package/lib/feature-libraries/node-key/nodeKeyManager.js

@@ -1,43 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import { assert } from "@fluidframework/core-utils/internal";
-import { assertIsStableId, isStableId } from "@fluidframework/id-compressor/internal";
-import { brand, extractFromOpaque } from "../../util/index.js";
-/**
- * Creates a {@link NodeKeyManager} from the given {@link IIdCompressor}.
- * @param idCompressor - the compressor to use for key generation, compression, and decompression.
- * If undefined, then attempts to generate or convert keys will throw an error.
- */
-export function createNodeKeyManager(idCompressor) {
-    return {
-        generateLocalNodeKey: () => {
-            assert(idCompressor !== undefined, 0x6e4 /* Runtime IdCompressor must be available to generate local node keys */);
-            return brand(idCompressor.generateCompressedId());
-        },
-        localizeNodeKey: (key) => {
-            assert(idCompressor !== undefined, 0x6e5 /* Runtime IdCompressor must be available to convert node keys */);
-            return brand(idCompressor.recompress(key));
-        },
-        stabilizeNodeKey: (key) => {
-            assert(idCompressor !== undefined, 0x6e6 /* Runtime IdCompressor must be available to convert node keys */);
-            return brand(
-            // TODO: The assert below is required for type safety but is maybe slow
-            assertIsStableId(idCompressor.decompress(extractFromOpaque(key))));
-        },
-        tryLocalizeNodeKey: (key) => {
-            assert(idCompressor !== undefined, 0x6e9 /* Runtime IdCompressor must be available to convert node keys */);
-            if (isStableNodeKey(key)) {
-                const compressedKey = idCompressor.tryRecompress(key);
-                if (compressedKey !== undefined) {
-                    return brand(compressedKey);
-                }
-            }
-        },
-    };
-}
-export function isStableNodeKey(key) {
-    return isStableId(key);
-}
-//# sourceMappingURL=nodeKeyManager.js.map

package/lib/feature-libraries/node-key/nodeKeyManager.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"nodeKeyManager.js","sourceRoot":"","sources":["../../../src/feature-libraries/node-key/nodeKeyManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAEtF,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA+B/D;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CACnC,YAAwC;IAExC,OAAO;QACN,oBAAoB,EAAE,GAAG,EAAE;YAC1B,MAAM,CACL,YAAY,KAAK,SAAS,EAC1B,KAAK,CAAC,wEAAwE,CAC9E,CAAC;YACF,OAAO,KAAK,CAAC,YAAY,CAAC,oBAAoB,EAAE,CAAC,CAAC;QACnD,CAAC;QAED,eAAe,EAAE,CAAC,GAAkB,EAAE,EAAE;YACvC,MAAM,CACL,YAAY,KAAK,SAAS,EAC1B,KAAK,CAAC,iEAAiE,CACvE,CAAC;YACF,OAAO,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5C,CAAC;QAED,gBAAgB,EAAE,CAAC,GAAiB,EAAE,EAAE;YACvC,MAAM,CACL,YAAY,KAAK,SAAS,EAC1B,KAAK,CAAC,iEAAiE,CACvE,CAAC;YACF,OAAO,KAAK;YACX,uEAAuE;YACvE,gBAAgB,CAAC,YAAY,CAAC,UAAU,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,CACjE,CAAC;QACH,CAAC;QACD,kBAAkB,EAAE,CAAC,GAAW,EAAE,EAAE;YACnC,MAAM,CACL,YAAY,KAAK,SAAS,EAC1B,KAAK,CAAC,iEAAiE,CACvE,CAAC;YACF,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;gBACtD,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;oBACjC,OAAO,KAAK,CAAC,aAAa,CAAC,CAAC;gBAC7B,CAAC;YACF,CAAC;QACF,CAAC;KACD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IAC1C,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\nimport { assertIsStableId, isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport { brand, extractFromOpaque } from \"../../util/index.js\";\n\nimport type { LocalNodeKey, StableNodeKey } from \"./nodeKey.js\";\n\n/**\n * An object which handles the generation of node keys as well as conversion between their two types ({@link StableNodeKey} and {@link LocalNodeKey}).\n */\nexport interface NodeKeyManager {\n\t/**\n\t * Generate a {@link StableNodeKey}.\n\t */\n\tgenerateLocalNodeKey(): LocalNodeKey;\n\n\t/**\n\t * Convert the given {@link StableNodeKey} into its {@link LocalNodeKey} form.\n\t */\n\tlocalizeNodeKey(key: StableNodeKey): LocalNodeKey;\n\n\t/**\n\t * Convert the given {@link LocalNodeKey} into its {@link StableNodeKey} form.\n\t */\n\tstabilizeNodeKey(key: LocalNodeKey): StableNodeKey;\n\n\t/**\n\t * Attempts to recompress a StableNodeKey.\n\t * @param key - The key that is attempted to recompress.\n\t * @returns The `LocalNodeKey` associated with `key` or undefined if the key was not generated by any session known to this compressor.\n\t */\n\ttryLocalizeNodeKey(key: string): LocalNodeKey | undefined;\n}\n\n/**\n * Creates a {@link NodeKeyManager} from the given {@link IIdCompressor}.\n * @param idCompressor - the compressor to use for key generation, compression, and decompression.\n * If undefined, then attempts to generate or convert keys will throw an error.\n */\nexport function createNodeKeyManager(\n\tidCompressor?: IIdCompressor | undefined,\n): NodeKeyManager {\n\treturn {\n\t\tgenerateLocalNodeKey: () => {\n\t\t\tassert(\n\t\t\t\tidCompressor !== undefined,\n\t\t\t\t0x6e4 /* Runtime IdCompressor must be available to generate local node keys */,\n\t\t\t);\n\t\t\treturn brand(idCompressor.generateCompressedId());\n\t\t},\n\n\t\tlocalizeNodeKey: (key: StableNodeKey) => {\n\t\t\tassert(\n\t\t\t\tidCompressor !== undefined,\n\t\t\t\t0x6e5 /* Runtime IdCompressor must be available to convert node keys */,\n\t\t\t);\n\t\t\treturn brand(idCompressor.recompress(key));\n\t\t},\n\n\t\tstabilizeNodeKey: (key: LocalNodeKey) => {\n\t\t\tassert(\n\t\t\t\tidCompressor !== undefined,\n\t\t\t\t0x6e6 /* Runtime IdCompressor must be available to convert node keys */,\n\t\t\t);\n\t\t\treturn brand(\n\t\t\t\t// TODO: The assert below is required for type safety but is maybe slow\n\t\t\t\tassertIsStableId(idCompressor.decompress(extractFromOpaque(key))),\n\t\t\t);\n\t\t},\n\t\ttryLocalizeNodeKey: (key: string) => {\n\t\t\tassert(\n\t\t\t\tidCompressor !== undefined,\n\t\t\t\t0x6e9 /* Runtime IdCompressor must be available to convert node keys */,\n\t\t\t);\n\t\t\tif (isStableNodeKey(key)) {\n\t\t\t\tconst compressedKey = idCompressor.tryRecompress(key);\n\t\t\t\tif (compressedKey !== undefined) {\n\t\t\t\t\treturn brand(compressedKey);\n\t\t\t\t}\n\t\t\t}\n\t\t},\n\t};\n}\n\nexport function isStableNodeKey(key: string): key is StableNodeKey {\n\treturn isStableId(key);\n}\n"]}

package/src/feature-libraries/node-key/README.md

@@ -1,11 +0,0 @@
-# Node Key
-
-Nodes keys provide references to nodes in a shared tree.
-
-## Local Node Keys
-
-Local node keys are an efficient representation of a node key and are unique within the local session (machine memory).
-
-## Stable Node Keys
-
-Stable node keys are UUIDs that are globally unique and can be persisted outside of the document.

package/src/feature-libraries/node-key/index.ts

@@ -1,17 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-export { MockNodeKeyManager } from "./mockNodeKeyManager.js";
-export {
-	compareLocalNodeKeys,
-	type LocalNodeKey,
-	type StableNodeKey,
-	nodeKeyTreeIdentifier,
-} from "./nodeKey.js";
-export {
-	createNodeKeyManager,
-	isStableNodeKey,
-	type NodeKeyManager,
-} from "./nodeKeyManager.js";

package/src/feature-libraries/node-key/mockNodeKeyManager.ts

@@ -1,54 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { assert } from "@fluidframework/core-utils/internal";
-import type { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
-import { assertIsStableId } from "@fluidframework/id-compressor/internal";
-import type { LocalNodeKey, StableNodeKey } from "./nodeKey.js";
-import { isStableNodeKey, type NodeKeyManager } from "./nodeKeyManager.js";
-import { brand, extractFromOpaque, fail } from "../../util/index.js";
-
-/**
- * Mock {@link NodeKeyManager} that generates deterministic {@link StableNodeKey}s and {@link LocalNodeKey}s.
- * @remarks This is useful for test environments because it will always yield the same keys in the same order.
- * It should not be used for production environments for the same reason; the {@link StableNodeKey}s are not universally unique.
- */
-export class MockNodeKeyManager implements NodeKeyManager {
-	private count = 0;
-
-	public generateStableNodeKey(): StableNodeKey {
-		return brand(this.getId(this.count++));
-	}
-
-	public generateLocalNodeKey(): LocalNodeKey {
-		return this.localizeNodeKey(this.generateStableNodeKey());
-	}
-
-	public localizeNodeKey(key: StableNodeKey): LocalNodeKey {
-		return this.tryLocalizeNodeKey(key) ?? fail(0xb26 /* Key is not compressible */);
-	}
-
-	public stabilizeNodeKey(key: LocalNodeKey): StableNodeKey {
-		return brand(this.getId(extractFromOpaque(key)));
-	}
-
-	public tryLocalizeNodeKey(key: string): LocalNodeKey | undefined {
-		if (!isStableNodeKey(key) || !key.startsWith("a110ca7e-add1-4000-8000-")) {
-			return undefined;
-		}
-		const localNodeKey = Number.parseInt(key.substring(24), 16);
-		return localNodeKey < this.count
-			? brand(localNodeKey as SessionSpaceCompressedId)
-			: undefined;
-	}
-
-	public getId(offset: number): StableId {
-		assert(offset >= 0, 0x6e7 /* UUID offset may not be negative */);
-		assert(offset < 281_474_976_710_656, 0x6e8 /* UUID offset must be at most 16^12 */);
-		return assertIsStableId(
-			`a110ca7e-add1-4000-8000-${Math.round(offset).toString(16).padStart(12, "0")}`,
-		);
-	}
-}

package/src/feature-libraries/node-key/nodeKey.ts

@@ -1,47 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import type { SessionSpaceCompressedId, StableId } from "@fluidframework/id-compressor";
-
-import type { TreeNodeSchemaIdentifier } from "../../core/index.js";
-import { type Brand, type Opaque, brand } from "../../util/index.js";
-
-/**
- * A key which uniquely identifies a node in the tree within this session.
- * @remarks {@link LocalNodeKey}s must not be serialized and stored as data without first being converted into a {@link StableNodeKey}.
- * They are local to the current session and equivalent nodes in another session will not necessarily have the same {@link LocalNodeKey}.
- * However, they are otherwise preferential to use over {@link StableNodeKey}s as they are much smaller.
- * For example, they are more efficient than {@link StableNodeKey}s when used as keys in a map.
- * {@link LocalNodeKey}s may be compared or equated via {@link compareLocalNodeKeys}.
- */
-export interface LocalNodeKey
-	extends Opaque<Brand<SessionSpaceCompressedId, "Local Node Key">> {}
-
-/**
- * A UUID which identifies a node in the tree.
- * This key is universally unique and stable forever; therefore it is safe to persist as data in a SharedTree or other DDS/database.
- * When not persisted or serialized, it is preferable to use a {@link LocalNodeKey} instead for better performance.
- */
-export type StableNodeKey = Brand<StableId, "Stable Node Key">;
-
-/**
- * Compares two {@link LocalNodeKey}s.
- * All {@link LocalNodeKey}s retrieved from a single SharedTree client can be totally ordered using this comparator.
- * @param a - the first key to compare
- * @param b - the second key to compare
- * @returns `0` if `a` and `b` are the same key, otherwise `-1` if `a` is ordered before `b` or `1` if `a` is ordered after `b`.
- */
-export function compareLocalNodeKeys(a: LocalNodeKey, b: LocalNodeKey): -1 | 0 | 1 {
-	return a === b ? 0 : a > b ? 1 : -1;
-}
-
-/**
- * The TreeNodeSchemaIdentifier for node keys.
- * @privateRemarks TODO: Come up with a unified and collision-resistant naming schema for types defined by the system.
- * For now, we'll use `__` to reduce the change of collision, since this is what other internal properties use in Fluid.
- */
-export const nodeKeyTreeIdentifier: TreeNodeSchemaIdentifier = brand(
-	"com.fluidframework.nodeKey.NodeKey",
-);

package/src/feature-libraries/node-key/nodeKeyManager.ts

@@ -1,93 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { assert } from "@fluidframework/core-utils/internal";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import { assertIsStableId, isStableId } from "@fluidframework/id-compressor/internal";
-
-import { brand, extractFromOpaque } from "../../util/index.js";
-
-import type { LocalNodeKey, StableNodeKey } from "./nodeKey.js";
-
-/**
- * An object which handles the generation of node keys as well as conversion between their two types ({@link StableNodeKey} and {@link LocalNodeKey}).
- */
-export interface NodeKeyManager {
-	/**
-	 * Generate a {@link StableNodeKey}.
-	 */
-	generateLocalNodeKey(): LocalNodeKey;
-
-	/**
-	 * Convert the given {@link StableNodeKey} into its {@link LocalNodeKey} form.
-	 */
-	localizeNodeKey(key: StableNodeKey): LocalNodeKey;
-
-	/**
-	 * Convert the given {@link LocalNodeKey} into its {@link StableNodeKey} form.
-	 */
-	stabilizeNodeKey(key: LocalNodeKey): StableNodeKey;
-
-	/**
-	 * Attempts to recompress a StableNodeKey.
-	 * @param key - The key that is attempted to recompress.
-	 * @returns The `LocalNodeKey` associated with `key` or undefined if the key was not generated by any session known to this compressor.
-	 */
-	tryLocalizeNodeKey(key: string): LocalNodeKey | undefined;
-}
-
-/**
- * Creates a {@link NodeKeyManager} from the given {@link IIdCompressor}.
- * @param idCompressor - the compressor to use for key generation, compression, and decompression.
- * If undefined, then attempts to generate or convert keys will throw an error.
- */
-export function createNodeKeyManager(
-	idCompressor?: IIdCompressor | undefined,
-): NodeKeyManager {
-	return {
-		generateLocalNodeKey: () => {
-			assert(
-				idCompressor !== undefined,
-				0x6e4 /* Runtime IdCompressor must be available to generate local node keys */,
-			);
-			return brand(idCompressor.generateCompressedId());
-		},
-
-		localizeNodeKey: (key: StableNodeKey) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e5 /* Runtime IdCompressor must be available to convert node keys */,
-			);
-			return brand(idCompressor.recompress(key));
-		},
-
-		stabilizeNodeKey: (key: LocalNodeKey) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e6 /* Runtime IdCompressor must be available to convert node keys */,
-			);
-			return brand(
-				// TODO: The assert below is required for type safety but is maybe slow
-				assertIsStableId(idCompressor.decompress(extractFromOpaque(key))),
-			);
-		},
-		tryLocalizeNodeKey: (key: string) => {
-			assert(
-				idCompressor !== undefined,
-				0x6e9 /* Runtime IdCompressor must be available to convert node keys */,
-			);
-			if (isStableNodeKey(key)) {
-				const compressedKey = idCompressor.tryRecompress(key);
-				if (compressedKey !== undefined) {
-					return brand(compressedKey);
-				}
-			}
-		},
-	};
-}
-
-export function isStableNodeKey(key: string): key is StableNodeKey {
-	return isStableId(key);
-}