@fluidframework/tree 2.92.0 → 2.93.0

package/lib/simple-tree/api/schemaFactoryAlpha.d.ts

@@ -4,7 +4,7 @@
  */
 import type { RestrictiveStringRecord } from "../../util/index.js";
 import { type NodeKind, type TreeNodeSchemaClass, type ImplicitAllowedTypes, type WithType } from "../core/index.js";
-import { type FieldProps, type FieldSchemaAlpha, type FieldPropsAlpha, type FieldKind, type ImplicitFieldSchema, type InsertableTreeFieldFromImplicitField, type FieldSchema, type DefaultProvider } from "../fieldSchema.js";
+import { type FieldProps, type FieldSchemaAlpha, type FieldPropsAlpha, FieldKind, type ImplicitFieldSchema, type InsertableTreeFieldFromImplicitField, type FieldSchema, type DefaultProvider } from "../fieldSchema.js";
 import type { LeafSchema } from "../leafNodeSchema.js";
 import { type ArrayNodeCustomizableSchemaAlpha, type MapNodeCustomizableSchema, type ObjectNodeSchema, type ObjectNodeSchemaWorkaround, type RecordNodeCustomizableSchema } from "../node-kinds/index.js";
 import type { SchemaType, SimpleObjectNodeSchema } from "../simpleSchema.js";
@@ -80,6 +80,27 @@ export interface SchemaStaticsAlpha {
     readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
         defaultProvider: DefaultProvider;
     }>;
+    /**
+     * Creates a field schema that is Optional in the view but behaves as Required in the stored schema
+     * during the rollout period of an optional-field migration.
+     *
+     * @remarks
+     * Use this to incrementally migrate a required field to optional without a coordinated deployment.
+     * The migration path is:
+     *
+     * 1. Start with `sf.required(T)` — all clients require the field.
+     * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing `undefined` is blocked at runtime.
+     * 3. Deploy `sf.optional(T)` once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.
+     *
+     * Analogous to {@link SchemaStaticsBeta.staged} for allowed types, but for field optionality.
+     *
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
+     *
+     * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+     * See {@link FieldSchemaMetadata.custom}.
+     */
+    readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     /**
      * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.
      * Use with {@link ValidateRecursiveSchema} for improved type safety.
@@ -190,7 +211,15 @@ export declare class SchemaFactoryAlpha<out TScope extends string | undefined =
         defaultProvider: DefaultProvider;
     }>;
     /**
-     * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
+     * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+     */
+    readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    /**
+     * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+     */
+    static readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "stagedOptionalUpgrade" | "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    /**
+     * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.
      *
      * @param name - Unique identifier for this schema within this factory's scope.
      * @param allowedTypes - The types that may appear as values in the map.

package/lib/simple-tree/api/schemaFactoryAlpha.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaFactoryAlpha.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryAlpha.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemaFactoryAlpha.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryAlpha.ts"],"names":[],"mappings":"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"}

package/lib/simple-tree/api/schemaFactoryAlpha.js

@@ -2,10 +2,10 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { normalizeAllowedTypes, isTreeNode, } from "../core/index.js";
+import { normalizeAllowedTypes, isTreeNode, createSchemaUpgrade, } from "../core/index.js";
 // These imports prevent a large number of type references in the API reports from showing up as *_2.
 /* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */
-import { getDefaultProvider, createFieldSchema, } from "../fieldSchema.js";
+import { FieldKind, getDefaultProvider, createFieldSchema, } from "../fieldSchema.js";
 import { arraySchema, mapSchema, objectSchema, recordSchema, } from "../node-kinds/index.js";
 import { unhydratedFlexTreeFromInsertableNode } from "../unhydratedFlexTreeFromInsertable.js";
 import { defaultSchemaFactoryObjectOptions, scoped, } from "./schemaFactory.js";
@@ -42,9 +42,17 @@ const withDefault = (fieldSchema, defaultValue) => {
     };
     return createFieldSchema(typedFieldSchema.kind, typedFieldSchema.allowedTypes, propsWithDefault);
 };
+const stagedOptional = (t, props) => {
+    return createFieldSchema(FieldKind.Optional, t, {
+        defaultProvider: getDefaultProvider(() => []),
+        ...props,
+        stagedOptionalUpgrade: createSchemaUpgrade(),
+    });
+};
 const schemaStaticsAlpha = {
     withDefault,
     withDefaultRecursive: withDefault,
+    stagedOptional,
 };
 /**
  * {@link SchemaFactory} with additional alpha APIs.
@@ -86,6 +94,10 @@ export class SchemaFactoryAlpha extends SchemaFactoryBeta {
          * {@inheritdoc SchemaStaticsAlpha.withDefault}
          */
         this.withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
+        /**
+         * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+         */
+        this.stagedOptional = schemaStaticsAlpha.stagedOptional;
     }
     /**
      * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.
@@ -117,7 +129,7 @@ export class SchemaFactoryAlpha extends SchemaFactoryBeta {
         return this.objectAlpha(name, t, options);
     }
     /**
-     * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.
+     * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.
      *
      * @param name - Unique identifier for this schema within this factory's scope.
      * @param allowedTypes - The types that may appear as values in the map.
@@ -242,4 +254,8 @@ SchemaFactoryAlpha.withDefault = schemaStaticsAlpha.withDefault;
  * {@inheritdoc SchemaStaticsAlpha.withDefault}
  */
 SchemaFactoryAlpha.withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;
+/**
+ * {@inheritdoc SchemaStaticsAlpha.stagedOptional}
+ */
+SchemaFactoryAlpha.stagedOptional = schemaStaticsAlpha.stagedOptional;
 //# sourceMappingURL=schemaFactoryAlpha.js.map

package/lib/simple-tree/api/schemaFactoryAlpha.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaFactoryAlpha.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryAlpha.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { RestrictiveStringRecord } from \"../../util/index.js\";\nimport {\n\ttype NodeKind,\n\ttype TreeNodeSchemaClass,\n\ttype ImplicitAllowedTypes,\n\ttype WithType,\n\tnormalizeAllowedTypes,\n\tisTreeNode,\n} from \"../core/index.js\";\n// These imports prevent a large number of type references in the API reports from showing up as *_2.\n/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */\nimport {\n\ttype FieldProps,\n\ttype FieldSchemaAlpha,\n\ttype FieldPropsAlpha,\n\ttype FieldKind,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype FieldSchema,\n\tgetDefaultProvider,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n} from \"../fieldSchema.js\";\nimport type { LeafSchema } from \"../leafNodeSchema.js\";\nimport {\n\ttype ArrayNodeCustomizableSchema,\n\ttype ArrayNodeCustomizableSchemaAlpha,\n\tarraySchema,\n\ttype MapNodeCustomizableSchema,\n\tmapSchema,\n\ttype ObjectNodeSchema,\n\ttype ObjectNodeSchemaWorkaround,\n\tobjectSchema,\n\ttype RecordNodeCustomizableSchema,\n\trecordSchema,\n} from \"../node-kinds/index.js\";\nimport type { SchemaType, SimpleObjectNodeSchema } from \"../simpleSchema.js\";\nimport type { SimpleLeafNodeSchema } from \"../simpleSchema.js\";\nimport { unhydratedFlexTreeFromInsertableNode } from \"../unhydratedFlexTreeFromInsertable.js\";\n\nimport {\n\tdefaultSchemaFactoryObjectOptions,\n\tscoped,\n\ttype NodeSchemaOptionsAlpha,\n\ttype ObjectSchemaOptionsAlpha,\n\ttype ScopedSchemaName,\n} from \"./schemaFactory.js\";\nimport { SchemaFactoryBeta } from \"./schemaFactoryBeta.js\";\nimport { schemaStatics } from \"./schemaStatics.js\";\nimport { TreeBeta } from \"./treeBeta.js\";\nimport type {\n\tArrayNodeCustomizableSchemaUnsafe,\n\tFieldSchemaAlphaUnsafe,\n\tInsertableObjectFromSchemaRecordAlphaUnsafe,\n\tMapNodeCustomizableSchemaUnsafe,\n\tSystem_Unsafe,\n\tTreeRecordNodeUnsafe,\n\tUnenforced,\n} from \"./typesUnsafe.js\";\n/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */\n\n/**\n * A provider for values in tree nodes.\n *\n * @remarks\n * This type represents two ways to provide node values:\n *\n * 1. **A value**: Provide any value directly (number, string, object, array, etc.). When a value is provided,\n * the data is copied for each use to ensure independence between instances. The value must be of an allowed type for the field.\n *\n * 2. **A generator function**: A function that returns a value. The function is called each time a default is needed,\n * allowing for dynamic defaults or explicit control over value creation. The return value must be of an allowed type for the field.\n *\n * Values should be preferred over generator functions when possible, as they are simpler and more efficient.\n * Generator functions should be used when the default value needs to be dynamic or when it is not possible to provide a value directly.\n *\n * @example\n * ```typescript\n * // Provide a value directly\n * factory.withDefault(factory.required(factory.string), \"default\")\n * factory.withDefault(factory.optional(Person), new Person({ name: \"Guest\" }))\n *\n * // Use a generator function\n * factory.withDefault(factory.required(factory.string), () => crypto.randomUUID())\n * factory.withDefault(factory.optional(Person), () => new Person({ name: \"Guest\" }))\n * ```\n *\n * @alpha @sealed\n */\nexport type NodeProvider<T> = T | (() => T);\n\n/**\n * Stateless APIs exposed via {@link SchemaFactoryBeta} as both instance properties and as statics.\n * @see {@link SchemaStatics} for why this is useful.\n * @system @sealed @alpha\n */\nexport interface SchemaStaticsAlpha {\n\t/**\n\t * Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors,\n\t * allowing them to be omitted when creating new nodes.\n\t *\n\t * @param fieldSchema - The field schema to add a default to (e.g., `factory.required(factory.string)` or `factory.optional(factory.number)`)\n\t * @param defaultValue - A {@link NodeProvider} specifying the default value.\n\t *\n\t * @example\n\t * ```typescript\n\t * const MySchema = factory.objectAlpha(\"MyObject\", {\n\t *     // Provide values directly\n\t *     name: factory.withDefault(factory.required(factory.string), \"untitled\"),\n\t *     count: factory.withDefault(factory.required(factory.number), 0),\n\t *     metadata: factory.withDefault(factory.optional(Metadata), new Metadata({ version: 1 })),\n\t *\n\t *     // Use generator functions for dynamic values\n\t *     timestamp: factory.withDefault(factory.required(factory.number), () => Date.now()),\n\t *     id: factory.withDefault(factory.required(factory.string), () => crypto.randomUUID()),\n\t * });\n\t *\n\t * const obj1 = new MySchema({}); // All defaults applied\n\t * const obj2 = new MySchema({ name: \"custom\" }); // name=\"custom\", other defaults applied\n\t * ```\n\t *\n\t * @privateRemarks\n\t * This function wraps an existing field schema and adds a default value provider to it.\n\t * The default value will be used when constructing nodes if the field is not explicitly provided or set to `undefined`.\n\t *\n\t * Defaults are evaluated eagerly during node construction, unlike identifier defaults which require context.\n\t */\n\treadonly withDefault: <\n\t\tKind extends FieldKind,\n\t\tTypes extends ImplicitAllowedTypes,\n\t\tTCustomMetadata = unknown,\n\t>(\n\t\tfieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,\n\t\tdefaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,\n\t) => FieldSchemaAlpha<\n\t\tKind,\n\t\tTypes,\n\t\tTCustomMetadata,\n\t\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n\t>;\n\t/**\n\t * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of {@link SchemaStaticsAlpha.withDefault} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\twithDefaultRecursive: <\n\t\tKind extends FieldKind,\n\t\tTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tTCustomMetadata = unknown,\n\t>(\n\t\tfieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>,\n\t\tdefaultValue: Unenforced<\n\t\t\tNodeProvider<\n\t\t\t\tSystem_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<\n\t\t\t\t\tSystem_Unsafe.FieldSchemaUnsafe<Kind, Types>\n\t\t\t\t>\n\t\t\t>\n\t\t>,\n\t) => FieldSchemaAlphaUnsafe<\n\t\tKind,\n\t\tTypes,\n\t\tTCustomMetadata,\n\t\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n\t>;\n}\n\nconst withDefault = <\n\tKind extends FieldKind,\n\tTypes extends ImplicitAllowedTypes,\n\tTCustomMetadata = unknown,\n>(\n\tfieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,\n\tdefaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,\n): FieldSchemaAlpha<\n\tKind,\n\tTypes,\n\tTCustomMetadata,\n\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n> => {\n\tconst typedFieldSchema = fieldSchema as FieldSchemaAlpha<Kind, Types, TCustomMetadata>;\n\n\t// create the default provider function, it is called eagerly during node construction\n\tconst defaultProvider = getDefaultProvider(() => {\n\t\t// Resolve the value: if it's a function, call it; otherwise use it directly\n\t\tlet insertableValue =\n\t\t\ttypeof defaultValue === \"function\" ? (defaultValue as () => unknown)() : defaultValue;\n\n\t\t// If the value is an already-constructed TreeNode (e.g., from a generator function that\n\t\t// returns the same instance repeatedly), clone it to ensure each use gets a fresh instance.\n\t\t// This prevents multi-parenting errors.\n\t\tif (isTreeNode(insertableValue)) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\tinsertableValue = TreeBeta.clone(insertableValue as any);\n\t\t}\n\n\t\t// For optional fields with an undefined default, return an empty array (no value).\n\t\tif (insertableValue === undefined) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Convert the insertable value to an unhydrated flex tree.\n\t\t// For insertable data, this creates a fresh tree structure.\n\t\tconst allowedTypeSet = normalizeAllowedTypes(typedFieldSchema.allowedTypes).evaluateSet();\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\treturn [unhydratedFlexTreeFromInsertableNode(insertableValue as any, allowedTypeSet)];\n\t});\n\n\t// create a new field schema with the default provider\n\tconst propsWithDefault = {\n\t\t...typedFieldSchema.props,\n\t\tdefaultProvider,\n\t};\n\n\treturn createFieldSchema(\n\t\ttypedFieldSchema.kind,\n\t\ttypedFieldSchema.allowedTypes,\n\t\tpropsWithDefault,\n\t);\n};\n\nconst schemaStaticsAlpha: SchemaStaticsAlpha = {\n\twithDefault,\n\n\twithDefaultRecursive: withDefault as SchemaStaticsAlpha[\"withDefaultRecursive\"],\n};\n\n/**\n * {@link SchemaFactory} with additional alpha APIs.\n *\n * @alpha\n * @privateRemarks\n * When building schema, when `options` is not provided, `TCustomMetadata` is inferred as `unknown`.\n * If desired, this could be made to infer `undefined` instead by adding overloads for everything,\n * but currently it is not worth the maintenance overhead as there is no use case which this is known to be helpful for.\n */\nexport class SchemaFactoryAlpha<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> extends SchemaFactoryBeta<TScope, TName> {\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t * @param options - Additional options for the schema.\n\t */\n\tpublic objectAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): ObjectNodeSchemaWorkaround<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {\n\t\t\t...defaultSchemaFactoryObjectOptions,\n\t\t\t...options,\n\t\t});\n\t}\n\n\t/**\n\t * {@inheritdoc SchemaFactory.objectRecursive}\n\t */\n\tpublic override objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\tfalse,\n\t\tT,\n\t\tnever,\n\t\tTCustomMetadata\n\t> &\n\t\tSimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &\n\t\t// We can't just use non generic `ObjectNodeSchema` here since \"Base constructors must all have the same return type\".\n\t\t// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.\n\t\t// ObjectNodeSchema<\n\t\t// \tScopedSchemaName<TScope, Name>,\n\t\t// \t//  T & RestrictiveStringRecord<ImplicitFieldSchema> would be nice to use here, but it breaks the recursive type self references.\n\t\t// \tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t// \tfalse,\n\t\t// \tTCustomMetadata\n\t\t// >\n\t\tPick<ObjectNodeSchema, \"fields\"> {\n\t\t// TODO: syntax highting is vs code is broken here. Don't trust it. Use the compiler instead.\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.objectAlpha(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\toptions,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> &\n\t\t\tObjectNodeSchema<\n\t\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\t\tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\t\tfalse,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t}\n\n\t/**\n\t * Alpha version of {@link SchemaFactory.objectRecursive} that supports field defaults via {@link SchemaStaticsAlpha.withDefaultRecursive}.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * Use this instead of {@link SchemaFactory.objectRecursive} when fields use {@link SchemaStaticsAlpha.withDefaultRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\tpublic objectRecursiveAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,\n\t\tfalse,\n\t\tT,\n\t\tnever,\n\t\tTCustomMetadata\n\t> &\n\t\tSimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &\n\t\tPick<ObjectNodeSchema, \"fields\"> {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.objectAlpha(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\toptions,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> &\n\t\t\tObjectNodeSchema<\n\t\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\t\tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\t\tfalse,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaStatics.leaves}\n\t */\n\tpublic static override readonly leaves = schemaStatics.leaves;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optional}\n\t */\n\tpublic static override readonly optional = schemaStatics.optional;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.required}\n\t */\n\tpublic static override readonly required = schemaStatics.required;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optionalRecursive}\n\t */\n\tpublic static override readonly optionalRecursive = schemaStatics.optionalRecursive;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.requiredRecursive}\n\t */\n\tpublic static override readonly requiredRecursive = schemaStatics.requiredRecursive;\n\n\t/**\n\t * Like {@link SchemaFactory.identifier} but static and a factory function that can be provided {@link FieldProps}.\n\t */\n\tpublic static readonly identifier = schemaStatics.identifier;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.leaves}\n\t */\n\tpublic override readonly leaves = schemaStatics.leaves;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optional}\n\t */\n\tpublic override readonly optional = schemaStatics.optional;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.required}\n\t */\n\tpublic override readonly required = schemaStatics.required;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optionalRecursive}\n\t */\n\tpublic override readonly optionalRecursive = schemaStatics.optionalRecursive;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.requiredRecursive}\n\t */\n\tpublic override readonly requiredRecursive = schemaStatics.requiredRecursive;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic readonly withDefault = schemaStaticsAlpha.withDefault;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic static readonly withDefault = schemaStaticsAlpha.withDefault;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic static readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear as values in the map.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number, {\n\t * \tmetadata: { description: \"A map of numbers\" }\n\t * }) {}\n\t * ```\n\t */\n\tpublic mapAlpha<\n\t\tName extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn mapSchema(\n\t\t\tscoped<TScope, TName, Name>(this, name),\n\t\t\tallowedTypes,\n\t\t\ttrue,\n\t\t\ttrue,\n\t\t\toptions,\n\t\t);\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaFactory.objectRecursive}\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override mapRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\treturn this.mapAlpha(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\toptions,\n\t\t) as unknown as MapNodeCustomizableSchemaUnsafe<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the array.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedArray extends factory.arrayAlpha(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic arrayAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): ArrayNodeCustomizableSchemaAlpha<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tT,\n\t\ttrue,\n\t\tTCustomMetadata\n\t> {\n\t\treturn arraySchema(\n\t\t\tscoped<TScope, TName, Name>(this, name),\n\t\t\tallowedTypes,\n\t\t\ttrue,\n\t\t\ttrue,\n\t\t\toptions ?? {},\n\t\t) as unknown as ArrayNodeCustomizableSchemaAlpha<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\ttrue,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * {@link SchemaFactory.arrayRecursive} but with support for some alpha features.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\treturn this.arrayAlpha(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\toptions,\n\t\t) as unknown as ArrayNodeCustomizableSchemaUnsafe<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeRecordNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the record.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedRecord extends factory.recordAlpha(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic recordAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): RecordNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn recordSchema({\n\t\t\tidentifier: scoped<TScope, TName, Name>(this, name),\n\t\t\tinfo: allowedTypes,\n\t\t\tcustomizable: true,\n\t\t\timplicitlyConstructable: true,\n\t\t\tnodeOptions: options,\n\t\t});\n\t}\n\n\t/**\n\t * {@link SchemaFactoryBeta.(record:2)} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.record` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override recordRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\tconst RecordSchema = recordSchema({\n\t\t\tidentifier: scoped<TScope, TName, Name>(this, name),\n\t\t\tinfo: allowedTypes as T & ImplicitAllowedTypes,\n\t\t\tcustomizable: true,\n\t\t\t// Setting this to true seems to work ok currently, but not for other node kinds.\n\t\t\t// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.\n\t\t\timplicitlyConstructable: false,\n\t\t\tnodeOptions: options,\n\t\t});\n\n\t\treturn RecordSchema as TreeNodeSchemaClass<\n\t\t\t/* Name */ ScopedSchemaName<TScope, Name>,\n\t\t\t/* Kind */ NodeKind.Record,\n\t\t\t/* TNode */ TreeRecordNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>,\n\t\t\t/* TInsertable */ {\n\t\t\t\t// Ideally this would be\n\t\t\t\t// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t\t// but doing so breaks recursive types.\n\t\t\t\t// Instead we do a less nice version:\n\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t},\n\t\t\t/* ImplicitlyConstructable */ false,\n\t\t\t/* Info */ T,\n\t\t\t/* TConstructorExtra */ undefined,\n\t\t\t/* TCustomMetadata */ TCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaFactoryBeta.scopedFactory}\n\t */\n\tpublic scopedFactoryAlpha<\n\t\tconst T extends TName,\n\t\tTNameInner extends number | string = string,\n\t>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner> {\n\t\treturn new SchemaFactoryAlpha(scoped<TScope, TName, T>(this, name));\n\t}\n}\n"]}
+{"version":3,"file":"schemaFactoryAlpha.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryAlpha.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { RestrictiveStringRecord } from \"../../util/index.js\";\nimport {\n\ttype NodeKind,\n\ttype TreeNodeSchemaClass,\n\ttype ImplicitAllowedTypes,\n\ttype WithType,\n\tnormalizeAllowedTypes,\n\tisTreeNode,\n\tcreateSchemaUpgrade,\n} from \"../core/index.js\";\n// These imports prevent a large number of type references in the API reports from showing up as *_2.\n/* eslint-disable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */\nimport {\n\ttype FieldProps,\n\ttype FieldSchemaAlpha,\n\ttype FieldPropsAlpha,\n\tFieldKind,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype FieldSchema,\n\tgetDefaultProvider,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n} from \"../fieldSchema.js\";\nimport type { LeafSchema } from \"../leafNodeSchema.js\";\nimport {\n\ttype ArrayNodeCustomizableSchema,\n\ttype ArrayNodeCustomizableSchemaAlpha,\n\tarraySchema,\n\ttype MapNodeCustomizableSchema,\n\tmapSchema,\n\ttype ObjectNodeSchema,\n\ttype ObjectNodeSchemaWorkaround,\n\tobjectSchema,\n\ttype RecordNodeCustomizableSchema,\n\trecordSchema,\n} from \"../node-kinds/index.js\";\nimport type { SchemaType, SimpleObjectNodeSchema } from \"../simpleSchema.js\";\nimport type { SimpleLeafNodeSchema } from \"../simpleSchema.js\";\nimport { unhydratedFlexTreeFromInsertableNode } from \"../unhydratedFlexTreeFromInsertable.js\";\n\nimport {\n\tdefaultSchemaFactoryObjectOptions,\n\tscoped,\n\ttype NodeSchemaOptionsAlpha,\n\ttype ObjectSchemaOptionsAlpha,\n\ttype ScopedSchemaName,\n} from \"./schemaFactory.js\";\nimport { SchemaFactoryBeta } from \"./schemaFactoryBeta.js\";\nimport { schemaStatics } from \"./schemaStatics.js\";\nimport { TreeBeta } from \"./treeBeta.js\";\nimport type {\n\tArrayNodeCustomizableSchemaUnsafe,\n\tFieldSchemaAlphaUnsafe,\n\tInsertableObjectFromSchemaRecordAlphaUnsafe,\n\tMapNodeCustomizableSchemaUnsafe,\n\tSystem_Unsafe,\n\tTreeRecordNodeUnsafe,\n\tUnenforced,\n} from \"./typesUnsafe.js\";\n/* eslint-enable unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars, import-x/no-duplicates */\n\n/**\n * A provider for values in tree nodes.\n *\n * @remarks\n * This type represents two ways to provide node values:\n *\n * 1. **A value**: Provide any value directly (number, string, object, array, etc.). When a value is provided,\n * the data is copied for each use to ensure independence between instances. The value must be of an allowed type for the field.\n *\n * 2. **A generator function**: A function that returns a value. The function is called each time a default is needed,\n * allowing for dynamic defaults or explicit control over value creation. The return value must be of an allowed type for the field.\n *\n * Values should be preferred over generator functions when possible, as they are simpler and more efficient.\n * Generator functions should be used when the default value needs to be dynamic or when it is not possible to provide a value directly.\n *\n * @example\n * ```typescript\n * // Provide a value directly\n * factory.withDefault(factory.required(factory.string), \"default\")\n * factory.withDefault(factory.optional(Person), new Person({ name: \"Guest\" }))\n *\n * // Use a generator function\n * factory.withDefault(factory.required(factory.string), () => crypto.randomUUID())\n * factory.withDefault(factory.optional(Person), () => new Person({ name: \"Guest\" }))\n * ```\n *\n * @alpha @sealed\n */\nexport type NodeProvider<T> = T | (() => T);\n\n/**\n * Stateless APIs exposed via {@link SchemaFactoryBeta} as both instance properties and as statics.\n * @see {@link SchemaStatics} for why this is useful.\n * @system @sealed @alpha\n */\nexport interface SchemaStaticsAlpha {\n\t/**\n\t * Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors,\n\t * allowing them to be omitted when creating new nodes.\n\t *\n\t * @param fieldSchema - The field schema to add a default to (e.g., `factory.required(factory.string)` or `factory.optional(factory.number)`)\n\t * @param defaultValue - A {@link NodeProvider} specifying the default value.\n\t *\n\t * @example\n\t * ```typescript\n\t * const MySchema = factory.objectAlpha(\"MyObject\", {\n\t *     // Provide values directly\n\t *     name: factory.withDefault(factory.required(factory.string), \"untitled\"),\n\t *     count: factory.withDefault(factory.required(factory.number), 0),\n\t *     metadata: factory.withDefault(factory.optional(Metadata), new Metadata({ version: 1 })),\n\t *\n\t *     // Use generator functions for dynamic values\n\t *     timestamp: factory.withDefault(factory.required(factory.number), () => Date.now()),\n\t *     id: factory.withDefault(factory.required(factory.string), () => crypto.randomUUID()),\n\t * });\n\t *\n\t * const obj1 = new MySchema({}); // All defaults applied\n\t * const obj2 = new MySchema({ name: \"custom\" }); // name=\"custom\", other defaults applied\n\t * ```\n\t *\n\t * @privateRemarks\n\t * This function wraps an existing field schema and adds a default value provider to it.\n\t * The default value will be used when constructing nodes if the field is not explicitly provided or set to `undefined`.\n\t *\n\t * Defaults are evaluated eagerly during node construction, unlike identifier defaults which require context.\n\t */\n\treadonly withDefault: <\n\t\tKind extends FieldKind,\n\t\tTypes extends ImplicitAllowedTypes,\n\t\tTCustomMetadata = unknown,\n\t>(\n\t\tfieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,\n\t\tdefaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,\n\t) => FieldSchemaAlpha<\n\t\tKind,\n\t\tTypes,\n\t\tTCustomMetadata,\n\t\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n\t>;\n\t/**\n\t * Creates a field schema that is Optional in the view but behaves as Required in the stored schema\n\t * during the rollout period of an optional-field migration.\n\t *\n\t * @remarks\n\t * Use this to incrementally migrate a required field to optional without a coordinated deployment.\n\t * The migration path is:\n\t *\n\t * 1. Start with `sf.required(T)` — all clients require the field.\n\t * 2. Deploy `sf.stagedOptional(T)` — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing `undefined` is blocked at runtime.\n\t * 3. Deploy `sf.optional(T)` once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.\n\t *\n\t * Analogous to {@link SchemaStaticsBeta.staged} for allowed types, but for field optionality.\n\t *\n\t * @param t - The types allowed under the field.\n\t * @param props - Optional properties to associate with the field.\n\t *\n\t * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.\n\t * See {@link FieldSchemaMetadata.custom}.\n\t */\n\treadonly stagedOptional: <\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tt: T,\n\t\tprops?: Omit<\n\t\t\tFieldPropsAlpha<TCustomMetadata>,\n\t\t\t\"defaultProvider\" | \"stagedOptionalUpgrade\"\n\t\t>,\n\t) => FieldSchemaAlpha<\n\t\tFieldKind.Optional,\n\t\tT,\n\t\tTCustomMetadata,\n\t\tFieldPropsAlpha<TCustomMetadata>\n\t>;\n\n\t/**\n\t * {@link SchemaStaticsAlpha.withDefault} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of {@link SchemaStaticsAlpha.withDefault} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\twithDefaultRecursive: <\n\t\tKind extends FieldKind,\n\t\tTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tTCustomMetadata = unknown,\n\t>(\n\t\tfieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>,\n\t\tdefaultValue: Unenforced<\n\t\t\tNodeProvider<\n\t\t\t\tSystem_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<\n\t\t\t\t\tSystem_Unsafe.FieldSchemaUnsafe<Kind, Types>\n\t\t\t\t>\n\t\t\t>\n\t\t>,\n\t) => FieldSchemaAlphaUnsafe<\n\t\tKind,\n\t\tTypes,\n\t\tTCustomMetadata,\n\t\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n\t>;\n}\n\nconst withDefault = <\n\tKind extends FieldKind,\n\tTypes extends ImplicitAllowedTypes,\n\tTCustomMetadata = unknown,\n>(\n\tfieldSchema: FieldSchema<Kind, Types, TCustomMetadata>,\n\tdefaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>,\n): FieldSchemaAlpha<\n\tKind,\n\tTypes,\n\tTCustomMetadata,\n\tFieldPropsAlpha<TCustomMetadata> & { defaultProvider: DefaultProvider }\n> => {\n\tconst typedFieldSchema = fieldSchema as FieldSchemaAlpha<Kind, Types, TCustomMetadata>;\n\n\t// create the default provider function, it is called eagerly during node construction\n\tconst defaultProvider = getDefaultProvider(() => {\n\t\t// Resolve the value: if it's a function, call it; otherwise use it directly\n\t\tlet insertableValue =\n\t\t\ttypeof defaultValue === \"function\" ? (defaultValue as () => unknown)() : defaultValue;\n\n\t\t// If the value is an already-constructed TreeNode (e.g., from a generator function that\n\t\t// returns the same instance repeatedly), clone it to ensure each use gets a fresh instance.\n\t\t// This prevents multi-parenting errors.\n\t\tif (isTreeNode(insertableValue)) {\n\t\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\t\tinsertableValue = TreeBeta.clone(insertableValue as any);\n\t\t}\n\n\t\t// For optional fields with an undefined default, return an empty array (no value).\n\t\tif (insertableValue === undefined) {\n\t\t\treturn [];\n\t\t}\n\n\t\t// Convert the insertable value to an unhydrated flex tree.\n\t\t// For insertable data, this creates a fresh tree structure.\n\t\tconst allowedTypeSet = normalizeAllowedTypes(typedFieldSchema.allowedTypes).evaluateSet();\n\t\t// eslint-disable-next-line @typescript-eslint/no-explicit-any\n\t\treturn [unhydratedFlexTreeFromInsertableNode(insertableValue as any, allowedTypeSet)];\n\t});\n\n\t// create a new field schema with the default provider\n\tconst propsWithDefault = {\n\t\t...typedFieldSchema.props,\n\t\tdefaultProvider,\n\t};\n\n\treturn createFieldSchema(\n\t\ttypedFieldSchema.kind,\n\t\ttypedFieldSchema.allowedTypes,\n\t\tpropsWithDefault,\n\t);\n};\n\nconst stagedOptional = <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\" | \"stagedOptionalUpgrade\">,\n): FieldSchemaAlpha<\n\tFieldKind.Optional,\n\tT,\n\tTCustomMetadata,\n\tFieldPropsAlpha<TCustomMetadata>\n> => {\n\treturn createFieldSchema(FieldKind.Optional, t, {\n\t\tdefaultProvider: getDefaultProvider(() => []),\n\t\t...props,\n\t\tstagedOptionalUpgrade: createSchemaUpgrade(),\n\t});\n};\n\nconst schemaStaticsAlpha: SchemaStaticsAlpha = {\n\twithDefault,\n\n\twithDefaultRecursive: withDefault as SchemaStaticsAlpha[\"withDefaultRecursive\"],\n\n\tstagedOptional,\n};\n\n/**\n * {@link SchemaFactory} with additional alpha APIs.\n *\n * @alpha\n * @privateRemarks\n * When building schema, when `options` is not provided, `TCustomMetadata` is inferred as `unknown`.\n * If desired, this could be made to infer `undefined` instead by adding overloads for everything,\n * but currently it is not worth the maintenance overhead as there is no use case which this is known to be helpful for.\n */\nexport class SchemaFactoryAlpha<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> extends SchemaFactoryBeta<TScope, TName> {\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t * @param options - Additional options for the schema.\n\t */\n\tpublic objectAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): ObjectNodeSchemaWorkaround<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn objectSchema(scoped<TScope, TName, Name>(this, name), fields, true, {\n\t\t\t...defaultSchemaFactoryObjectOptions,\n\t\t\t...options,\n\t\t});\n\t}\n\n\t/**\n\t * {@inheritdoc SchemaFactory.objectRecursive}\n\t */\n\tpublic override objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\tfalse,\n\t\tT,\n\t\tnever,\n\t\tTCustomMetadata\n\t> &\n\t\tSimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &\n\t\t// We can't just use non generic `ObjectNodeSchema` here since \"Base constructors must all have the same return type\".\n\t\t// We also can't just use generic `ObjectNodeSchema` here and not `TreeNodeSchemaClass` since that doesn't work with unsafe recursive types.\n\t\t// ObjectNodeSchema<\n\t\t// \tScopedSchemaName<TScope, Name>,\n\t\t// \t//  T & RestrictiveStringRecord<ImplicitFieldSchema> would be nice to use here, but it breaks the recursive type self references.\n\t\t// \tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t// \tfalse,\n\t\t// \tTCustomMetadata\n\t\t// >\n\t\tPick<ObjectNodeSchema, \"fields\"> {\n\t\t// TODO: syntax highting is vs code is broken here. Don't trust it. Use the compiler instead.\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.objectAlpha(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\toptions,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> &\n\t\t\tObjectNodeSchema<\n\t\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\t\tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\t\tfalse,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t}\n\n\t/**\n\t * Alpha version of {@link SchemaFactory.objectRecursive} that supports field defaults via {@link SchemaStaticsAlpha.withDefaultRecursive}.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * Use this instead of {@link SchemaFactory.objectRecursive} when fields use {@link SchemaStaticsAlpha.withDefaultRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\tpublic objectRecursiveAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tt: T,\n\t\toptions?: ObjectSchemaOptionsAlpha<TCustomMetadata>,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,\n\t\tfalse,\n\t\tT,\n\t\tnever,\n\t\tTCustomMetadata\n\t> &\n\t\tSimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> &\n\t\tPick<ObjectNodeSchema, \"fields\"> {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.objectAlpha(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\toptions,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tSystem_Unsafe.TreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & InsertableObjectFromSchemaRecordAlphaUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tnever,\n\t\t\tTCustomMetadata\n\t\t> &\n\t\t\tObjectNodeSchema<\n\t\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\t\tRestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t\t\tfalse,\n\t\t\t\tTCustomMetadata\n\t\t\t>;\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaStatics.leaves}\n\t */\n\tpublic static override readonly leaves = schemaStatics.leaves;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optional}\n\t */\n\tpublic static override readonly optional = schemaStatics.optional;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.required}\n\t */\n\tpublic static override readonly required = schemaStatics.required;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optionalRecursive}\n\t */\n\tpublic static override readonly optionalRecursive = schemaStatics.optionalRecursive;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.requiredRecursive}\n\t */\n\tpublic static override readonly requiredRecursive = schemaStatics.requiredRecursive;\n\n\t/**\n\t * Like {@link SchemaFactory.identifier} but static and a factory function that can be provided {@link FieldProps}.\n\t */\n\tpublic static readonly identifier = schemaStatics.identifier;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.leaves}\n\t */\n\tpublic override readonly leaves = schemaStatics.leaves;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optional}\n\t */\n\tpublic override readonly optional = schemaStatics.optional;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.required}\n\t */\n\tpublic override readonly required = schemaStatics.required;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.optionalRecursive}\n\t */\n\tpublic override readonly optionalRecursive = schemaStatics.optionalRecursive;\n\n\t/**\n\t * {@inheritDoc SchemaStatics.requiredRecursive}\n\t */\n\tpublic override readonly requiredRecursive = schemaStatics.requiredRecursive;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic readonly withDefault = schemaStaticsAlpha.withDefault;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic static readonly withDefault = schemaStaticsAlpha.withDefault;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.withDefault}\n\t */\n\tpublic static readonly withDefaultRecursive = schemaStaticsAlpha.withDefaultRecursive;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.stagedOptional}\n\t */\n\tpublic readonly stagedOptional = schemaStaticsAlpha.stagedOptional;\n\n\t/**\n\t * {@inheritdoc SchemaStaticsAlpha.stagedOptional}\n\t */\n\tpublic static readonly stagedOptional = schemaStaticsAlpha.stagedOptional;\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeAlpha}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear as values in the map.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number, {\n\t * \tmetadata: { description: \"A map of numbers\" }\n\t * }) {}\n\t * ```\n\t */\n\tpublic mapAlpha<\n\t\tName extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn mapSchema(\n\t\t\tscoped<TScope, TName, Name>(this, name),\n\t\t\tallowedTypes,\n\t\t\ttrue,\n\t\t\ttrue,\n\t\t\toptions,\n\t\t);\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaFactory.objectRecursive}\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override mapRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\treturn this.mapAlpha(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\toptions,\n\t\t) as unknown as MapNodeCustomizableSchemaUnsafe<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the array.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedArray extends factory.arrayAlpha(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic arrayAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): ArrayNodeCustomizableSchemaAlpha<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tT,\n\t\ttrue,\n\t\tTCustomMetadata\n\t> {\n\t\treturn arraySchema(\n\t\t\tscoped<TScope, TName, Name>(this, name),\n\t\t\tallowedTypes,\n\t\t\ttrue,\n\t\t\ttrue,\n\t\t\toptions ?? {},\n\t\t) as unknown as ArrayNodeCustomizableSchemaAlpha<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\ttrue,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * {@link SchemaFactory.arrayRecursive} but with support for some alpha features.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\treturn this.arrayAlpha(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\toptions,\n\t\t) as unknown as ArrayNodeCustomizableSchemaUnsafe<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tT,\n\t\t\tTCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeRecordNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param allowedTypes - The types that may appear in the record.\n\t * @param options - Additional options for the schema.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedRecord extends factory.recordAlpha(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic recordAlpha<\n\t\tconst Name extends TName,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\toptions?: NodeSchemaOptionsAlpha<TCustomMetadata>,\n\t): RecordNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> {\n\t\treturn recordSchema({\n\t\t\tidentifier: scoped<TScope, TName, Name>(this, name),\n\t\t\tinfo: allowedTypes,\n\t\t\tcustomizable: true,\n\t\t\timplicitlyConstructable: true,\n\t\t\tnodeOptions: options,\n\t\t});\n\t}\n\n\t/**\n\t * {@link SchemaFactoryBeta.(record:2)} except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.record` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic override recordRecursive<\n\t\tName extends TName,\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>) {\n\t\tconst RecordSchema = recordSchema({\n\t\t\tidentifier: scoped<TScope, TName, Name>(this, name),\n\t\t\tinfo: allowedTypes as T & ImplicitAllowedTypes,\n\t\t\tcustomizable: true,\n\t\t\t// Setting this to true seems to work ok currently, but not for other node kinds.\n\t\t\t// Supporting this could be fragile and might break other future changes, so it's being kept as false for now.\n\t\t\timplicitlyConstructable: false,\n\t\t\tnodeOptions: options,\n\t\t});\n\n\t\treturn RecordSchema as TreeNodeSchemaClass<\n\t\t\t/* Name */ ScopedSchemaName<TScope, Name>,\n\t\t\t/* Kind */ NodeKind.Record,\n\t\t\t/* TNode */ TreeRecordNodeUnsafe<T> &\n\t\t\t\tWithType<ScopedSchemaName<TScope, Name>, NodeKind.Record>,\n\t\t\t/* TInsertable */ {\n\t\t\t\t// Ideally this would be\n\t\t\t\t// RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\t\t// but doing so breaks recursive types.\n\t\t\t\t// Instead we do a less nice version:\n\t\t\t\treadonly [P in string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;\n\t\t\t},\n\t\t\t/* ImplicitlyConstructable */ false,\n\t\t\t/* Info */ T,\n\t\t\t/* TConstructorExtra */ undefined,\n\t\t\t/* TCustomMetadata */ TCustomMetadata\n\t\t>;\n\t}\n\n\t/**\n\t * {@inheritDoc SchemaFactoryBeta.scopedFactory}\n\t */\n\tpublic scopedFactoryAlpha<\n\t\tconst T extends TName,\n\t\tTNameInner extends number | string = string,\n\t>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner> {\n\t\treturn new SchemaFactoryAlpha(scoped<TScope, TName, T>(this, name));\n\t}\n}\n"]}

package/lib/simple-tree/api/simpleTreeIndex.d.ts

@@ -11,7 +11,7 @@ import type { TreeView } from "./tree.js";
  * @remarks
  * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.
  * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).
- * @alpha
+ * @beta
  */
 export type TreeIndexKey = TreeLeafValue;
 /**
@@ -23,7 +23,7 @@ export type TreeIndexKey = TreeLeafValue;
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: (schema: TreeNodeSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): TreeIndex<TKey, TValue>;
 /**
@@ -36,7 +36,7 @@ export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: (schema: TSchema) => string | undefined, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): TreeIndex<TKey, TValue>;
 /**
@@ -48,7 +48,7 @@ export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema
  * @param getValue - given at least one {@link TreeNode}, returns an associated value
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  *
- * @alpha
+ * @beta
  */
 export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<TreeNode>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey): TreeIndex<TKey, TValue>;
 /**
@@ -61,7 +61,7 @@ export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema
  * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer
  * @param indexableSchema - a list of all the schema types that can be indexed
  *
- * @alpha
+ * @beta
  */
 export declare function createTreeIndex<TFieldSchema extends ImplicitFieldSchema, TKey extends TreeIndexKey, TValue, TSchema extends TreeNodeSchema>(view: TreeView<TFieldSchema>, indexer: Map<TreeNodeSchema, string>, getValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue, isKeyValid: (key: TreeIndexKey) => key is TKey, indexableSchema: readonly TSchema[]): TreeIndex<TKey, TValue>;
 //# sourceMappingURL=simpleTreeIndex.d.ts.map

package/lib/simple-tree/api/simpleTreeIndex.js

@@ -11,7 +11,7 @@ import { treeNodeApi } from "./treeNodeApi.js";
 /**
  * Creates a {@link TreeIndex} with a specified indexer.
  *
- * @alpha
+ * @beta
  */
 export function createTreeIndex(view, indexer, getValue, isKeyValid, indexableSchema) {
     const indexableSchemaMap = new Map();

package/lib/simple-tree/api/simpleTreeIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"simpleTreeIndex.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleTreeIndex.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,qCAAqC,CAAC;AAQ3D,OAAO,EACN,eAAe,EACf,WAAW,EAEX,UAAU,GAGV,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EACN,kBAAkB,GAKlB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAyG/C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAK9B,IAA4B,EAC5B,OAAuF,EACvF,QAEsE,EACtE,UAA8C,EAC9C,eAA2C;IAE3C,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC7D,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;QACnC,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE;YAC5B,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC;SACtE,CAAC,CAAC;IACJ,CAAC;SAAM,CAAC;QACP,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;YACvC,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QACrD,CAAC;IACF,CAAC;IAED,MAAM,aAAa,GAClB,eAAe,KAAK,SAAS;QAC5B,CAAC,CAAC,CAAC,gBAA0C,EAAE,EAAE;YAC/C,wEAAwE;YACxE,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACzD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;YACzC,CAAC;iBAAM,CAAC;gBACP,MAAM,WAAW,GAChB,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACzE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC/B,OAAO,oBAAoB,CAAO,KAAK,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;gBACnE,CAAC;YACF,CAAC;QACF,CAAC;QACF,CAAC,CAAC,CAAC,gBAA0C,EAAE,EAAE;YAC/C,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YACzD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,WAAW,GAChB,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACzE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC/B,OAAO,oBAAoB,CAAO,KAAK,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC;gBACnE,CAAC;YACF,CAAC;QACF,CAAC,CAAC;IAEL,MAAM,KAAK,GAAG,IAAI,eAAe,CAC/B,IAAiD,CAAC,QAAQ,CAAC,MAAM,EAClE,aAAa,EACb,CAAC,WAAW,EAAE,EAAE;QACf,MAAM,eAAe,GAAe,EAAE,CAAC;QACvC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACtC,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;YAClD,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC9B,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAClC,CAAC;QACF,CAAC;QAED,IAAI,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YACjC,OAAO,QAAQ,CAAC,eAAe,CAAC,CAAC;QAClC,CAAC;IACF,CAAC,EACD,CAAC,UAAsB,EAAE,EAAE;QAC1B,MAAM,UAAU,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAClD,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,OAAO,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;IACF,CAAC;IACD,+FAA+F;IAC/F,IAAI,CACJ,CAAC;IAEF,sFAAsF;IACtF,2CAA2C;IAC3C,OAAO,KAAgC,CAAC;AACzC,CAAC;AAED,SAAS,oBAAoB,CAC5B,QAAkB,EAClB,UAA8C;IAE9C,OAAO,CAAC,MAA+B,EAAE,EAAE;QAC1C,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC5B,MAAM,CAAC,SAAS,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC3B,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,SAAS,EAAE,CAAC;QAEnB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { fail } from \"@fluidframework/core-utils/internal\";\n\nimport type {\n\tAnchorNode,\n\tFieldKey,\n\tITreeSubscriptionCursor,\n\tTreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport {\n\tAnchorTreeIndex,\n\tisTreeValue,\n\ttype TreeIndexNodes,\n\thasElement,\n\ttype TreeIndex,\n\ttype KeyFinder,\n} from \"../../feature-libraries/index.js\";\nimport type { SchematizingSimpleTreeView } from \"../../shared-tree/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttreeNodeFromAnchor,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\ttype NodeFromSchema,\n\ttype TreeLeafValue,\n} from \"../core/index.js\";\nimport type { ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\n\nimport type { TreeView } from \"./tree.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\n\n/**\n * Value that may be used as keys in a {@link TreeIndex}.\n * @remarks\n * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.\n * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).\n * @alpha\n */\nexport type TreeIndexKey = TreeLeafValue;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TreeNodeSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @alpha\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @alpha\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @alpha\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: ((schema: TreeNodeSchema) => string | undefined) | Map<TreeNodeSchema, string>,\n\tgetValue:\n\t\t| ((nodes: TreeIndexNodes<TreeNode>) => TValue)\n\t\t| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema?: readonly TreeNodeSchema[],\n): TreeIndex<TKey, TValue> {\n\tconst indexableSchemaMap = new Map<string, TreeNodeSchema>();\n\tif (indexableSchema === undefined) {\n\t\twalkFieldSchema(view.schema, {\n\t\t\tnode: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),\n\t\t});\n\t} else {\n\t\tfor (const schemus of indexableSchema) {\n\t\t\tindexableSchemaMap.set(schemus.identifier, schemus);\n\t\t}\n\t}\n\n\tconst schemaIndexer =\n\t\tindexableSchema === undefined\n\t\t\t? (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\t// if indexable schema isn't provided, we check if the node is in schema\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus === undefined) {\n\t\t\t\t\t\tfail(0xb32 /* node is out of schema */);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus !== undefined) {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t};\n\n\tconst index = new AnchorTreeIndex<TKey, TValue>(\n\t\t(view as SchematizingSimpleTreeView<TFieldSchema>).checkout.forest,\n\t\tschemaIndexer,\n\t\t(anchorNodes) => {\n\t\t\tconst simpleTreeNodes: TreeNode[] = [];\n\t\t\tfor (const anchorNode of anchorNodes) {\n\t\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\t\tsimpleTreeNodes.push(simpleTree);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (hasElement(simpleTreeNodes)) {\n\t\t\t\treturn getValue(simpleTreeNodes);\n\t\t\t}\n\t\t},\n\t\t(anchorNode: AnchorNode) => {\n\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\treturn treeNodeApi.status(simpleTree);\n\t\t\t}\n\t\t},\n\t\t// simple tree indexes are shallow indexes, indicating so allows for a performance optimization\n\t\ttrue,\n\t);\n\n\t// all the type checking guarantees that we put nodes of the correct type in the index\n\t// but it's not captured in the type system\n\treturn index as TreeIndex<TKey, TValue>;\n}\n\nfunction makeGenericKeyFinder<TKey extends TreeIndexKey>(\n\tkeyField: FieldKey,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): KeyFinder<TKey> {\n\treturn (cursor: ITreeSubscriptionCursor) => {\n\t\tcursor.enterField(keyField);\n\t\tcursor.firstNode();\n\t\tconst value = cursor.value;\n\t\tcursor.exitNode();\n\t\tcursor.exitField();\n\n\t\tif (value === undefined) {\n\t\t\tfail(0xb33 /* a value for the key does not exist */);\n\t\t}\n\n\t\tif (!isKeyValid(value)) {\n\t\t\tfail(0xb34 /* the key is an unexpected type */);\n\t\t}\n\n\t\treturn value;\n\t};\n}\n"]}
+{"version":3,"file":"simpleTreeIndex.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleTreeIndex.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { fail } from \"@fluidframework/core-utils/internal\";\n\nimport type {\n\tAnchorNode,\n\tFieldKey,\n\tITreeSubscriptionCursor,\n\tTreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport {\n\tAnchorTreeIndex,\n\tisTreeValue,\n\ttype TreeIndexNodes,\n\thasElement,\n\ttype TreeIndex,\n\ttype KeyFinder,\n} from \"../../feature-libraries/index.js\";\nimport type { SchematizingSimpleTreeView } from \"../../shared-tree/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttreeNodeFromAnchor,\n\ttype TreeNode,\n\ttype TreeNodeSchema,\n\ttype NodeFromSchema,\n\ttype TreeLeafValue,\n} from \"../core/index.js\";\nimport type { ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\n\nimport type { TreeView } from \"./tree.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\n\n/**\n * Value that may be used as keys in a {@link TreeIndex}.\n * @remarks\n * This supports values which have value semantics and are compared by value, just like {@link TreeLeafValue}.\n * This allows using any tree value as a key (for example in an index tracking where those values occur in the tree).\n * @beta\n */\nexport type TreeIndexKey = TreeLeafValue;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @beta\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TreeNodeSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a function that takes in a {@link TreeNodeSchema} and returns the field name that all nodes of the given schema\n * should be keyed on, must be pure and functional\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @beta\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: (schema: TSchema) => string | undefined,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n *\n * @beta\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<TreeNode>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @param view - the view for the tree being indexed\n * @param indexer - a map from {@link TreeNodeSchema} to the field name that all nodes of the given schema\n * should be keyed on\n * @param getValue - given at least one {@link TreeNode}, returns an associated value\n * @param isKeyValid - function for verifying the validity of the key retrieved based on the information given by the indexer\n * @param indexableSchema - a list of all the schema types that can be indexed\n *\n * @beta\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n\tTSchema extends TreeNodeSchema,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: Map<TreeNodeSchema, string>,\n\tgetValue: (nodes: TreeIndexNodes<NodeFromSchema<TSchema>>) => TValue,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema: readonly TSchema[],\n): TreeIndex<TKey, TValue>;\n\n/**\n * Creates a {@link TreeIndex} with a specified indexer.\n *\n * @beta\n */\nexport function createTreeIndex<\n\tTFieldSchema extends ImplicitFieldSchema,\n\tTKey extends TreeIndexKey,\n\tTValue,\n>(\n\tview: TreeView<TFieldSchema>,\n\tindexer: ((schema: TreeNodeSchema) => string | undefined) | Map<TreeNodeSchema, string>,\n\tgetValue:\n\t\t| ((nodes: TreeIndexNodes<TreeNode>) => TValue)\n\t\t| ((nodes: TreeIndexNodes<NodeFromSchema<TreeNodeSchema>>) => TValue),\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n\tindexableSchema?: readonly TreeNodeSchema[],\n): TreeIndex<TKey, TValue> {\n\tconst indexableSchemaMap = new Map<string, TreeNodeSchema>();\n\tif (indexableSchema === undefined) {\n\t\twalkFieldSchema(view.schema, {\n\t\t\tnode: (schemus) => indexableSchemaMap.set(schemus.identifier, schemus),\n\t\t});\n\t} else {\n\t\tfor (const schemus of indexableSchema) {\n\t\t\tindexableSchemaMap.set(schemus.identifier, schemus);\n\t\t}\n\t}\n\n\tconst schemaIndexer =\n\t\tindexableSchema === undefined\n\t\t\t? (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\t// if indexable schema isn't provided, we check if the node is in schema\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus === undefined) {\n\t\t\t\t\t\tfail(0xb32 /* node is out of schema */);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t: (schemaIdentifier: TreeNodeSchemaIdentifier) => {\n\t\t\t\t\tconst schemus = indexableSchemaMap.get(schemaIdentifier);\n\t\t\t\t\tif (schemus !== undefined) {\n\t\t\t\t\t\tconst keyLocation =\n\t\t\t\t\t\t\ttypeof indexer === \"function\" ? indexer(schemus) : indexer.get(schemus);\n\t\t\t\t\t\tif (keyLocation !== undefined) {\n\t\t\t\t\t\t\treturn makeGenericKeyFinder<TKey>(brand(keyLocation), isKeyValid);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t};\n\n\tconst index = new AnchorTreeIndex<TKey, TValue>(\n\t\t(view as SchematizingSimpleTreeView<TFieldSchema>).checkout.forest,\n\t\tschemaIndexer,\n\t\t(anchorNodes) => {\n\t\t\tconst simpleTreeNodes: TreeNode[] = [];\n\t\t\tfor (const anchorNode of anchorNodes) {\n\t\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\t\tsimpleTreeNodes.push(simpleTree);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (hasElement(simpleTreeNodes)) {\n\t\t\t\treturn getValue(simpleTreeNodes);\n\t\t\t}\n\t\t},\n\t\t(anchorNode: AnchorNode) => {\n\t\t\tconst simpleTree = treeNodeFromAnchor(anchorNode);\n\t\t\tif (!isTreeValue(simpleTree)) {\n\t\t\t\treturn treeNodeApi.status(simpleTree);\n\t\t\t}\n\t\t},\n\t\t// simple tree indexes are shallow indexes, indicating so allows for a performance optimization\n\t\ttrue,\n\t);\n\n\t// all the type checking guarantees that we put nodes of the correct type in the index\n\t// but it's not captured in the type system\n\treturn index as TreeIndex<TKey, TValue>;\n}\n\nfunction makeGenericKeyFinder<TKey extends TreeIndexKey>(\n\tkeyField: FieldKey,\n\tisKeyValid: (key: TreeIndexKey) => key is TKey,\n): KeyFinder<TKey> {\n\treturn (cursor: ITreeSubscriptionCursor) => {\n\t\tcursor.enterField(keyField);\n\t\tcursor.firstNode();\n\t\tconst value = cursor.value;\n\t\tcursor.exitNode();\n\t\tcursor.exitField();\n\n\t\tif (value === undefined) {\n\t\t\tfail(0xb33 /* a value for the key does not exist */);\n\t\t}\n\n\t\tif (!isKeyValid(value)) {\n\t\t\tfail(0xb34 /* the key is an unexpected type */);\n\t\t}\n\n\t\treturn value;\n\t};\n}\n"]}

package/lib/simple-tree/api/storedSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storedSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAE5F,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAKnF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,uBAAuB,EAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,GAChD,cAAc,CAOhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAQlD"}
+{"version":3,"file":"storedSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8CAA8C,CAAC;AAE5F,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAKnF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,mBAAmB,EAC3B,mBAAmB,EAAE,uBAAuB,EAC5C,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,GAChD,cAAc,CAUhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAQlD"}

package/lib/simple-tree/api/storedSchema.js

@@ -41,7 +41,10 @@ import { SchemaCompatibilityTester } from "./schemaCompatibilityTester.js";
  * @alpha
  */
 export function extractPersistedSchema(schema, minVersionForCollab, includeStaged) {
-    const stored = toStoredSchema(schema, { includeStaged });
+    const stored = toStoredSchema(schema, {
+        includeStaged,
+        includeStagedOptional: includeStaged,
+    });
     const codec = schemaCodecBuilder.build({
         minVersionForCollab,
         jsonValidator: FormatValidatorNoOp,

package/lib/simple-tree/api/storedSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,EAAE,oBAAoB,EAA4B,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAA2B,EAC3B,mBAA4C,EAC5C,aAAkD;IAElD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC;QACtC,mBAAmB;QACnB,aAAa,EAAE,mBAAmB;KAClC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAmB,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,MAAM,WAAW,GAAG,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,0BAA0B,CAAC;QAC7C,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\n\nimport { FormatValidatorNoOp, type ICodecOptions } from \"../../codec/index.js\";\nimport { schemaCodecBuilder } from \"../../feature-libraries/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { SchemaUpgrade } from \"../core/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\n\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.\n *\n * @param schema - The schema to dump.\n * @param minVersionForCollab - The oldest client version which can read the schema: impacts the format used.\n * @param includeStaged - filter for selecting which staged allowed types to include in the output.\n *\n * @remarks\n * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.\n * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.\n *\n * This only includes the \"persisted\" subset of schema information, which means the portion which gets included in documents.\n * It thus uses \"persisted\" keys, see {@link FieldProps.key}.\n *\n * If two schema have identical \"persisted\" schema, then they are considered {@link SchemaCompatibilityStatus.isEquivalent|equivalent}.\n *\n * See also {@link comparePersistedSchema}.\n *\n * @example\n * An application could use this API to generate a `schema.json` file when it first releases,\n * then test that the schema is sill compatible with documents from that version with a test like :\n * ```typescript\n * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require(\"./schema.json\"));\n * ```\n *\n * @privateRemarks\n * This currently uses the schema summary format, but that could be changed to something more human readable (particularly if the encoded format becomes less human readable).\n * This intentionally does not leak the format types in the API.\n *\n * Public API surface uses \"persisted\" terminology while internally we use \"stored\".\n * @alpha\n */\nexport function extractPersistedSchema(\n\tschema: ImplicitFieldSchema,\n\tminVersionForCollab: MinimumVersionForCollab,\n\tincludeStaged: (upgrade: SchemaUpgrade) => boolean,\n): JsonCompatible {\n\tconst stored = toStoredSchema(schema, { includeStaged });\n\tconst codec = schemaCodecBuilder.build({\n\t\tminVersionForCollab,\n\t\tjsonValidator: FormatValidatorNoOp,\n\t});\n\treturn codec.encode(stored) as JsonCompatible;\n}\n\n/**\n * Compares two schema extracted using {@link extractPersistedSchema}.\n * Reports the same compatibility that {@link TreeView.compatibility} would report if\n * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.\n *\n * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.\n * @param view - Schema which would be used to view persisted content.\n * @param options - {@link ICodecOptions} used when parsing the provided schema.\n * @param canInitialize - Passed through to the return value unchanged and otherwise unused.\n * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.\n *\n * @remarks\n * This uses the persisted formats for schema, meaning it only includes data which impacts compatibility.\n * It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.\n *\n * @example\n * An application could use {@link extractPersistedSchema} to generate a `schema.json` file for various versions of the app,\n * then test that documents using those schema can be upgraded to work with the current schema using a test like:\n * ```typescript\n * assert(\n * \tcomparePersistedSchema(\n * \t\trequire(\"./schema.json\"),\n * \t\tMySchema,\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: ImplicitFieldSchema,\n\toptions: ICodecOptions,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\tconst schemaCodec = schemaCodecBuilder.buildDecoder(options);\n\tconst stored = schemaCodec.decode(persisted);\n\tconst config = new TreeViewConfigurationAlpha({\n\t\tschema: normalizeFieldSchema(view),\n\t});\n\tconst viewSchema = new SchemaCompatibilityTester(config);\n\treturn viewSchema.checkCompatibility(stored);\n}\n"]}
+{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAGtE,OAAO,EAAE,oBAAoB,EAA4B,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,sBAAsB,CACrC,MAA2B,EAC3B,mBAA4C,EAC5C,aAAkD;IAElD,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,EAAE;QACrC,aAAa;QACb,qBAAqB,EAAE,aAAa;KACpC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC;QACtC,mBAAmB;QACnB,aAAa,EAAE,mBAAmB;KAClC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAmB,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,MAAM,WAAW,GAAG,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,0BAA0B,CAAC;QAC7C,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,yBAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { MinimumVersionForCollab } from \"@fluidframework/runtime-definitions/internal\";\n\nimport { FormatValidatorNoOp, type ICodecOptions } from \"../../codec/index.js\";\nimport { schemaCodecBuilder } from \"../../feature-libraries/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { SchemaUpgrade } from \"../core/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\n\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\nimport { SchemaCompatibilityTester } from \"./schemaCompatibilityTester.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.\n *\n * @param schema - The schema to dump.\n * @param minVersionForCollab - The oldest client version which can read the schema: impacts the format used.\n * @param includeStaged - filter for selecting which staged allowed types to include in the output.\n *\n * @remarks\n * This can be used to help inspect schema for debugging, and to save a snapshot of schema to help detect and review changes to an applications schema.\n * This format is also compatible with {@link ViewContent.schema}, {@link comparePersistedSchema} and {@link persistedToSimpleSchema}.\n *\n * This only includes the \"persisted\" subset of schema information, which means the portion which gets included in documents.\n * It thus uses \"persisted\" keys, see {@link FieldProps.key}.\n *\n * If two schema have identical \"persisted\" schema, then they are considered {@link SchemaCompatibilityStatus.isEquivalent|equivalent}.\n *\n * See also {@link comparePersistedSchema}.\n *\n * @example\n * An application could use this API to generate a `schema.json` file when it first releases,\n * then test that the schema is sill compatible with documents from that version with a test like :\n * ```typescript\n * assert.deepEqual(extractPersistedSchema(MySchema, FluidClientVersion.v2_0), require(\"./schema.json\"));\n * ```\n *\n * @privateRemarks\n * This currently uses the schema summary format, but that could be changed to something more human readable (particularly if the encoded format becomes less human readable).\n * This intentionally does not leak the format types in the API.\n *\n * Public API surface uses \"persisted\" terminology while internally we use \"stored\".\n * @alpha\n */\nexport function extractPersistedSchema(\n\tschema: ImplicitFieldSchema,\n\tminVersionForCollab: MinimumVersionForCollab,\n\tincludeStaged: (upgrade: SchemaUpgrade) => boolean,\n): JsonCompatible {\n\tconst stored = toStoredSchema(schema, {\n\t\tincludeStaged,\n\t\tincludeStagedOptional: includeStaged,\n\t});\n\tconst codec = schemaCodecBuilder.build({\n\t\tminVersionForCollab,\n\t\tjsonValidator: FormatValidatorNoOp,\n\t});\n\treturn codec.encode(stored) as JsonCompatible;\n}\n\n/**\n * Compares two schema extracted using {@link extractPersistedSchema}.\n * Reports the same compatibility that {@link TreeView.compatibility} would report if\n * opening a document that used the `persisted` schema and provided `view` to {@link ViewableTree.viewWith}.\n *\n * @param persisted - Schema persisted for a document. Typically persisted alongside the data and assumed to describe that data.\n * @param view - Schema which would be used to view persisted content.\n * @param options - {@link ICodecOptions} used when parsing the provided schema.\n * @param canInitialize - Passed through to the return value unchanged and otherwise unused.\n * @returns The {@link SchemaCompatibilityStatus} a {@link TreeView} would report for this combination of schema.\n *\n * @remarks\n * This uses the persisted formats for schema, meaning it only includes data which impacts compatibility.\n * It also uses the persisted format so that this API can be used in tests to compare against saved schema from previous versions of the application.\n *\n * @example\n * An application could use {@link extractPersistedSchema} to generate a `schema.json` file for various versions of the app,\n * then test that documents using those schema can be upgraded to work with the current schema using a test like:\n * ```typescript\n * assert(\n * \tcomparePersistedSchema(\n * \t\trequire(\"./schema.json\"),\n * \t\tMySchema,\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: ImplicitFieldSchema,\n\toptions: ICodecOptions,\n): Omit<SchemaCompatibilityStatus, \"canInitialize\"> {\n\tconst schemaCodec = schemaCodecBuilder.buildDecoder(options);\n\tconst stored = schemaCodec.decode(persisted);\n\tconst config = new TreeViewConfigurationAlpha({\n\t\tschema: normalizeFieldSchema(view),\n\t});\n\tconst viewSchema = new SchemaCompatibilityTester(config);\n\treturn viewSchema.checkCompatibility(stored);\n}\n"]}

package/lib/simple-tree/api/treeAlpha.d.ts

@@ -3,9 +3,10 @@
  * Licensed under the MIT License.
  */
 import type { NodeKind, TreeNode, WithType } from "../core/index.js";
+import type { TreeChangeEventsBeta } from "./treeBeta.js";
 import type { TreeChangeEvents } from "./treeChangeEvents.js";
-export type { ArrayNodeDeltaOp, ArrayNodeInsertOp, ArrayNodeRemoveOp, ArrayNodeRetainOp, } from "./treeNodeApi.js";
-import type { ArrayNodeDeltaOp } from "./treeNodeApi.js";
+import type { ArrayNodeDeltaOp, ArrayNodeTreeChangedDeltaOp } from "./treeNodeApi.js";
+export type { ArrayNodeDeltaOp, ArrayNodeInsertOp, ArrayNodeRemoveOp, ArrayNodeRetainOp, ArrayNodeTreeChangedDeltaOp, ArrayNodeTreeChangedRetainOp, } from "./treeNodeApi.js";
 /**
  * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an object, map, or record node.
  * @sealed @alpha
@@ -21,25 +22,45 @@ export interface NodeChangedDataProperties<TNode extends TreeNode = TreeNode> {
     readonly changedProperties: ReadonlySet<TNode extends WithType<string, NodeKind.Object, infer TInfo> ? string & keyof TInfo : string>;
 }
 /**
- * Data included for {@link TreeChangeEventsAlpha.nodeChanged} when the node is an array node.
+ * Data carried by the {@link TreeChangeEventsAlpha.nodeChanged} event for array nodes.
  * @sealed @alpha
  */
 export interface NodeChangedDataDelta {
     /**
      * The sequential operations describing what changed in the array node.
      * @remarks
-     * The value may be `undefined` in two cases:
-     * - The node was created locally and has not yet been inserted into a document tree (a known
-     * temporary limitation, tracked in AB#63261).
-     * - The document was updated in a way that required multiple internal change passes in a single
-     * operation (for example, a data change combined with a schema upgrade).
+     * The value may be `undefined` when the document was updated in a way that required multiple
+     * internal change passes in a single operation (for example, a data change combined with a
+     * schema upgrade).
      *
      * See {@link ArrayNodeDeltaOp} for op semantics.
      */
     readonly delta: readonly ArrayNodeDeltaOp[] | undefined;
 }
 /**
- * The data passed to {@link TreeChangeEventsAlpha.nodeChanged}.
+ * Data carried by the {@link TreeChangeEventsAlpha.treeChanged} event for array nodes.
+ * @remarks
+ * Extends {@link NodeChangedDataDelta}: the retain ops in the delta additionally carry a
+ * {@link ArrayNodeTreeChangedRetainOp.subtreeChanged} flag indicating whether any descendant
+ * of the retained element changed.
+ * @sealed @alpha
+ */
+export interface NodeChangedDataTreeDelta {
+    /**
+     * The sequential operations describing what changed in the array node,
+     * including subtree-change information on retain ops.
+     * @remarks
+     * The value may be `undefined` when the document was updated in a way that required multiple
+     * internal change passes in a single operation (for example, a data change combined with a
+     * schema upgrade).
+     *
+     * See {@link ArrayNodeTreeChangedDeltaOp} for op semantics.
+     */
+    readonly delta: readonly ArrayNodeTreeChangedDeltaOp[] | undefined;
+}
+/**
+ * The data passed to {@link TreeChangeEventsAlpha.nodeChanged} and, for array nodes,
+ * to {@link TreeChangeEventsAlpha.treeChanged}.
  * @remarks
  * - For array nodes: {@link NodeChangedDataDelta} (includes a {@link NodeChangedDataDelta.delta | delta} payload).
  * - For object, map, and record nodes: {@link NodeChangedDataProperties} (includes {@link NodeChangedDataProperties.changedProperties | changedProperties}).
@@ -48,22 +69,58 @@ export interface NodeChangedDataDelta {
  */
 export type NodeChangedDataAlpha<TNode extends TreeNode = TreeNode> = TNode extends WithType<string, NodeKind.Array> ? NodeChangedDataDelta : TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record> ? NodeChangedDataProperties<TNode> : NodeChangedDataProperties<TNode> | NodeChangedDataDelta;
 /**
- * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event.
+ * Extension of {@link TreeChangeEvents} with a richer `nodeChanged` event and a
+ * delta-carrying `treeChanged` event for array nodes.
  * @remarks
  * Provides a `nodeChanged` event that includes a delta payload for array nodes and
  * requires `changedProperties` for object, map, and record nodes.
+ * Also provides a `treeChanged` event that, for array nodes, carries a {@link NodeChangedDataDelta}
+ * payload describing both shallow and deep changes.
+ * For non-array nodes, the `treeChanged` signature is the same as the base event.
+ *
  * Use via `TreeAlpha.on`.
  * @sealed @alpha
  */
 export interface TreeChangeEventsAlpha<TNode extends TreeNode = TreeNode> extends TreeChangeEvents {
     /**
-     * Like `TreeChangeEventsBeta.nodeChanged`, but for array nodes the event data includes
-     * a {@link NodeChangedDataDelta.delta | delta} payload describing the changes as a sequence
-     * of {@link ArrayNodeDeltaOp} values.
+     * Emitted when a shallow change occurs on this node, i.e., when the node's direct children change.
      *
      * @remarks
+     * For array nodes: the event data includes a {@link NodeChangedDataDelta.delta | delta} payload
+     * as a sequence of {@link ArrayNodeDeltaOp} values. Does not fire for deep changes (e.g. a
+     * property of an array element changed without any shallow array change). Subscribe to
+     * {@link TreeChangeEventsAlpha.treeChanged} on the array to receive a delta for those cases as well.
+     *
+     * For object, map, and record nodes: the event data includes
+     * {@link NodeChangedDataProperties.changedProperties | changedProperties}.
+     * @privateRemarks
      * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
      */
     nodeChanged: (data: NodeChangedDataAlpha<TNode>) => void;
+    /**
+     * Emitted when something in the subtree rooted at this node changes.
+     *
+     * @remarks
+     * For array nodes: emitted when any change occurred within the array, including both
+     * shallow changes (insert, remove, move) and deep changes (e.g. a property of an element
+     * changed). The event data carries a {@link NodeChangedDataTreeDelta.delta | delta} payload
+     * describing what changed. The delta uses {@link ArrayNodeTreeChangedRetainOp.subtreeChanged}
+     * to flag elements that have deep changes, without describing the details of those deep changes.
+     * To inspect deep changes, subscribe to `nodeChanged` or `treeChanged` on the individual
+     * element nodes.
+     *
+     * When this array is nested inside another array, the outer array's `treeChanged` still
+     * fires with a delta, but that delta only shows `subtreeChanged: true` for the element
+     * position containing this inner array — it does not include the inner array's detailed
+     * insert/remove/retain ops. To receive those detailed ops, subscribe to `treeChanged`
+     * directly on the inner array.
+     * Ancestor non-array nodes still receive the base (no-payload) `treeChanged` via normal
+     * subtree propagation.
+     *
+     * For non-array nodes: same as the base {@link TreeChangeEvents.treeChanged}.
+     * @privateRemarks
+     * This defines a property which is a function instead of using the method syntax to avoid function bi-variance issues with the input data to the callback.
+     */
+    treeChanged: TNode extends WithType<string, NodeKind.Array> ? (data: NodeChangedDataTreeDelta) => void : TreeChangeEventsBeta<TNode>["treeChanged"];
 }
 //# sourceMappingURL=treeAlpha.d.ts.map

package/lib/simple-tree/api/treeAlpha.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeAlpha.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeAlpha.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,yBAAyB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAC3E;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAEtC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,IACjE,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GAC3C,oBAAoB,GACpB,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC/E,yBAAyB,CAAC,KAAK,CAAC,GAChC,yBAAyB,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACvE,SAAQ,gBAAgB;IACxB;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACzD"}
+{"version":3,"file":"treeAlpha.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeAlpha.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AACtF,YAAY,EACX,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,2BAA2B,EAC3B,4BAA4B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B;;;GAGG;AACH,MAAM,WAAW,yBAAyB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAC3E;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAEtC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC;CACxD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,CAAC;CACnE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,IACjE,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GAC3C,oBAAoB,GACpB,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC/E,yBAAyB,CAAC,KAAK,CAAC,GAChC,yBAAyB,CAAC,KAAK,CAAC,GAAG,oBAAoB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACvE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,WAAW,EAAE,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,GACxD,CAAC,IAAI,EAAE,wBAAwB,KAAK,IAAI,GACxC,oBAAoB,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC;CAC9C"}