@fluidframework/tree 2.41.0-338401 → 2.42.0

package/src/simple-tree/api/schemaFactory.ts

@@ -3,21 +3,31 @@
  * Licensed under the MIT License.
  */
 
-import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
 import { isFluidHandle } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
 
 import type { TreeValue } from "../../core/index.js";
-import type { NodeIdentifierManager } from "../../feature-libraries/index.js";
+// This import is required for intellisense in @link doc comments on mouseover in VSCode.
+// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
+import type { TreeAlpha } from "../../shared-tree/index.js";
 import {
 	type RestrictiveStringRecord,
+	compareSets,
 	getOrCreate,
 	isReadonlyArray,
 } from "../../util/index.js";
-// This import is required for intellisense in @link doc comments on mouseover in VSCode.
-// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars
-import type { TreeAlpha } from "../../shared-tree/index.js";
-
+import type {
+	NodeKind,
+	WithType,
+	TreeNodeSchema,
+	TreeNodeSchemaClass,
+	TreeNodeSchemaNonClass,
+	TreeNodeSchemaBoth,
+	UnhydratedFlexTreeNode,
+} from "../core/index.js";
+import { isLazy } from "../flexList.js";
 import {
 	booleanSchema,
 	handleSchema,
@@ -26,6 +36,16 @@ import {
 	stringSchema,
 	type LeafSchema,
 } from "../leafNodeSchema.js";
+import {
+	arraySchema,
+	type MapNodeInsertableData,
+	mapSchema,
+	objectSchema,
+	type TreeArrayNode,
+	type InsertableObjectFromSchemaRecord,
+	type TreeMapNode,
+	type TreeObjectNode,
+} from "../node-kinds/index.js";
 import {
 	FieldKind,
 	type FieldSchema,
@@ -42,25 +62,15 @@ import {
 	type ImplicitAnnotatedAllowedTypes,
 	type UnannotateImplicitAllowedTypes,
 	type UnannotateSchemaRecord,
+	normalizeAllowedTypes,
 } from "../schemaTypes.js";
-import type {
-	NodeKind,
-	WithType,
-	TreeNodeSchema,
-	TreeNodeSchemaClass,
-	TreeNodeSchemaNonClass,
-	TreeNodeSchemaBoth,
-} from "../core/index.js";
-import { type TreeArrayNode, arraySchema } from "../arrayNode.js";
-import {
-	type InsertableObjectFromSchemaRecord,
-	type TreeObjectNode,
-	objectSchema,
-} from "../objectNode.js";
-import { type MapNodeInsertableData, type TreeMapNode, mapSchema } from "../mapNode.js";
-import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
+
 import { createFieldSchemaUnsafe } from "./schemaFactoryRecursive.js";
-import { isLazy } from "../flexList.js";
+import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+import { createIdCompressor } from "@fluidframework/id-compressor/internal";
+import type { FlexTreeHydratedContextMinimal } from "../../feature-libraries/index.js";
+import { unhydratedFlexTreeFromInsertable } from "../unhydratedFlexTreeFromInsertable.js";
 
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
@@ -290,9 +300,7 @@ export interface SchemaStatics {
 	) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
 }
 
-const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {
-	return undefined;
-});
+const defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);
 
 // The following overloads for optional and required are used to get around the fact that
 // the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes
@@ -763,9 +771,9 @@ export class SchemaFactory<
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Map", types);
-			return getOrCreate(
-				this.structuralTypes,
+			return this.getStructuralType(
 				fullName,
+				types,
 				() =>
 					this.namedMap(
 						fullName as TName,
@@ -951,7 +959,7 @@ export class SchemaFactory<
 		if (allowedTypes === undefined) {
 			const types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];
 			const fullName = structuralName("Array", types);
-			return getOrCreate(this.structuralTypes, fullName, () =>
+			return this.getStructuralType(fullName, types, () =>
 				this.namedArray(fullName, nameOrAllowedTypes as T, false, true),
 			) as TreeNodeSchemaClass<
 				ScopedSchemaName<TScope, string>,
@@ -975,6 +983,35 @@ export class SchemaFactory<
 		return out;
 	}
 
+	/**
+	 * Retrieves or creates a structural {@link TreeNodeSchema} with the specified name and types.
+	 *
+	 * @param fullName - The name for the structural schema.
+	 * @param types - The input schema(s) used to define the structural schema.
+	 * @param builder - A function that builds the schema if it does not already exist.
+	 * @returns The structural {@link TreeNodeSchema} associated with the given name and types.
+	 * @throws `UsageError` if a schema structurally named schema with the same name is cached in `structuralTypes` but had different input types.
+	 */
+	private getStructuralType(
+		fullName: string,
+		types: TreeNodeSchema | readonly TreeNodeSchema[],
+		builder: () => TreeNodeSchema,
+	): TreeNodeSchema {
+		const structural = getOrCreate(this.structuralTypes, fullName, builder);
+		const inputTypes = new Set(normalizeAllowedTypes(types));
+		const outputTypes = new Set(
+			normalizeAllowedTypes(structural.info as TreeNodeSchema | readonly TreeNodeSchema[]),
+		);
+		// If our cached value had a different set of types then were requested, the user must have caused a collision.
+		const same = compareSets({ a: inputTypes, b: outputTypes });
+		if (!same) {
+			throw new UsageError(
+				`Structurally named schema collision: two schema named "${fullName}" were defined with different input schema.`,
+			);
+		}
+		return structural;
+	}
+
 	/**
 	 * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
 	 *
@@ -1072,11 +1109,11 @@ export class SchemaFactory<
 	 * - It is a UUID which will not collide with other generated UUIDs.
 	 *
 	 * - It is compressed to a space-efficient representation when stored in the document.
+	 * Reading the identifier before inserting the node into a tree prevents the identifier from being stored in its compressed form,
+	 * resulting in a larger storage footprint.
 	 *
 	 * - A compressed form of the identifier can be accessed at runtime via the {@link TreeNodeApi.shortId|Tree.shortId()} API.
 	 *
-	 * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into a tree.
-	 *
 	 * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).
 	 * In that case, if the user requires it to be unique, it is up to them to ensure uniqueness.
 	 * User-supplied identifiers may be read immediately, even before insertion into the tree.
@@ -1085,10 +1122,19 @@ export class SchemaFactory<
 	 */
 	public get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {
 		const defaultIdentifierProvider: DefaultProvider = getDefaultProvider(
-			(nodeKeyManager: NodeIdentifierManager) => {
-				return nodeKeyManager.stabilizeNodeIdentifier(
-					nodeKeyManager.generateLocalNodeIdentifier(),
-				);
+			(
+				context: FlexTreeHydratedContextMinimal | "UseGlobalContext",
+			): UnhydratedFlexTreeNode[] => {
+				const id =
+					context === "UseGlobalContext"
+						? globalIdentifierAllocator.decompress(
+								globalIdentifierAllocator.generateCompressedId(),
+							)
+						: context.nodeKeyManager.stabilizeNodeIdentifier(
+								context.nodeKeyManager.generateLocalNodeIdentifier(),
+							);
+
+				return [unhydratedFlexTreeFromInsertable(id, this.string)];
 			},
 		);
 		return createFieldSchema(FieldKind.Identifier, this.string, {
@@ -1261,3 +1307,11 @@ export function structuralName<const T extends string>(
 	}
 	return `${collectionName}<${inner}>`;
 }
+
+/**
+ * Used to allocate default identifiers for unhydrated nodes when no context is available.
+ * @remarks
+ * The identifiers allocated by this will never be compressed to Short Ids.
+ * Using this is only better than creating fully random V4 UUIDs because it reduces the entropy making it possible for things like text compression to work slightly better.
+ */
+const globalIdentifierAllocator: IIdCompressor = createIdCompressor();

package/src/simple-tree/api/schemaFactoryAlpha.ts

@@ -3,6 +3,14 @@
  * Licensed under the MIT License.
  */
 
+import {
+	type ArrayNodeCustomizableSchema,
+	arraySchema,
+	type MapNodeCustomizableSchema,
+	mapSchema,
+	type ObjectNodeSchema,
+	objectSchema,
+} from "../node-kinds/index.js";
 import {
 	defaultSchemaFactoryObjectOptions,
 	SchemaFactory,
@@ -17,7 +25,6 @@ import type {
 	ImplicitFieldSchema,
 	NodeSchemaOptions,
 } from "../schemaTypes.js";
-import { objectSchema } from "../objectNode.js";
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import type { NodeKind, TreeNodeSchemaClass } from "../core/index.js";
 import type {
@@ -25,12 +32,7 @@ import type {
 	MapNodeCustomizableSchemaUnsafe,
 	System_Unsafe,
 } from "./typesUnsafe.js";
-import { mapSchema } from "../mapNode.js";
-import { arraySchema } from "../arrayNode.js";
-import type { ObjectNodeSchema } from "../objectNodeTypes.js";
 import type { SimpleObjectNodeSchema } from "../simpleSchema.js";
-import type { ArrayNodeCustomizableSchema } from "../arrayNodeTypes.js";
-import type { MapNodeCustomizableSchema } from "../mapNodeTypes.js";
 
 /**
  * {@link SchemaFactory} with additional alpha APIs.

package/src/simple-tree/api/schemaFactoryRecursive.ts

@@ -4,8 +4,8 @@
  */
 
 import type { RestrictiveStringRecord } from "../../util/index.js";
-import type { InsertableObjectFromSchemaRecord } from "../objectNode.js";
-
+import type { NodeKind, TreeNodeSchema, WithType, TreeNode } from "../core/index.js";
+import type { InsertableObjectFromSchemaRecord } from "../node-kinds/index.js";
 import {
 	type FieldKind,
 	type FieldProps,
@@ -14,7 +14,7 @@ import {
 	type ImplicitFieldSchema,
 	type InsertableTreeNodeFromImplicitAllowedTypes,
 } from "../schemaTypes.js";
-import type { NodeKind, TreeNodeSchema, WithType, TreeNode } from "../core/index.js";
+
 import type { FieldSchemaAlphaUnsafe, System_Unsafe } from "./typesUnsafe.js";
 
 export function createFieldSchemaUnsafe<

package/src/simple-tree/api/schemaFromSimple.ts

@@ -4,6 +4,7 @@
  */
 
 import { unreachableCase, fail } from "@fluidframework/core-utils/internal";
+
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import {
 	type FieldSchema,
@@ -17,8 +18,9 @@ import type {
 	SimpleNodeSchema,
 	SimpleTreeSchema,
 } from "../simpleSchema.js";
-import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
+
 import type { TreeSchema } from "./configuration.js";
+import { SchemaFactoryAlpha } from "./schemaFactoryAlpha.js";
 
 const factory = new SchemaFactoryAlpha(undefined);
 

package/src/simple-tree/api/simpleSchemaToJsonSchema.ts

@@ -28,9 +28,7 @@ import type {
 import { NodeKind, type TreeNodeSchema } from "../core/index.js";
 import type { TreeSchema } from "./configuration.js";
 import type { TreeSchemaEncodingOptions } from "./getJsonSchema.js";
-import { ObjectNodeSchema } from "../objectNodeTypes.js";
-import { ArrayNodeSchema } from "../arrayNodeTypes.js";
-import { MapNodeSchema } from "../mapNodeTypes.js";
+import { ArrayNodeSchema, MapNodeSchema, ObjectNodeSchema } from "../node-kinds/index.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 
 /**

package/src/simple-tree/api/storedSchema.ts

@@ -4,11 +4,11 @@
  */
 
 import type { FluidClientVersion, ICodecOptions } from "../../codec/index.js";
+import { SchemaVersion } from "../../core/index.js";
 import {
 	defaultSchemaPolicy,
 	encodeTreeSchema,
 	makeSchemaCodec,
-	SchemaCodecVersion,
 } from "../../feature-libraries/index.js";
 import {
 	clientVersionToSchemaVersion,
@@ -17,10 +17,11 @@ import {
 } from "../../feature-libraries/schema-index/index.js";
 import type { JsonCompatible } from "../../util/index.js";
 import { normalizeFieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
+import type { SimpleTreeSchema } from "../simpleSchema.js";
 import { simpleToStoredSchema } from "../toStoredSchema.js";
-import type { SchemaCompatibilityStatus } from "./tree.js";
+
 import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
+import type { SchemaCompatibilityStatus } from "./tree.js";
 
 /**
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
@@ -98,7 +99,7 @@ export function comparePersistedSchema(
 ): Omit<SchemaCompatibilityStatus, "canInitialize"> {
 	// Any version can be passed down to makeSchemaCodec here.
 	// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.
-	const schemaCodec = makeSchemaCodec(options, SchemaCodecVersion.v1);
+	const schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);
 	const stored = schemaCodec.decode(persisted as Format);
 	const viewSchema = new SchemaCompatibilityTester(
 		defaultSchemaPolicy,

package/src/simple-tree/api/tree.ts

@@ -10,13 +10,11 @@ import type {
 	RevertibleAlphaFactory,
 	RevertibleFactory,
 } from "../../core/index.js";
-
 import type {
 	// This is referenced by doc comments.
 	// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports
 	TreeAlpha,
 } from "../../shared-tree/index.js";
-
 import type {
 	ImplicitFieldSchema,
 	InsertableField,
@@ -26,8 +24,9 @@ import type {
 	TreeFieldFromImplicitField,
 	UnsafeUnknownSchema,
 } from "../schemaTypes.js";
-import type { VerboseTree } from "./verboseTree.js";
 import type { SimpleTreeSchema } from "../simpleSchema.js";
+
+import type { TreeViewConfiguration } from "./configuration.js";
 import type {
 	RunTransactionParams,
 	TransactionCallbackStatus,
@@ -35,7 +34,7 @@ import type {
 	TransactionResultExt,
 	VoidTransactionCallbackStatus,
 } from "./transactionTypes.js";
-import type { TreeViewConfiguration } from "./configuration.js";
+import type { VerboseTree } from "./verboseTree.js";
 
 /**
  * A tree from which a {@link TreeView} can be created.

package/src/simple-tree/api/treeBeta.ts

@@ -11,10 +11,11 @@ import {
 	type Unhydrated,
 	type WithType,
 } from "../core/index.js";
-import { treeNodeApi } from "./treeNodeApi.js";
-import { createFromCursor } from "./create.js";
 import type { ImplicitFieldSchema, TreeFieldFromImplicitField } from "../schemaTypes.js";
+
+import { createFromCursor } from "./create.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
+import { treeNodeApi } from "./treeNodeApi.js";
 
 // Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,
 // and where most of the actual implementation is for much of it.

package/src/simple-tree/api/treeNodeApi.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, unreachableCase } from "@fluidframework/core-utils/internal";
 
 import { EmptyKey, rootFieldKey } from "../../core/index.js";
 import { type TreeStatus, isTreeValue, FieldKinds } from "../../feature-libraries/index.js";
@@ -34,17 +34,23 @@ import {
 	type TreeNode,
 	tryGetTreeNodeSchema,
 	getOrCreateNodeFromInnerNode,
-	UnhydratedFlexTreeNode,
 	typeSchemaSymbol,
 	getOrCreateInnerNode,
 } from "../core/index.js";
-import { isObjectNodeSchema } from "../objectNodeTypes.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
+import { isObjectNodeSchema } from "../node-kinds/index.js";
+import { getTreeNodeForField } from "../getTreeNodeForField.js";
 
 /**
  * Provides various functions for analyzing {@link TreeNode}s.
- * * @remarks
- * This type should only be used via the public `Tree` export.
+ *
+ * @remarks
+ * With the exception of {@link TreeNodeApi.status}, these functions should not be called with nodes that have
+ * been {@link TreeStatus.Deleted | deleted}.
+ * To verify whether or not a node already has been deleted, use the {@link TreeNodeApi.status} function.
+ *
+ * This type should only be used via the public {@link (Tree:variable)} export.
+ *
  * @privateRemarks
  * Due to limitations of API-Extractor link resolution, this type can't be moved into internalTypes but should be considered just an implementation detail of the `Tree` export.
  *
@@ -75,14 +81,19 @@ export interface TreeNodeApi {
 
 	/**
 	 * Return the node under which this node resides in the tree (or undefined if this is a root node of the tree).
+	 *
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
 	 */
 	parent(node: TreeNode): TreeNode | undefined;
 
 	/**
 	 * The key of the given node under its parent.
+	 *
 	 * @remarks
 	 * If `node` is an element in a {@link (TreeArrayNode:interface)}, this returns the index of `node` in the array node (a `number`).
 	 * Otherwise, this returns the key of the field that it is under (a `string`).
+	 *
+	 * @throws A {@link @fluidframework/telemetry-utils#UsageError} if the node has been {@link TreeStatus.Deleted | deleted}.
 	 */
 	key(node: TreeNode): string | number;
 
@@ -108,9 +119,9 @@ export interface TreeNodeApi {
 	/**
 	 * Returns the {@link SchemaFactory.identifier | identifier} of the given node in the most compressed form possible.
 	 * @remarks
-	 * If the node's identifier is a valid UUID that was automatically generated by the SharedTree, then this will return a process-unique integer corresponding to that identifier.
-	 * Note that the node must already have been inserted into the tree in order to retrieve a generated UUID (or shortId will error).
+	 * If the node is {@link Unhydrated | hydrated}  and its identifier is a valid UUID that was automatically generated by the SharedTree it is part of (or something else using the same {@link @fluidframework/id-compressor#IIdCompressor}), then this will return a process-unique integer corresponding to that identifier.
 	 * This is useful for performance-sensitive scenarios involving many nodes with identifiers that need to be compactly retained in memory or used for efficient lookup.
+	 * Note that automatically generated identifiers that were accessed before the node was hydrated will return the generated UUID, not the process-unique integer.
 	 *
 	 * If the node's identifier is any other user-provided string, then this will return that string.
 	 *
@@ -118,7 +129,7 @@ export interface TreeNodeApi {
 	 *
 	 * If the node has more than one identifier, then this will throw an error.
 	 *
-	 * The returned integer must not be serialized or preserved outside of the current process.
+	 * The returned integer should not be serialized or preserved outside of the current process.
 	 * Its lifetime is that of the current in-memory instance of the FF container for this client, and it is not guaranteed to be unique or stable outside of that context.
 	 * The same node's identifier may, for example, be different across multiple sessions for the same client and document, or different across two clients in the same session.
 	 */
@@ -126,7 +137,7 @@ export interface TreeNodeApi {
 }
 
 /**
- * The `Tree` object holds various functions for analyzing {@link TreeNode}s.
+ * {@inheritDoc TreeNodeApi}
  */
 export const treeNodeApi: TreeNodeApi = {
 	parent(node: TreeNode): TreeNode | undefined {
@@ -217,42 +228,7 @@ export const treeNodeApi: TreeNodeApi = {
 		return tryGetSchema(node) ?? fail(0xb37 /* Not a tree node */);
 	},
 	shortId(node: TreeNode): number | string | undefined {
-		const schema = node[typeSchemaSymbol];
-		if (!isObjectNodeSchema(schema)) {
-			return undefined;
-		}
-
-		const flexNode = getOrCreateInnerNode(node);
-		const identifierFieldKeys = schema.identifierFieldKeys;
-
-		switch (identifierFieldKeys.length) {
-			case 0:
-				return undefined;
-			case 1: {
-				const identifier = flexNode.tryGetField(identifierFieldKeys[0] ?? oob())?.boxedAt(0);
-				if (flexNode instanceof UnhydratedFlexTreeNode) {
-					if (identifier === undefined) {
-						throw new UsageError(
-							"Tree.shortId cannot access default identifiers on unhydrated nodes",
-						);
-					}
-					return identifier.value as string;
-				}
-				assert(
-					identifier?.context.isHydrated() === true,
-					0xa27 /* Expected hydrated identifier */,
-				);
-				const identifierValue = identifier.value as string;
-
-				const localNodeKey =
-					identifier.context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
-				return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : identifierValue;
-			}
-			default:
-				throw new UsageError(
-					"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
-				);
-		}
+		return getIdentifierFromNode(node, "preferCompressed");
 	},
 };
 
@@ -285,6 +261,100 @@ export function tryGetSchema(value: unknown): undefined | TreeNodeSchema {
 	}
 }
 
+/**
+ * Gets the identifier from a node.
+ *
+ * @param node - {@link TreeNode} where you want to extract the identifier from.
+ * @param compression - string value to determine what type of identifier you want to retrieve.
+ *
+ * @remarks
+ * If the node does not contain an identifier field, it returns undefined.
+ *
+ * If `compression` is set to `compressed`:
+ *
+ * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.
+ *
+ * - If the node contains an identifier, but is not compressible or unknown by the id compressor, `undefined` is returned.
+ *
+ * If `compression` is set to `preferCompressed`:
+ *
+ * - If the node contains a compressible identifier known by the id compressor, the compressed identifier is returned.
+ *
+ * - If the node contains an identifier, but is not compressible or unknown by the id compressor, the uncompressed identifier is returned.
+ *
+ * If `compression` is set to `uncompressed`:
+ * - If the node contains an identifier field, the uncompressed identifier is returned.
+ */
+export function getIdentifierFromNode(
+	node: TreeNode,
+	compression: "preferCompressed",
+): number | string | undefined;
+export function getIdentifierFromNode(
+	node: TreeNode,
+	compression: "compressed",
+): number | undefined;
+export function getIdentifierFromNode(
+	node: TreeNode,
+	compression: "uncompressed",
+): string | undefined;
+export function getIdentifierFromNode(
+	node: TreeNode,
+	compression: "preferCompressed" | "compressed" | "uncompressed",
+): number | string | undefined {
+	const schema = node[typeSchemaSymbol];
+	if (!isObjectNodeSchema(schema)) {
+		return undefined;
+	}
+
+	const flexNode = getOrCreateInnerNode(node);
+	const identifierFieldKeys = schema.identifierFieldKeys;
+
+	switch (identifierFieldKeys.length) {
+		case 0:
+			return undefined;
+		case 1: {
+			const key = identifierFieldKeys[0] ?? oob();
+			const identifierField = flexNode.tryGetField(key);
+			assert(identifierField !== undefined, 0xbb5 /* missing identifier field */);
+			const identifierValue = getTreeNodeForField(identifierField);
+			assert(typeof identifierValue === "string", 0xbb6 /* identifier not a string */);
+
+			const context = flexNode.context;
+			switch (compression) {
+				case "preferCompressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined
+							? extractFromOpaque(localNodeKey)
+							: identifierValue;
+					} else {
+						return identifierValue;
+					}
+				}
+				case "compressed": {
+					if (context.isHydrated()) {
+						const localNodeKey =
+							context.nodeKeyManager.tryLocalizeNodeIdentifier(identifierValue);
+						return localNodeKey !== undefined ? extractFromOpaque(localNodeKey) : undefined;
+					} else {
+						return undefined;
+					}
+				}
+				case "uncompressed": {
+					return identifierValue;
+				}
+				default:
+					unreachableCase(compression);
+			}
+		}
+		default:
+			throw new UsageError(
+				"shortId() may not be called on a node with more than one identifier. Consider converting extraneous identifier fields to string fields.",
+			);
+	}
+}
+
 /**
  * Gets the stored key with which the provided node is associated in the parent.
  */

package/src/simple-tree/api/typesUnsafe.ts

@@ -28,7 +28,7 @@ import type {
 	TreeNodeSchemaCore,
 	TreeNodeSchemaClass,
 } from "../core/index.js";
-import type { TreeArrayNode } from "../arrayNode.js";
+import type { TreeArrayNode } from "../node-kinds/index.js";
 import type { FlexListToUnion, LazyItem } from "../flexList.js";
 import type { SimpleArrayNodeSchema, SimpleMapNodeSchema } from "../simpleSchema.js";