@fluidframework/tree 2.52.0 → 2.53.0-350190

package/dist/simple-tree/api/schemaFactoryRecursive.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaFactoryRecursive.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryRecursive.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAYH,sDAK2B;AAI3B,SAAgB,uBAAuB,CAKtC,IAAU,EACV,YAAmB,EACnB,KAAmC;IAEnC,kJAAkJ;IAClJ,OAAO,IAAA,kCAAiB,EACvB,IAAI,EACJ,YAA4C,EAC5C,KAAK,CACmD,CAAC;AAC3D,CAAC;AAfD,0DAeC;AAkOD;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CAAI,CAAK,IAAS,CAAC;AAA9C,kCAA8C","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 type {\n\tNodeKind,\n\tTreeNodeSchema,\n\tWithType,\n\tTreeNode,\n\tImplicitAllowedTypes,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n} from \"../core/index.js\";\nimport type { InsertableObjectFromSchemaRecord } from \"../node-kinds/index.js\";\nimport {\n\ttype FieldKind,\n\ttype FieldProps,\n\tcreateFieldSchema,\n\ttype ImplicitFieldSchema,\n} from \"../fieldSchema.js\";\n\nimport type { FieldSchemaAlphaUnsafe, System_Unsafe } from \"./typesUnsafe.js\";\n\nexport function createFieldSchemaUnsafe<\n\tKind extends FieldKind,\n\tTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tTCustomMetadata = unknown,\n>(\n\tkind: Kind,\n\tallowedTypes: Types,\n\tprops?: FieldProps<TCustomMetadata>,\n): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {\n\t// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe\n\treturn createFieldSchema(\n\t\tkind,\n\t\tallowedTypes as ImplicitAllowedTypes & Types,\n\t\tprops,\n\t) as FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;\n}\n\n/**\n * Compile time check for validity of a recursive schema.\n * This type also serves as a central location for documenting the requirements and issues related to recursive schema.\n *\n * @example\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => Test]) {}\n * {\n *     type _check = ValidateRecursiveSchema<typeof Test>;\n * }\n * ```\n * @remarks\n * In this context recursive schema are defined as all {@link FieldSchema} and {@link TreeNodeSchema} schema which are part of a cycle such that walking down through each {@link TreeNodeSchemaCore.childTypes} the given starting schema can be reached again.\n * Schema referencing the recursive schema and schema they reference that are not part of a cycle are not considered recursive.\n *\n * TypeScript puts a lot of limitations on the typing of recursive schema.\n * To help avoid running into these limitations and thus getting schema that do not type check (or only type checks sometimes!),\n * {@link SchemaFactory} provides APIs (postfixed with `Recursive`) for writing recursive schema.\n * These APIs when combined with the patterns documented below should ensure that the schema provide robust type checking.\n * These special patterns (other than {@link LazyItem} forward references which are not recursion specific)\n * are not required for correct runtime behavior: they exist entirely to mitigate TypeScript type checking limitations and bugs.\n * Ideally TypeScript's type checker would be able to handle all of these cases and more, removing the need for recursive type specific guidance, rules and APIs.\n * Currently however there are open issues preventing this:\n * {@link https://github.com/microsoft/TypeScript/issues/59550 | 1},\n * {@link https://github.com/microsoft/TypeScript/issues/55832 | 2},\n * {@link https://github.com/microsoft/TypeScript/issues/55758 | 3}.\n * Note that the proposed resolution to some of these issues is for the compiler to error rather than allow the case,\n * so even if these are all resolved the recursive type workarounds may still be needed.\n *\n * # Patterns\n *\n * Below are patterns for how to use recursive schema.\n *\n * ## General Patterns\n *\n * When defining a recursive {@link TreeNodeSchema}, use the `*Recursive` {@link SchemaFactory} methods.\n * The returned class should be used as the base class for the recursive schema, which should then be passed to {@link ValidateRecursiveSchema}.\n *\n * Using {@link ValidateRecursiveSchema} will provide compile error for some of the cases of malformed schema.\n * This can be used to help mitigate the issue that recursive schema definitions are {@link Unenforced}.\n * If an issue is encountered where a mistake in a recursive schema is made which produces an invalid schema but is not rejected by this checker,\n * it should be considered a bug and this should be updated to handle that case (or have a disclaimer added to these docs that it misses that case).\n *\n * The non-recursive versions of the schema building methods will run into several issues when used recursively.\n * Consider the following example:\n *\n * ```typescript\n * const Test = sf.array(Test); // Bad\n * ```\n *\n * This has several issues:\n *\n * 1. It is a structurally named schema.\n * Structurally named schema derive their name from the names of their child types, which is not possible when the type is recursive since its name would include itself.\n * Instead a name must be explicitly provided.\n *\n * 2. The schema accesses itself before it's defined.\n * This would be a runtime error if the TypeScript compiler allowed it.\n * This can be fixed by wrapping the type in a function, which also requires explicitly listing the allowed types in an array (`[() => Test]`).\n *\n * 3. TypeScript fails to infer the recursive type and falls back to `any` with this warning or error (depending on the compiler configuration):\n * `'Test' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.ts(7022)`.\n * This issue is what the specialized recursive schema building methods fix.\n * This fix comes at a cost: to make the recursive cases work, the `extends` clauses had to be removed.\n * This means that mistakes declaring recursive schema often don't give compile errors in the schema.\n * Additionally support for implicit construction had to be disabled.\n * This means that new nested {@link Unhydrated} nodes can not be created like `new Test([[]])`.\n * Instead the nested nodes must be created explicitly using the construction like`new Test([new Test([])])`.\n *\n * 4. It is using \"POJO\" mode since it's not explicitly declaring a new class.\n * This means that the generated d.ts files for the schema replace recursive references with `any`, breaking use of recursive schema across compilation boundaries.\n * This is fixed by explicitly creating a class which extends the returned schema.\n *\n * All together, the fixed version looks like:\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => Test]) {} // Good\n * ```\n *\n * Be very careful when declaring recursive schema.\n * Due to the removed extends clauses, subtle mistakes will compile just fine but cause strange errors when the schema is used.\n *\n * For example if a reference to a schema is malformed (in this case boxed inside an object):\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * ```\n * This schema will still compile, and some (but not all) usages of it may look like they work correctly while other usages will produce generally unintelligible compile errors.\n * This issue can be partially mitigated using {@link ValidateRecursiveSchema}:\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * {\n *     type _check = ValidateRecursiveSchema<typeof Test>; // Reports compile error due to invalid schema above.\n * }\n * ```\n *\n * If your TypeScript configuration objects to this patten due to the unused local, you can use {@link allowUnused} to suppress the error:\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * allowUnused<ValidateRecursiveSchema<typeof Test>>(); // Reports compile error due to invalid schema above.\n * ```\n *\n * ## Object Schema\n *\n * When defining fields, if the fields is part of the recursive cycle, use the `*Recursive` {@link SchemaFactory} methods for defining the {@link FieldSchema}.\n *\n * ## Array Schema\n *\n * See {@link FixRecursiveArraySchema} for array specific details.\n *\n * @privateRemarks\n * There are probably mistakes this misses: it's hard to guess all the wrong things people will accidentally do and defend against them.\n * Hopefully over time this can grow toward being robust, at least for common mistakes.\n *\n * This check duplicates logic that ideally would be entirely decided by the actual schema building methods.\n * Therefore changes to those methods may require updating `ValidateRecursiveSchema`.\n *\n * TODO: this currently does not reject `any`, but ideally should.\n * @public\n */\nexport type ValidateRecursiveSchema<\n\t// Recursive types should always be using TreeNodeSchemaClass (not TreeNodeSchemaNonClass) as thats part of the requirements for the type to work across compilation boundaries correctly.\n\tT extends ValidateRecursiveSchemaTemplate<T>,\n> = true;\n\n/**\n * Validation logic used by {@link ValidateRecursiveSchema}.\n * @system @public\n */\nexport type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchema> = TreeNodeSchema<\n\t// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).\n\tstring,\n\t// NodeKind: These are the NodeKinds which currently can be used recursively.\n\tNodeKind.Array | NodeKind.Map | NodeKind.Object | NodeKind.Record,\n\t// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.\n\tTreeNode & WithType<T[\"identifier\"], T[\"kind\"]>,\n\t// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.\n\t// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.\n\t{\n\t\t[NodeKind.Object]: T[\"info\"] extends RestrictiveStringRecord<ImplicitFieldSchema>\n\t\t\t? InsertableObjectFromSchemaRecord<T[\"info\"]>\n\t\t\t: unknown;\n\t\t[NodeKind.Array]: T[\"info\"] extends ImplicitAllowedTypes\n\t\t\t? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T[\"info\"]>>\n\t\t\t: unknown;\n\t\t[NodeKind.Map]: T[\"info\"] extends ImplicitAllowedTypes\n\t\t\t? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T[\"info\"]>]>\n\t\t\t: unknown;\n\t\t[NodeKind.Record]: {\n\t\t\treadonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypes<T>;\n\t\t};\n\t\t[NodeKind.Leaf]: unknown;\n\t}[T[\"kind\"]],\n\t// ImplicitlyConstructable: recursive types are currently not implicitly constructable.\n\tfalse,\n\t// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.\n\t{\n\t\t[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;\n\t\t[NodeKind.Array]: ImplicitAllowedTypes;\n\t\t[NodeKind.Map]: ImplicitAllowedTypes;\n\t\t[NodeKind.Record]: ImplicitAllowedTypes;\n\t\t[NodeKind.Leaf]: unknown;\n\t}[T[\"kind\"]]\n>;\n\n/**\n * Workaround for \"Type instantiation is excessively deep and possibly infinite.ts\" errors.\n * @remarks\n *\n * Generally this workaround should be avoided if possible,\n * especially for exported types, as it is likely to result in issues when exporting or importing schema where the user will be forced to use the workaround as well.\n * This is particularly problematic since in some cases it may not be possible for the user to replicate the pattern.\n * Additionally, which cases hit these limits may vary based on TypeScript version and implementation details of this library.\n *\n * This workaround is provided and documented as a last resort to be able to keep an app compiling.\n * Future version of SharedTree should provide schema type erasure functionality as a better alternative for most cases.\n *\n * When TypeScript gives the error \"Error (TS2589) Type instantiation is excessively deep and possibly infinite.\" on the invocation of `ValidateRecursiveSchema`\n * for a large schema, it can sometimes be worked around by repeating the usage of the type multiple times.\n * This works because the TypeScript compiler caches some of the intermediate results from the first usage, and thus can get further on the second.\n *\n * This utility can be referenced when applying this pattern.\n * For recursive types this can be used directly:\n *\n * ```typescript\n * {\n *     // @ts-expect-error Recursion limit\n *     type _check1 = FixRecursiveRecursionLimit<typeof LargeType>;\n *     type _check2 = FixRecursiveRecursionLimit<typeof LargeType>;\n *     type _check3 = ValidateRecursiveSchemaTemplate<typeof LargeType>;\n * }\n * ```\n *\n * For non-recursive types, they can be ported to the more flexible recursive APIs and use the pattern above.\n *\n * Non-recursive types can also use this workaround by making a duplicate copy of the problematic schema written using the recursive APIs.\n * Then this pattern can be applied to the duplicate copy.\n *\n * ```typescript\n * // Workaround TypeScript recursion limit\n * \t{\n * \t\tclass LargeUnionObjectNode_Fix extends schema.objectRecursive(\"ObjectNode\", {\n * \t\t\tx: largeUnion,\n * \t\t}) {}\n *\n * \t\t// @ts-expect-error Recursion limit\n * \t\tallowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();\n * \t\tallowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();\n * \t\tallowUnused<ValidateRecursiveSchema<typeof LargeUnionObjectNode_Fix>>();\n * \t\t}\n *\n * \t// Fails to compile without the above workaround.\n * \tclass LargeUnionObjectNode extends schema.object(\"ObjectNode\", { x: largeUnion }) {}\n * ```\n * @privateRemarks\n * Using this is real sketchy, and leads to a lot of issues (errors which depend on how the schema is compiled, making different build setups produce different results and complicating exports).\n * This is being kept as internal for now: if a customer really needs it, we have this as a documented workaround, but it would be much better to find an alternative solution before using this one.\n * This uses ValidateRecursiveSchemaTemplate since it was found to evaluate enough of the type to work.\n * @internal\n */\nexport type FixRecursiveRecursionLimit<T extends TreeNodeSchema> =\n\tT extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;\n\n/**\n * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.\n *\n * @remarks\n * When TypeScript is configured with \"noUnusedLocals\", it will produce an error if a local variable is declared but never used.\n * When you want to have this check enabled, but not follow it for a specific variable, you can pass the type or value to this function.\n *\n * Instead of using this, consider disabling \"noUnusedLocals\" in your tsconfig.json file, and enabling a similar check via a linter.\n * This will allow you to still have the check, but have more control over it, for example being able to suppress it, or enable patterns like allowing unused locals with an \"_\" prefix.\n * @alpha\n */\nexport function allowUnused<T>(t?: T): void {}\n\n/**\n * Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.\n * @remarks\n * Importing a recursive ArrayNode schema via a d.ts file can produce an error like\n * `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.`\n * if using a tsconfig with `\"skipLibCheck\": false`.\n *\n * This error occurs due to the TypeScript compiler splitting the class definition into two separate declarations in the d.ts file (one for the base, and one for the actual class).\n * For unknown reasons, splitting the class declaration in this way breaks the recursive type handling, leading to the mentioned error.\n *\n * This type always evaluates to `undefined` to ensure the dummy export (which doesn't exist at runtime) is typed correctly.\n *\n * {@link https://github.com/microsoft/TypeScript/issues/59550|TypeScript Issue 59550} tracks a suggestion which would make this workaround unnecessary.\n *\n * @example Usage\n * Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error.\n * For the case of ArrayNodes, this can be done via usage that looks like this:\n *\n * This example should use a doc comment to ensure the workaround comment shows up in the intellisense for the dummy export,\n * however doing so is impossible due to how this example is included in a doc comment.\n * ```typescript\n *  // Workaround to avoid\n *  // `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.` in the d.ts file.\n * export declare type _RecursiveArrayWorkaround = FixRecursiveArraySchema<typeof RecursiveArray>;\n * export class RecursiveArray extends schema.arrayRecursive(\"RA\", [() => RecursiveArray]) {}\n * {\n * \ttype _check = ValidateRecursiveSchema<typeof RecursiveArray>;\n * }\n * ```\n *\n * @alpha\n */\nexport type FixRecursiveArraySchema<T> = T extends TreeNodeSchema ? undefined : undefined;\n"]}
+{"version":3,"file":"schemaFactoryRecursive.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactoryRecursive.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AA8OH;;;;;;;;;;GAUG;AACH,SAAgB,WAAW,CAAI,CAAK,IAAS,CAAC;AAA9C,kCAA8C","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 type {\n\tNodeKind,\n\tTreeNodeSchema,\n\tWithType,\n\tTreeNode,\n\tImplicitAllowedTypes,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n} from \"../core/index.js\";\nimport type { InsertableObjectFromSchemaRecord } from \"../node-kinds/index.js\";\nimport type { ImplicitFieldSchema } from \"../fieldSchema.js\";\n\n/**\n * Compile time check for validity of a recursive schema.\n * This type also serves as a central location for documenting the requirements and issues related to recursive schema.\n *\n * @example\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => Test]) {}\n * {\n *     type _check = ValidateRecursiveSchema<typeof Test>;\n * }\n * ```\n * @remarks\n * In this context recursive schema are defined as all {@link FieldSchema} and {@link TreeNodeSchema} schema which are part of a cycle such that walking down through each {@link TreeNodeSchemaCore.childTypes} the given starting schema can be reached again.\n * Schema referencing the recursive schema and schema they reference that are not part of a cycle are not considered recursive.\n *\n * TypeScript puts a lot of limitations on the typing of recursive schema.\n * To help avoid running into these limitations and thus getting schema that do not type check (or only type checks sometimes!),\n * {@link SchemaFactory} provides APIs (postfixed with `Recursive`) for writing recursive schema.\n * These APIs when combined with the patterns documented below should ensure that the schema provide robust type checking.\n * These special patterns (other than {@link LazyItem} forward references which are not recursion specific)\n * are not required for correct runtime behavior: they exist entirely to mitigate TypeScript type checking limitations and bugs.\n * Ideally TypeScript's type checker would be able to handle all of these cases and more, removing the need for recursive type specific guidance, rules and APIs.\n * Currently however there are open issues preventing this:\n * {@link https://github.com/microsoft/TypeScript/issues/59550 | 1},\n * {@link https://github.com/microsoft/TypeScript/issues/55832 | 2},\n * {@link https://github.com/microsoft/TypeScript/issues/55758 | 3}.\n * Note that the proposed resolution to some of these issues is for the compiler to error rather than allow the case,\n * so even if these are all resolved the recursive type workarounds may still be needed.\n *\n * # Patterns\n *\n * Below are patterns for how to use recursive schema.\n *\n * ## General Patterns\n *\n * When defining a recursive {@link TreeNodeSchema}, use the `*Recursive` {@link SchemaFactory} methods.\n * The returned class should be used as the base class for the recursive schema, which should then be passed to {@link ValidateRecursiveSchema}.\n *\n * Using {@link ValidateRecursiveSchema} will provide compile error for some of the cases of malformed schema.\n * This can be used to help mitigate the issue that recursive schema definitions are {@link Unenforced}.\n * If an issue is encountered where a mistake in a recursive schema is made which produces an invalid schema but is not rejected by this checker,\n * it should be considered a bug and this should be updated to handle that case (or have a disclaimer added to these docs that it misses that case).\n *\n * The non-recursive versions of the schema building methods will run into several issues when used recursively.\n * Consider the following example:\n *\n * ```typescript\n * const Test = sf.array(Test); // Bad\n * ```\n *\n * This has several issues:\n *\n * 1. It is a structurally named schema.\n * Structurally named schema derive their name from the names of their child types, which is not possible when the type is recursive since its name would include itself.\n * Instead a name must be explicitly provided.\n *\n * 2. The schema accesses itself before it's defined.\n * This would be a runtime error if the TypeScript compiler allowed it.\n * This can be fixed by wrapping the type in a function, which also requires explicitly listing the allowed types in an array (`[() => Test]`).\n *\n * 3. TypeScript fails to infer the recursive type and falls back to `any` with this warning or error (depending on the compiler configuration):\n * `'Test' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.ts(7022)`.\n * This issue is what the specialized recursive schema building methods fix.\n * This fix comes at a cost: to make the recursive cases work, the `extends` clauses had to be removed.\n * This means that mistakes declaring recursive schema often don't give compile errors in the schema.\n * Additionally support for implicit construction had to be disabled.\n * This means that new nested {@link Unhydrated} nodes can not be created like `new Test([[]])`.\n * Instead the nested nodes must be created explicitly using the construction like`new Test([new Test([])])`.\n *\n * 4. It is using \"POJO\" mode since it's not explicitly declaring a new class.\n * This means that the generated d.ts files for the schema replace recursive references with `any`, breaking use of recursive schema across compilation boundaries.\n * This is fixed by explicitly creating a class which extends the returned schema.\n *\n * All together, the fixed version looks like:\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => Test]) {} // Good\n * ```\n *\n * Be very careful when declaring recursive schema.\n * Due to the removed extends clauses, subtle mistakes will compile just fine but cause strange errors when the schema is used.\n *\n * For example if a reference to a schema is malformed (in this case boxed inside an object):\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * ```\n * This schema will still compile, and some (but not all) usages of it may look like they work correctly while other usages will produce generally unintelligible compile errors.\n * This issue can be partially mitigated using {@link ValidateRecursiveSchema}:\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * {\n *     type _check = ValidateRecursiveSchema<typeof Test>; // Reports compile error due to invalid schema above.\n * }\n * ```\n *\n * If your TypeScript configuration objects to this patten due to the unused local, you can use {@link allowUnused} to suppress the error:\n *\n * ```typescript\n * class Test extends sf.arrayRecursive(\"Test\", [() => ({ Test })]) {} // Bad\n * allowUnused<ValidateRecursiveSchema<typeof Test>>(); // Reports compile error due to invalid schema above.\n * ```\n *\n * ## Object Schema\n *\n * When defining fields, if the fields is part of the recursive cycle, use the `*Recursive` {@link SchemaFactory} methods for defining the {@link FieldSchema}.\n *\n * ## Array Schema\n *\n * See {@link FixRecursiveArraySchema} for array specific details.\n *\n * @privateRemarks\n * There are probably mistakes this misses: it's hard to guess all the wrong things people will accidentally do and defend against them.\n * Hopefully over time this can grow toward being robust, at least for common mistakes.\n *\n * This check duplicates logic that ideally would be entirely decided by the actual schema building methods.\n * Therefore changes to those methods may require updating `ValidateRecursiveSchema`.\n *\n * TODO: this currently does not reject `any`, but ideally should.\n * @public\n */\nexport type ValidateRecursiveSchema<\n\t// Recursive types should always be using TreeNodeSchemaClass (not TreeNodeSchemaNonClass) as thats part of the requirements for the type to work across compilation boundaries correctly.\n\tT extends ValidateRecursiveSchemaTemplate<T>,\n> = true;\n\n/**\n * Validation logic used by {@link ValidateRecursiveSchema}.\n * @system @public\n */\nexport type ValidateRecursiveSchemaTemplate<T extends TreeNodeSchema> = TreeNodeSchema<\n\t// Name: This validator places no restrictions on the name other than that it's a string (as required by TreeNodeSchemaClass).\n\tstring,\n\t// NodeKind: These are the NodeKinds which currently can be used recursively.\n\tNodeKind.Array | NodeKind.Map | NodeKind.Object | NodeKind.Record,\n\t// TNode: The produced node API. This is pretty minimal validation: more could be added if similar to how TInsertable works below if needed.\n\tTreeNode & WithType<T[\"identifier\"], T[\"kind\"]>,\n\t// TInsertable: What can be passed to the constructor. This should be enough to catch most issues with incorrect schema.\n\t// These match whats defined in the recursive methods on `SchemaFactory` except they do not use `Unenforced`.\n\t{\n\t\t[NodeKind.Object]: T[\"info\"] extends RestrictiveStringRecord<ImplicitFieldSchema>\n\t\t\t? InsertableObjectFromSchemaRecord<T[\"info\"]>\n\t\t\t: unknown;\n\t\t[NodeKind.Array]: T[\"info\"] extends ImplicitAllowedTypes\n\t\t\t? Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T[\"info\"]>>\n\t\t\t: unknown;\n\t\t[NodeKind.Map]: T[\"info\"] extends ImplicitAllowedTypes\n\t\t\t? Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T[\"info\"]>]>\n\t\t\t: unknown;\n\t\t[NodeKind.Record]: {\n\t\t\treadonly [P in string]: InsertableTreeNodeFromImplicitAllowedTypes<T>;\n\t\t};\n\t\t[NodeKind.Leaf]: unknown;\n\t}[T[\"kind\"]],\n\t// ImplicitlyConstructable: recursive types are currently not implicitly constructable.\n\tfalse,\n\t// Info: What's passed to the method to create the schema. Constraining these here should be about as effective as if the actual constraints existed on the actual method itself.\n\t{\n\t\t[NodeKind.Object]: RestrictiveStringRecord<ImplicitFieldSchema>;\n\t\t[NodeKind.Array]: ImplicitAllowedTypes;\n\t\t[NodeKind.Map]: ImplicitAllowedTypes;\n\t\t[NodeKind.Record]: ImplicitAllowedTypes;\n\t\t[NodeKind.Leaf]: unknown;\n\t}[T[\"kind\"]]\n>;\n\n/**\n * Workaround for \"Type instantiation is excessively deep and possibly infinite.ts\" errors.\n * @remarks\n *\n * Generally this workaround should be avoided if possible,\n * especially for exported types, as it is likely to result in issues when exporting or importing schema where the user will be forced to use the workaround as well.\n * This is particularly problematic since in some cases it may not be possible for the user to replicate the pattern.\n * Additionally, which cases hit these limits may vary based on TypeScript version and implementation details of this library.\n *\n * This workaround is provided and documented as a last resort to be able to keep an app compiling.\n * Future version of SharedTree should provide schema type erasure functionality as a better alternative for most cases.\n *\n * When TypeScript gives the error \"Error (TS2589) Type instantiation is excessively deep and possibly infinite.\" on the invocation of `ValidateRecursiveSchema`\n * for a large schema, it can sometimes be worked around by repeating the usage of the type multiple times.\n * This works because the TypeScript compiler caches some of the intermediate results from the first usage, and thus can get further on the second.\n *\n * This utility can be referenced when applying this pattern.\n * For recursive types this can be used directly:\n *\n * ```typescript\n * {\n *     // @ts-expect-error Recursion limit\n *     type _check1 = FixRecursiveRecursionLimit<typeof LargeType>;\n *     type _check2 = FixRecursiveRecursionLimit<typeof LargeType>;\n *     type _check3 = ValidateRecursiveSchemaTemplate<typeof LargeType>;\n * }\n * ```\n *\n * For non-recursive types, they can be ported to the more flexible recursive APIs and use the pattern above.\n *\n * Non-recursive types can also use this workaround by making a duplicate copy of the problematic schema written using the recursive APIs.\n * Then this pattern can be applied to the duplicate copy.\n *\n * ```typescript\n * // Workaround TypeScript recursion limit\n * \t{\n * \t\tclass LargeUnionObjectNode_Fix extends schema.objectRecursive(\"ObjectNode\", {\n * \t\t\tx: largeUnion,\n * \t\t}) {}\n *\n * \t\t// @ts-expect-error Recursion limit\n * \t\tallowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();\n * \t\tallowUnused<FixRecursiveRecursionLimit<typeof LargeUnionObjectNode_Fix>>();\n * \t\tallowUnused<ValidateRecursiveSchema<typeof LargeUnionObjectNode_Fix>>();\n * \t\t}\n *\n * \t// Fails to compile without the above workaround.\n * \tclass LargeUnionObjectNode extends schema.object(\"ObjectNode\", { x: largeUnion }) {}\n * ```\n * @privateRemarks\n * Using this is real sketchy, and leads to a lot of issues (errors which depend on how the schema is compiled, making different build setups produce different results and complicating exports).\n * This is being kept as internal for now: if a customer really needs it, we have this as a documented workaround, but it would be much better to find an alternative solution before using this one.\n * This uses ValidateRecursiveSchemaTemplate since it was found to evaluate enough of the type to work.\n * @internal\n */\nexport type FixRecursiveRecursionLimit<T extends TreeNodeSchema> =\n\tT extends ValidateRecursiveSchemaTemplate<T> ? undefined : undefined;\n\n/**\n * Does nothing with the provided value, but appears to use it to make unused locals warnings and errors go away.\n *\n * @remarks\n * When TypeScript is configured with \"noUnusedLocals\", it will produce an error if a local variable is declared but never used.\n * When you want to have this check enabled, but not follow it for a specific variable, you can pass the type or value to this function.\n *\n * Instead of using this, consider disabling \"noUnusedLocals\" in your tsconfig.json file, and enabling a similar check via a linter.\n * This will allow you to still have the check, but have more control over it, for example being able to suppress it, or enable patterns like allowing unused locals with an \"_\" prefix.\n * @alpha\n */\nexport function allowUnused<T>(t?: T): void {}\n\n/**\n * Workaround for fixing errors resulting from an issue with recursive ArrayNode schema exports.\n * @remarks\n * Importing a recursive ArrayNode schema via a d.ts file can produce an error like\n * `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.`\n * if using a tsconfig with `\"skipLibCheck\": false`.\n *\n * This error occurs due to the TypeScript compiler splitting the class definition into two separate declarations in the d.ts file (one for the base, and one for the actual class).\n * For unknown reasons, splitting the class declaration in this way breaks the recursive type handling, leading to the mentioned error.\n *\n * This type always evaluates to `undefined` to ensure the dummy export (which doesn't exist at runtime) is typed correctly.\n *\n * {@link https://github.com/microsoft/TypeScript/issues/59550|TypeScript Issue 59550} tracks a suggestion which would make this workaround unnecessary.\n *\n * @example Usage\n * Since recursive type handling in TypeScript is order dependent, putting just the right kind of usages of the type before the declarations can cause it to not hit this error.\n * For the case of ArrayNodes, this can be done via usage that looks like this:\n *\n * This example should use a doc comment to ensure the workaround comment shows up in the intellisense for the dummy export,\n * however doing so is impossible due to how this example is included in a doc comment.\n * ```typescript\n *  // Workaround to avoid\n *  // `error TS2310: Type 'RecursiveArray' recursively references itself as a base type.` in the d.ts file.\n * export declare type _RecursiveArrayWorkaround = FixRecursiveArraySchema<typeof RecursiveArray>;\n * export class RecursiveArray extends schema.arrayRecursive(\"RA\", [() => RecursiveArray]) {}\n * {\n * \ttype _check = ValidateRecursiveSchema<typeof RecursiveArray>;\n * }\n * ```\n *\n * @alpha\n */\nexport type FixRecursiveArraySchema<T> = T extends TreeNodeSchema ? undefined : undefined;\n"]}

package/dist/simple-tree/api/schemaStatics.d.ts

@@ -0,0 +1,158 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { IFluidHandle } from "@fluidframework/core-interfaces";
+import type { ImplicitAllowedTypes, ImplicitAnnotatedAllowedTypes, UnannotateImplicitAllowedTypes } from "../core/index.js";
+import { FieldKind } from "../fieldSchema.js";
+import type { FieldProps, FieldSchema, FieldPropsAlpha, FieldSchemaAlpha } from "../fieldSchema.js";
+import type { LeafSchema } from "../leafNodeSchema.js";
+import { stringSchema } from "../leafNodeSchema.js";
+import type { System_Unsafe, FieldSchemaAlphaUnsafe } from "./typesUnsafe.js";
+/**
+ * Stateless APIs exposed via {@link SchemaFactory} as both instance properties and as statics.
+ * @privateRemarks
+ * We have no way to make linkable members which exist both as statics and instance properties since API-Extractor does not support this.
+ * As a workaround, we have this type as a third place which can be linked.
+ * @system @sealed @public
+ */
+export interface SchemaStatics {
+    /**
+     * {@link TreeNodeSchema} for holding a JavaScript `string`.
+     *
+     * @remarks
+     * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.
+     *
+     * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.
+     * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.
+     * @privateRemarks
+     * TODO:
+     * We should be much more clear about what happens if you use problematic values.
+     * We should validate and/or normalize them when inserting content.
+     */
+    readonly string: LeafSchema<"string", string>;
+    /**
+     * {@link TreeNodeSchema} for holding a JavaScript `number`.
+     *
+     * @remarks
+     * The number is a {@link https://en.wikipedia.org/wiki/Double-precision_floating-point_format | double-precision 64-bit binary format IEEE 754} value, however there are some exceptions:
+     *
+     * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+     *
+     * - `-0` may be converted to `0` in some cases.
+     *
+     * These limitations match the limitations of JSON.
+     * @privateRemarks
+     * TODO:
+     * We should be much more clear about what happens if you use problematic values.
+     * We should validate and/or normalize them when inserting content.
+     */
+    readonly number: LeafSchema<"number", number>;
+    /**
+     * {@link TreeNodeSchema} for holding a boolean.
+     */
+    readonly boolean: LeafSchema<"boolean", boolean>;
+    /**
+     * {@link TreeNodeSchema} for JavaScript `null`.
+     *
+     * @remarks
+     * There are good {@link https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-null | reasons to avoid using null} in JavaScript, however sometimes it is desired.
+     * This {@link TreeNodeSchema} node provides the option to include nulls in trees when desired.
+     * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.
+     */
+    readonly null: LeafSchema<"null", null>;
+    /**
+     * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.
+     */
+    readonly handle: LeafSchema<"handle", IFluidHandle>;
+    /**
+     * {@link AllowedTypes} for holding any of the leaf types.
+     */
+    readonly leaves: readonly [
+        SchemaStatics["string"],
+        SchemaStatics["number"],
+        SchemaStatics["boolean"],
+        SchemaStatics["null"],
+        SchemaStatics["handle"]
+    ];
+    /**
+     * Make a field optional instead of the default, which is required.
+     *
+     * @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 optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">) => FieldSchema<FieldKind.Optional, T, TCustomMetadata>;
+    /**
+     * Make a field explicitly required.
+     *
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
+     *
+     * @remarks
+     * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
+     * and allows associating custom {@link FieldProps | properties} with the field.
+     *
+     * @typeParam TCustomMetadata - Custom metadata properties to associate with the field.
+     * See {@link FieldSchemaMetadata.custom}.
+     */
+    readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">) => FieldSchema<FieldKind.Required, T, TCustomMetadata>;
+    /**
+     * {@link SchemaStatics.optional} except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
+     * @remarks
+     * This version of {@link SchemaStatics.optional} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+     */
+    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+    /**
+     * {@link SchemaStatics.required} except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
+     * @remarks
+     * This version of {@link SchemaStatics.required} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+     */
+    readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;
+}
+declare function optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
+declare function optional<const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+declare function required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
+declare function required<const T extends ImplicitAnnotatedAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;
+/**
+ * Implementation of {@link SchemaStatics}.
+ * @remarks
+ * Entries can use more specific types than {@link SchemaStatics} requires to be more useful for non-public consumers.
+ * Additional non-public members are in {@link schemaStatics}.
+ */
+export declare const schemaStaticsStable: {
+    readonly string: LeafSchema<"string", string> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly number: LeafSchema<"number", number> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly boolean: LeafSchema<"boolean", boolean> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly null: LeafSchema<"null", null> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly handle: LeafSchema<"handle", IFluidHandle<unknown>> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly leaves: readonly [LeafSchema<"string", string> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"number", number> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"null", null> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"handle", IFluidHandle<unknown>> & import("../simpleSchema.js").SimpleLeafNodeSchema];
+    readonly optional: typeof optional;
+    readonly required: typeof required;
+    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider">) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+    readonly requiredRecursive: <const T_1 extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata_1 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T_1, TCustomMetadata_1>;
+};
+/**
+ * Unstable extensions to {@link schemaStaticsStable}.
+ */
+export declare const schemaStatics: {
+    readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider">) => FieldSchemaAlpha<FieldKind.Identifier, typeof stringSchema, TCustomMetadata>;
+    readonly string: LeafSchema<"string", string> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly number: LeafSchema<"number", number> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly boolean: LeafSchema<"boolean", boolean> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly null: LeafSchema<"null", null> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly handle: LeafSchema<"handle", IFluidHandle<unknown>> & import("../simpleSchema.js").SimpleLeafNodeSchema;
+    readonly leaves: readonly [LeafSchema<"string", string> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"number", number> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"boolean", boolean> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"null", null> & import("../simpleSchema.js").SimpleLeafNodeSchema, LeafSchema<"handle", IFluidHandle<unknown>> & import("../simpleSchema.js").SimpleLeafNodeSchema];
+    readonly optional: typeof optional;
+    readonly required: typeof required;
+    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata_1 = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata_1>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata_1>;
+    readonly requiredRecursive: <const T_1 extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata_2 = unknown>(t: T_1, props?: Omit<FieldPropsAlpha<TCustomMetadata_2>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T_1, TCustomMetadata_2>;
+};
+export {};
+//# sourceMappingURL=schemaStatics.d.ts.map

package/dist/simple-tree/api/schemaStatics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaStatics.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaStatics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EACX,oBAAoB,EACpB,6BAA6B,EAC7B,8BAA8B,EAC9B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAyC,MAAM,mBAAmB,CAAC;AACrF,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EAEX,eAAe,EACf,gBAAgB,EAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EACN,YAAY,EAKZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEjD;;;;;;;OAOG;IAEH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS;QACzB,aAAa,CAAC,QAAQ,CAAC;QACvB,aAAa,CAAC,QAAQ,CAAC;QACvB,aAAa,CAAC,SAAS,CAAC;QACxB,aAAa,CAAC,MAAM,CAAC;QACrB,aAAa,CAAC,QAAQ,CAAC;KACvB,CAAC;IAEF;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAAE,KAAK,CAAC,eAAe,GAAG,OAAO,EACxF,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,KACxD,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;IAEzD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAAE,KAAK,CAAC,eAAe,GAAG,OAAO,EACxF,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,KACxD,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;IAEzD;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC3B,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,0BAA0B,EACxD,KAAK,CAAC,eAAe,GAAG,OAAO,EAE/B,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,KACxD,aAAa,CAAC,iBAAiB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;IAE7E;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,CAC3B,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,0BAA0B,EACxD,KAAK,CAAC,eAAe,GAAG,OAAO,EAE/B,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,KACxD,aAAa,CAAC,iBAAiB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;CAC7E;AAQD,iBAAS,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAAE,KAAK,CAAC,eAAe,GAAG,OAAO,EACtF,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,GAC/D,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;AAE5D,iBAAS,QAAQ,CAChB,KAAK,CAAC,CAAC,SAAS,6BAA6B,EAC7C,KAAK,CAAC,eAAe,GAAG,OAAO,EAE/B,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,GAC/D,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,8BAA8B,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AAe5F,iBAAS,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAAE,KAAK,CAAC,eAAe,GAAG,OAAO,EACtF,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,GAC/D,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC,CAAC;AAE5D,iBAAS,QAAQ,CAChB,KAAK,CAAC,CAAC,SAAS,6BAA6B,EAC7C,KAAK,CAAC,eAAe,GAAG,OAAO,EAE/B,CAAC,EAAE,CAAC,EACJ,KAAK,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,iBAAiB,CAAC,GAC/D,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,8BAA8B,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;AAa5F;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;+HAgB3B,CAAC,UACI,KAAK,gBAAgB,eAAe,CAAC,EAAE,iBAAiB,CAAC,KAC/D,uBAAuB,UAAU,QAAQ,EAAE,CAAC,EAAE,eAAe,CAAC;;CAgBhC,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,aAAa;mEAGhB,KAAK,WAAW,eAAe,CAAC,EAAE,iBAAiB,CAAC,KAC1D,iBAAiB,UAAU,UAAU,EAAE,mBAAmB,EAAE,eAAe,CAAC;;;;;;;;;iIA3B3E,CAAC;;CA8BI,CAAC"}

package/dist/simple-tree/api/schemaStatics.js

@@ -0,0 +1,59 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaStatics = exports.schemaStaticsStable = void 0;
+const fieldSchema_js_1 = require("../fieldSchema.js");
+const leafNodeSchema_js_1 = require("../leafNodeSchema.js");
+const defaultOptionalProvider = (0, fieldSchema_js_1.getDefaultProvider)(() => []);
+function optional(t, props) {
+    return (0, fieldSchema_js_1.createFieldSchema)(fieldSchema_js_1.FieldKind.Optional, t, {
+        defaultProvider: defaultOptionalProvider,
+        ...props,
+    });
+}
+function required(t, props) {
+    return (0, fieldSchema_js_1.createFieldSchema)(fieldSchema_js_1.FieldKind.Required, t, props);
+}
+// #endregion
+/**
+ * Implementation of {@link SchemaStatics}.
+ * @remarks
+ * Entries can use more specific types than {@link SchemaStatics} requires to be more useful for non-public consumers.
+ * Additional non-public members are in {@link schemaStatics}.
+ */
+exports.schemaStaticsStable = {
+    string: leafNodeSchema_js_1.stringSchema,
+    number: leafNodeSchema_js_1.numberSchema,
+    boolean: leafNodeSchema_js_1.booleanSchema,
+    null: leafNodeSchema_js_1.nullSchema,
+    handle: leafNodeSchema_js_1.handleSchema,
+    leaves: [leafNodeSchema_js_1.stringSchema, leafNodeSchema_js_1.numberSchema, leafNodeSchema_js_1.booleanSchema, leafNodeSchema_js_1.nullSchema, leafNodeSchema_js_1.handleSchema],
+    optional,
+    required,
+    optionalRecursive: (t, props) => {
+        return createFieldSchemaUnsafe(fieldSchema_js_1.FieldKind.Optional, t, {
+            defaultProvider: defaultOptionalProvider,
+            ...props,
+        });
+    },
+    requiredRecursive: (t, props) => {
+        return createFieldSchemaUnsafe(fieldSchema_js_1.FieldKind.Required, t, props);
+    },
+};
+/**
+ * Unstable extensions to {@link schemaStaticsStable}.
+ */
+exports.schemaStatics = {
+    ...exports.schemaStaticsStable,
+    identifier: (props) => {
+        return (0, fieldSchema_js_1.createFieldSchema)(fieldSchema_js_1.FieldKind.Identifier, leafNodeSchema_js_1.stringSchema, props);
+    },
+};
+function createFieldSchemaUnsafe(kind, allowedTypes, props) {
+    // At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe
+    return (0, fieldSchema_js_1.createFieldSchema)(kind, allowedTypes, props);
+}
+//# sourceMappingURL=schemaStatics.js.map

package/dist/simple-tree/api/schemaStatics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaStatics.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaStatics.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAQH,sDAAqF;AASrF,4DAM8B;AA2I9B,MAAM,uBAAuB,GAAoB,IAAA,mCAAkB,EAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;AAmB9E,SAAS,QAAQ,CAIhB,CAAI,EACJ,KAAiE;IAEjE,OAAO,IAAA,kCAAiB,EAAC,0BAAS,CAAC,QAAQ,EAAE,CAAC,EAAE;QAC/C,eAAe,EAAE,uBAAuB;QACxC,GAAG,KAAK;KACR,CAAC,CAAC;AACJ,CAAC;AAeD,SAAS,QAAQ,CAIhB,CAAI,EACJ,KAAiE;IAEjE,OAAO,IAAA,kCAAiB,EAAC,0BAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AACD,aAAa;AAEb;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG;IAClC,MAAM,EAAE,gCAAY;IACpB,MAAM,EAAE,gCAAY;IACpB,OAAO,EAAE,iCAAa;IACtB,IAAI,EAAE,8BAAU;IAChB,MAAM,EAAE,gCAAY;IACpB,MAAM,EAAE,CAAC,gCAAY,EAAE,gCAAY,EAAE,iCAAa,EAAE,8BAAU,EAAE,gCAAY,CAAC;IAE7E,QAAQ;IAER,QAAQ;IAER,iBAAiB,EAAE,CAIlB,CAAI,EACJ,KAAiE,EACA,EAAE;QACnE,OAAO,uBAAuB,CAAC,0BAAS,CAAC,QAAQ,EAAE,CAAC,EAAE;YACrD,eAAe,EAAE,uBAAuB;YACxC,GAAG,KAAK;SACR,CAAC,CAAC;IACJ,CAAC;IAED,iBAAiB,EAAE,CAIlB,CAAI,EACJ,KAAiE,EACA,EAAE;QACnE,OAAO,uBAAuB,CAAC,0BAAS,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC;CACgC,CAAC;AAEnC;;GAEG;AACU,QAAA,aAAa,GAAG;IAC5B,GAAG,2BAAmB;IACtB,UAAU,EAAE,CACX,KAA4D,EACmB,EAAE;QACjF,OAAO,IAAA,kCAAiB,EAAC,0BAAS,CAAC,UAAU,EAAE,gCAAY,EAAE,KAAK,CAAC,CAAC;IACrE,CAAC;CACQ,CAAC;AAEX,SAAS,uBAAuB,CAK/B,IAAU,EACV,YAAmB,EACnB,KAAmC;IAEnC,kJAAkJ;IAClJ,OAAO,IAAA,kCAAiB,EACvB,IAAI,EACJ,YAA4C,EAC5C,KAAK,CACmD,CAAC;AAC3D,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport type {\n\tImplicitAllowedTypes,\n\tImplicitAnnotatedAllowedTypes,\n\tUnannotateImplicitAllowedTypes,\n} from \"../core/index.js\";\nimport { FieldKind, getDefaultProvider, createFieldSchema } from \"../fieldSchema.js\";\nimport type {\n\tFieldProps,\n\tFieldSchema,\n\tDefaultProvider,\n\tFieldPropsAlpha,\n\tFieldSchemaAlpha,\n} from \"../fieldSchema.js\";\nimport type { LeafSchema } from \"../leafNodeSchema.js\";\nimport {\n\tstringSchema,\n\tnumberSchema,\n\tbooleanSchema,\n\tnullSchema,\n\thandleSchema,\n} from \"../leafNodeSchema.js\";\nimport type { System_Unsafe, FieldSchemaAlphaUnsafe } from \"./typesUnsafe.js\";\n\n/**\n * Stateless APIs exposed via {@link SchemaFactory} as both instance properties and as statics.\n * @privateRemarks\n * We have no way to make linkable members which exist both as statics and instance properties since API-Extractor does not support this.\n * As a workaround, we have this type as a third place which can be linked.\n * @system @sealed @public\n */\nexport interface SchemaStatics {\n\t/**\n\t * {@link TreeNodeSchema} for holding a JavaScript `string`.\n\t *\n\t * @remarks\n\t * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.\n\t *\n\t * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.\n\t * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.\n\t * @privateRemarks\n\t * TODO:\n\t * We should be much more clear about what happens if you use problematic values.\n\t * We should validate and/or normalize them when inserting content.\n\t */\n\treadonly string: LeafSchema<\"string\", string>;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a JavaScript `number`.\n\t *\n\t * @remarks\n\t * The number is a {@link https://en.wikipedia.org/wiki/Double-precision_floating-point_format | double-precision 64-bit binary format IEEE 754} value, however there are some exceptions:\n\t *\n\t * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).\n\t *\n\t * - `-0` may be converted to `0` in some cases.\n\t *\n\t * These limitations match the limitations of JSON.\n\t * @privateRemarks\n\t * TODO:\n\t * We should be much more clear about what happens if you use problematic values.\n\t * We should validate and/or normalize them when inserting content.\n\t */\n\treadonly number: LeafSchema<\"number\", number>;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a boolean.\n\t */\n\treadonly boolean: LeafSchema<\"boolean\", boolean>;\n\n\t/**\n\t * {@link TreeNodeSchema} for JavaScript `null`.\n\t *\n\t * @remarks\n\t * There are good {@link https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-null | reasons to avoid using null} in JavaScript, however sometimes it is desired.\n\t * This {@link TreeNodeSchema} node provides the option to include nulls in trees when desired.\n\t * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.\n\t */\n\t// eslint-disable-next-line @rushstack/no-new-null\n\treadonly null: LeafSchema<\"null\", null>;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.\n\t */\n\treadonly handle: LeafSchema<\"handle\", IFluidHandle>;\n\n\t/**\n\t * {@link AllowedTypes} for holding any of the leaf types.\n\t */\n\treadonly leaves: readonly [\n\t\tSchemaStatics[\"string\"],\n\t\tSchemaStatics[\"number\"],\n\t\tSchemaStatics[\"boolean\"],\n\t\tSchemaStatics[\"null\"],\n\t\tSchemaStatics[\"handle\"],\n\t];\n\n\t/**\n\t * Make a field optional instead of the default, which is required.\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 optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps<TCustomMetadata>, \"defaultProvider\">,\n\t) => FieldSchema<FieldKind.Optional, T, TCustomMetadata>;\n\n\t/**\n\t * Make a field explicitly required.\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 * @remarks\n\t * Fields are required by default, but this API can be used to make the required nature explicit in the schema,\n\t * and allows associating custom {@link FieldProps | properties} 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 required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps<TCustomMetadata>, \"defaultProvider\">,\n\t) => FieldSchema<FieldKind.Required, T, TCustomMetadata>;\n\n\t/**\n\t * {@link SchemaStatics.optional} 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 SchemaStatics.optional} 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\treadonly optionalRecursive: <\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps<TCustomMetadata>, \"defaultProvider\">,\n\t) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Optional, T, TCustomMetadata>;\n\n\t/**\n\t * {@link SchemaStatics.required} 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 SchemaStatics.required} 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\treadonly requiredRecursive: <\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps<TCustomMetadata>, \"defaultProvider\">,\n\t) => System_Unsafe.FieldSchemaUnsafe<FieldKind.Required, T, TCustomMetadata>;\n}\n\nconst defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => []);\n\n// The following overloads for optional and required are used to get around the fact that\n// the compiler can't infer that UnannotateImplicitAllowedTypes<T> is equal to T when T is known to extend ImplicitAllowedTypes\n\n// #region Overloads for optional and required\nfunction optional<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;\n\nfunction optional<\n\tconst T extends ImplicitAnnotatedAllowedTypes,\n\tconst TCustomMetadata = unknown,\n>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;\n\nfunction optional<\n\tconst T extends ImplicitAnnotatedAllowedTypes,\n\tconst TCustomMetadata = unknown,\n>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Optional, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {\n\treturn createFieldSchema(FieldKind.Optional, t, {\n\t\tdefaultProvider: defaultOptionalProvider,\n\t\t...props,\n\t});\n}\n\nfunction required<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;\n\nfunction required<\n\tconst T extends ImplicitAnnotatedAllowedTypes,\n\tconst TCustomMetadata = unknown,\n>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata>;\n\nfunction required<\n\tconst T extends ImplicitAnnotatedAllowedTypes,\n\tconst TCustomMetadata = unknown,\n>(\n\tt: T,\n\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n): FieldSchemaAlpha<FieldKind.Required, UnannotateImplicitAllowedTypes<T>, TCustomMetadata> {\n\treturn createFieldSchema(FieldKind.Required, t, props);\n}\n// #endregion\n\n/**\n * Implementation of {@link SchemaStatics}.\n * @remarks\n * Entries can use more specific types than {@link SchemaStatics} requires to be more useful for non-public consumers.\n * Additional non-public members are in {@link schemaStatics}.\n */\nexport const schemaStaticsStable = {\n\tstring: stringSchema,\n\tnumber: numberSchema,\n\tboolean: booleanSchema,\n\tnull: nullSchema,\n\thandle: handleSchema,\n\tleaves: [stringSchema, numberSchema, booleanSchema, nullSchema, handleSchema],\n\n\toptional,\n\n\trequired,\n\n\toptionalRecursive: <\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tt: T,\n\t\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n\t): FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata> => {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Optional, t, {\n\t\t\tdefaultProvider: defaultOptionalProvider,\n\t\t\t...props,\n\t\t});\n\t},\n\n\trequiredRecursive: <\n\t\tconst T extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\t\tconst TCustomMetadata = unknown,\n\t>(\n\t\tt: T,\n\t\tprops?: Omit<FieldPropsAlpha<TCustomMetadata>, \"defaultProvider\">,\n\t): FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata> => {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Required, t, props);\n\t},\n} as const satisfies SchemaStatics;\n\n/**\n * Unstable extensions to {@link schemaStaticsStable}.\n */\nexport const schemaStatics = {\n\t...schemaStaticsStable,\n\tidentifier: <const TCustomMetadata = unknown>(\n\t\tprops?: Omit<FieldProps<TCustomMetadata>, \"defaultProvider\">,\n\t): FieldSchemaAlpha<FieldKind.Identifier, typeof stringSchema, TCustomMetadata> => {\n\t\treturn createFieldSchema(FieldKind.Identifier, stringSchema, props);\n\t},\n} as const;\n\nfunction createFieldSchemaUnsafe<\n\tKind extends FieldKind,\n\tTypes extends System_Unsafe.ImplicitAllowedTypesUnsafe,\n\tTCustomMetadata = unknown,\n>(\n\tkind: Kind,\n\tallowedTypes: Types,\n\tprops?: FieldProps<TCustomMetadata>,\n): FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata> {\n\t// At runtime, we still want this to be a FieldSchema instance, but we can't satisfy its extends clause, so just return it as an FieldSchemaUnsafe\n\treturn createFieldSchema(\n\t\tkind,\n\t\tallowedTypes as ImplicitAllowedTypes & Types,\n\t\tprops,\n\t) as FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata>;\n}\n"]}

package/dist/simple-tree/api/storedSchema.d.ts

@@ -4,13 +4,15 @@
  */
 import type { FluidClientVersion, ICodecOptions } from "../../codec/index.js";
 import type { JsonCompatible } from "../../util/index.js";
-import { type ImplicitFieldSchema } from "../fieldSchema.js";
-import type { SimpleTreeSchema } from "../simpleSchema.js";
+import type { SchemaUpgrade } from "../core/index.js";
+import { type ImplicitAnnotatedFieldSchema, type ImplicitFieldSchema } from "../fieldSchema.js";
 import type { SchemaCompatibilityStatus } from "./tree.js";
 /**
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
  *
  * @param schema - The schema to dump.
+ * @param oldestCompatibleClient - The oldest client version which can read the schema: impacts the format used.
+ * @param includeStaged - filter for selecting which staged allowed types to include in the output.
  *
  * @remarks
  * 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.
@@ -37,7 +39,7 @@ import type { SchemaCompatibilityStatus } from "./tree.js";
  * Public API surface uses "persisted" terminology while internally we use "stored".
  * @alpha
  */
-export declare function extractPersistedSchema(schema: SimpleTreeSchema, oldestCompatibleClient: FluidClientVersion): JsonCompatible;
+export declare function extractPersistedSchema(schema: ImplicitAnnotatedFieldSchema, oldestCompatibleClient: FluidClientVersion, includeStaged: (upgrade: SchemaUpgrade) => boolean): JsonCompatible;
 /**
  * Compares two schema extracted using {@link extractPersistedSchema}.
  * Reports the same compatibility that {@link TreeView.compatibility} would report if

package/dist/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,kBAAkB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQ9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAwB,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,gBAAgB,EACxB,sBAAsB,EAAE,kBAAkB,GACxC,cAAc,CAIhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAUlD"}
+{"version":3,"file":"storedSchema.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQ9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,4BAA4B,EACjC,KAAK,mBAAmB,EACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,4BAA4B,EACpC,sBAAsB,EAAE,kBAAkB,EAC1C,aAAa,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,GAChD,cAAc,CAIhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACrC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,aAAa,GACpB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAUlD"}

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

@@ -16,6 +16,8 @@ const schemaCompatibilityTester_js_1 = require("./schemaCompatibilityTester.js")
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable format.
  *
  * @param schema - The schema to dump.
+ * @param oldestCompatibleClient - The oldest client version which can read the schema: impacts the format used.
+ * @param includeStaged - filter for selecting which staged allowed types to include in the output.
  *
  * @remarks
  * 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.
@@ -42,8 +44,8 @@ const schemaCompatibilityTester_js_1 = require("./schemaCompatibilityTester.js")
  * Public API surface uses "persisted" terminology while internally we use "stored".
  * @alpha
  */
-function extractPersistedSchema(schema, oldestCompatibleClient) {
-    const stored = (0, toStoredSchema_js_1.simpleToStoredSchema)(schema);
+function extractPersistedSchema(schema, oldestCompatibleClient, includeStaged) {
+    const stored = (0, toStoredSchema_js_1.toStoredSchema)(schema, { includeStaged });
     const schemaWriteVersion = (0, index_js_3.clientVersionToSchemaVersion)(oldestCompatibleClient);
     return (0, index_js_2.encodeTreeSchema)(stored, schemaWriteVersion);
 }

package/dist/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;;;AAGH,kDAAoD;AACpD,+DAAqF;AACrF,4EAIuD;AAEvD,sDAAmF;AAEnF,4DAA4D;AAC5D,yDAAgE;AAEhE,iFAA2E;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,sBAAsB,CACrC,MAAwB,EACxB,sBAA0C;IAE1C,MAAM,MAAM,GAAG,IAAA,wCAAoB,EAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,kBAAkB,GAAG,IAAA,uCAA4B,EAAC,sBAAsB,CAAC,CAAC;IAChF,OAAO,IAAA,2BAAgB,EAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AACrD,CAAC;AAPD,wDAOC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,0DAA0D;IAC1D,2JAA2J;IAC3J,MAAM,WAAW,GAAG,IAAA,0BAAe,EAAC,OAAO,EAAE,wBAAa,CAAC,EAAE,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAqB,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,6CAA0B,CAAC;QAC7C,MAAM,EAAE,IAAA,qCAAoB,EAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,wDAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAdD,wDAcC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { FluidClientVersion, ICodecOptions } from \"../../codec/index.js\";\nimport { SchemaVersion } from \"../../core/index.js\";\nimport { encodeTreeSchema, makeSchemaCodec } from \"../../feature-libraries/index.js\";\nimport {\n\tclientVersionToSchemaVersion,\n\ttype FormatV1,\n\t// eslint-disable-next-line import/no-internal-modules\n} from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport { normalizeFieldSchema, type ImplicitFieldSchema } from \"../fieldSchema.js\";\nimport type { SimpleTreeSchema } from \"../simpleSchema.js\";\nimport { simpleToStoredSchema } from \"../toStoredSchema.js\";\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\n\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 *\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: SimpleTreeSchema,\n\toldestCompatibleClient: FluidClientVersion,\n): JsonCompatible {\n\tconst stored = simpleToStoredSchema(schema);\n\tconst schemaWriteVersion = clientVersionToSchemaVersion(oldestCompatibleClient);\n\treturn encodeTreeSchema(stored, schemaWriteVersion);\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\t// Any version can be passed down to makeSchemaCodec here.\n\t// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.\n\tconst schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);\n\tconst stored = schemaCodec.decode(persisted as FormatV1);\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;;;AAGH,kDAAoD;AACpD,+DAAqF;AACrF,4EAIuD;AAGvD,sDAI2B;AAC3B,4DAAsD;AACtD,yDAAgE;AAEhE,iFAA2E;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,sBAAsB,CACrC,MAAoC,EACpC,sBAA0C,EAC1C,aAAkD;IAElD,MAAM,MAAM,GAAG,IAAA,kCAAc,EAAC,MAAM,EAAE,EAAE,aAAa,EAAE,CAAC,CAAC;IACzD,MAAM,kBAAkB,GAAG,IAAA,uCAA4B,EAAC,sBAAsB,CAAC,CAAC;IAChF,OAAO,IAAA,2BAAgB,EAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AACrD,CAAC;AARD,wDAQC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,sBAAsB,CACrC,SAAyB,EACzB,IAAyB,EACzB,OAAsB;IAEtB,0DAA0D;IAC1D,2JAA2J;IAC3J,MAAM,WAAW,GAAG,IAAA,0BAAe,EAAC,OAAO,EAAE,wBAAa,CAAC,EAAE,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAqB,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,IAAI,6CAA0B,CAAC;QAC7C,MAAM,EAAE,IAAA,qCAAoB,EAAC,IAAI,CAAC;KAClC,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,IAAI,wDAAyB,CAAC,MAAM,CAAC,CAAC;IACzD,OAAO,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAdD,wDAcC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { FluidClientVersion, ICodecOptions } from \"../../codec/index.js\";\nimport { SchemaVersion } from \"../../core/index.js\";\nimport { encodeTreeSchema, makeSchemaCodec } from \"../../feature-libraries/index.js\";\nimport {\n\tclientVersionToSchemaVersion,\n\ttype FormatV1,\n\t// eslint-disable-next-line import/no-internal-modules\n} from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { SchemaUpgrade } from \"../core/index.js\";\nimport {\n\tnormalizeFieldSchema,\n\ttype ImplicitAnnotatedFieldSchema,\n\ttype ImplicitFieldSchema,\n} from \"../fieldSchema.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\nimport { TreeViewConfigurationAlpha } from \"./configuration.js\";\n\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 oldestCompatibleClient - 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: ImplicitAnnotatedFieldSchema,\n\toldestCompatibleClient: FluidClientVersion,\n\tincludeStaged: (upgrade: SchemaUpgrade) => boolean,\n): JsonCompatible {\n\tconst stored = toStoredSchema(schema, { includeStaged });\n\tconst schemaWriteVersion = clientVersionToSchemaVersion(oldestCompatibleClient);\n\treturn encodeTreeSchema(stored, schemaWriteVersion);\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\t// Any version can be passed down to makeSchemaCodec here.\n\t// We only use the decode part, which always dispatches to the correct codec based on the version in the data, not the version passed to `makeSchemaCodec`.\n\tconst schemaCodec = makeSchemaCodec(options, SchemaVersion.v1);\n\tconst stored = schemaCodec.decode(persisted as FormatV1);\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/dist/simple-tree/api/treeBeta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"treeBeta.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAKN,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEb,KAAK,QAAQ,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAGzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjE;;;;;;;;OAQG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAEvC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACtE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,WAAW,EAAE,CACZ,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAE3B,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,GAC3D,OAAO,CAAC,KACR,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,QAAQ,EACrE,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/C,MAAM,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,mBAAmB,EAC9C,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACvC,0BAA0B,CAAC,OAAO,CAAC,CAAC;CAoBvC;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QA+BtB,CAAC"}
+{"version":3,"file":"treeBeta.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAKN,KAAK,QAAQ,EACb,KAAK,QAAQ,EAEb,KAAK,QAAQ,EACb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAGzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM9D;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IACjE;;;;;;;;OAQG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAEvC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,GACzD,MAAM,GAAG,MAAM,KAAK,GACpB,MAAM,CACT,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,CACtE,SAAQ,gBAAgB;IACxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,WAAW,EAAE,CACZ,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAE3B,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,CAAC,GAC3D,OAAO,CAAC,KACR,IAAI,CAAC;CACV;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;;;;OAOG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,SAAS,QAAQ,EACrE,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,OAAO,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAC/C,MAAM,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,mBAAmB,EAC9C,IAAI,EAAE,0BAA0B,CAAC,OAAO,CAAC,GACvC,0BAA0B,CAAC,OAAO,CAAC,CAAC;CAoBvC;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAoCtB,CAAC"}

package/dist/simple-tree/api/treeBeta.js

@@ -6,7 +6,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TreeBeta = void 0;
 const index_js_1 = require("../../feature-libraries/index.js");
-const index_js_2 = require("../core/index.js");
+const index_js_2 = require("../../util/index.js");
+const index_js_3 = require("../core/index.js");
 const createContext_js_1 = require("../createContext.js");
 const create_js_1 = require("./create.js");
 const treeNodeApi_js_1 = require("./treeNodeApi.js");
@@ -21,16 +22,21 @@ exports.TreeBeta = {
     },
     clone(node) {
         // The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.
-        if (!(0, index_js_2.isTreeNode)(node)) {
+        if (!(0, index_js_3.isTreeNode)(node)) {
             return node;
         }
-        const kernel = (0, index_js_2.getKernel)(node);
+        const kernel = (0, index_js_3.getKernel)(node);
         const cursor = kernel.getOrCreateInnerNode().borrowCursor();
         // To handle when the node transitively contains unknown optional fields,
         // derive the context from the source node's stored schema which has stored schema for any such fields and their contents.
-        const flexContext = new index_js_2.UnhydratedContext(index_js_1.defaultSchemaPolicy, kernel.context.flexContext.schema);
-        const context = new index_js_2.Context(flexContext, (0, createContext_js_1.getUnhydratedContext)(kernel.schema).schema);
-        return (0, create_js_1.createFromCursor)(kernel.schema, cursor, context);
+        const flexContext = new index_js_3.UnhydratedContext(index_js_1.defaultSchemaPolicy, kernel.context.flexContext.schema);
+        const context = new index_js_3.Context(flexContext, (0, createContext_js_1.getUnhydratedContext)(kernel.schema).schema);
+        const fieldSchema = {
+            kind: index_js_1.FieldKinds.required.identifier,
+            types: new Set([(0, index_js_2.brand)(kernel.schema.identifier)]),
+            persistedMetadata: undefined,
+        };
+        return (0, create_js_1.createFromCursor)(kernel.schema, cursor, fieldSchema, context);
     },
 };
 //# sourceMappingURL=treeBeta.js.map

package/dist/simple-tree/api/treeBeta.js.map

@@ -1 +1 @@
-{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,+DAAuE;AACvE,+CAS0B;AAC1B,0DAA2D;AAG3D,2CAA+C;AAE/C,qDAA+C;AA4I/C;;;;GAIG;AACU,QAAA,QAAQ,GAAa;IACjC,EAAE,CACD,IAAW,EACX,SAAY,EACZ,QAAiD;QAEjD,OAAO,4BAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,CACJ,IAAyC;QAEzC,mIAAmI;QACnI,IAAI,CAAC,IAAA,qBAAU,EAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,oBAAS,EAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC,YAAY,EAAE,CAAC;QAE5D,yEAAyE;QACzE,0HAA0H;QAC1H,MAAM,WAAW,GAAG,IAAI,4BAAiB,CACxC,8BAAmB,EACnB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CACjC,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,kBAAO,CAAC,WAAW,EAAE,IAAA,uCAAoB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;QAErF,OAAO,IAAA,4BAAgB,EAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAErD,CAAC;IACH,CAAC;CACD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { defaultSchemaPolicy } from \"../../feature-libraries/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type { ImplicitFieldSchema, TreeFieldFromImplicitField } from \"../fieldSchema.js\";\n\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/**\n * Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n */\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t *\n\t * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t *\n\t * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t */\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/**\n * Extensions to {@link TreeChangeEvents} which are not yet stable.\n *\n * @sealed @beta\n */\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t *\n\t * 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.\n\t */\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/**\n * Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @system @sealed @beta\n */\nexport interface TreeBeta {\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/**\n\t * Clones the persisted data associated with a node.\n\t *\n\t * @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t *\n\t * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t *\n\t * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t *\n\t * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t *\n\t * - If the node (or any node in its subtree) contains {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t */\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /**\n\t//  * Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t//  * @remarks\n\t//  * This only clones the persisted data associated with a node.\n\t//  * Local state, such as properties added to customized schema classes, will not be cloned:\n\t//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t//  */\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/**\n\t// \t\t * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t */\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n}\n\n/**\n * Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getOrCreateInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\treturn createFromCursor(kernel.schema, cursor, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n};\n"]}
+{"version":3,"file":"treeBeta.js","sourceRoot":"","sources":["../../../src/simple-tree/api/treeBeta.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,+DAAmF;AACnF,kDAA4C;AAC5C,+CAS0B;AAC1B,0DAA2D;AAG3D,2CAA+C;AAE/C,qDAA+C;AA4I/C;;;;GAIG;AACU,QAAA,QAAQ,GAAa;IACjC,EAAE,CACD,IAAW,EACX,SAAY,EACZ,QAAiD;QAEjD,OAAO,4BAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,CACJ,IAAyC;QAEzC,mIAAmI;QACnI,IAAI,CAAC,IAAA,qBAAU,EAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,oBAAS,EAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,CAAC,YAAY,EAAE,CAAC;QAE5D,yEAAyE;QACzE,0HAA0H;QAC1H,MAAM,WAAW,GAAG,IAAI,4BAAiB,CACxC,8BAAmB,EACnB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CACjC,CAAC;QACF,MAAM,OAAO,GAAG,IAAI,kBAAO,CAAC,WAAW,EAAE,IAAA,uCAAoB,EAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;QAErF,MAAM,WAAW,GAA0B;YAC1C,IAAI,EAAE,qBAAU,CAAC,QAAQ,CAAC,UAAU;YACpC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,IAAA,gBAAK,EAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACjD,iBAAiB,EAAE,SAAS;SAC5B,CAAC;QACF,OAAO,IAAA,4BAAgB,EAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAElE,CAAC;IACH,CAAC;CACD,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { TreeFieldStoredSchema } from \"../../core/index.js\";\nimport { defaultSchemaPolicy, FieldKinds } from \"../../feature-libraries/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\tContext,\n\tgetKernel,\n\tisTreeNode,\n\tUnhydratedContext,\n\ttype NodeKind,\n\ttype TreeNode,\n\ttype Unhydrated,\n\ttype WithType,\n} from \"../core/index.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\nimport type { ImplicitFieldSchema, TreeFieldFromImplicitField } from \"../fieldSchema.js\";\n\nimport { createFromCursor } from \"./create.js\";\nimport type { TreeChangeEvents } from \"./treeChangeEvents.js\";\nimport { treeNodeApi } from \"./treeNodeApi.js\";\n\n// Tests for this file are grouped with those for treeNodeApi.ts as that is where this functionality will eventually land,\n// and where most of the actual implementation is for much of it.\n\n/**\n * Data included for {@link TreeChangeEventsBeta.nodeChanged}.\n * @sealed @beta\n */\nexport interface NodeChangedData<TNode extends TreeNode = TreeNode> {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t *\n\t * Set to `undefined` when the {@link NodeKind} does not support this feature (currently just ArrayNodes).\n\t *\n\t * When defined, the set should never be empty, since `nodeChanged` will only be triggered when there is a change, and for the supported node types, the only things that can change are properties.\n\t */\n\treadonly changedProperties?: ReadonlySet<\n\t\t// For Object nodes, make changedProperties required and strongly typed with the property names from the schema:\n\t\tTNode extends WithType<string, NodeKind.Object, infer TInfo>\n\t\t\t? string & keyof TInfo\n\t\t\t: string\n\t>;\n}\n\n/**\n * Extensions to {@link TreeChangeEvents} which are not yet stable.\n *\n * @sealed @beta\n */\nexport interface TreeChangeEventsBeta<TNode extends TreeNode = TreeNode>\n\textends TreeChangeEvents {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - Object nodes define a change as being when the value of one of its properties changes (i.e., the property's value is set, including when set to `undefined`).\n\t *\n\t * - Array nodes define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: define and document event ordering (ex: bottom up, with nodeChanged before treeChange on each level).\n\t *\n\t * 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.\n\t */\n\tnodeChanged: (\n\t\tdata: NodeChangedData<TNode> &\n\t\t\t// Make the properties of object, map, and record nodes required:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object | NodeKind.Record>\n\t\t\t\t? Required<Pick<NodeChangedData<TNode>, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t) => void;\n}\n\n/**\n * Extensions to {@link (Tree:interface)} which are not yet stable.\n * @remarks\n * Use via the {@link (TreeBeta:variable)} singleton.\n * @system @sealed @beta\n */\nexport interface TreeBeta {\n\t/**\n\t * Register an event listener on the given node.\n\t * @param node - The node whose events should be subscribed to.\n\t * @param eventName - Which event to subscribe to.\n\t * @param listener - The callback to trigger for the event. The tree can be read during the callback, but it is invalid to modify the tree during this callback.\n\t * @returns A callback function which will deregister the event.\n\t * This callback should be called only once.\n\t */\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void;\n\n\t/**\n\t * Clones the persisted data associated with a node.\n\t *\n\t * @param node - The node to clone.\n\t * @returns A new unhydrated node with the same persisted data as the original node.\n\t * @remarks\n\t * Some key things to note:\n\t *\n\t * - Local state, such as properties added to customized schema classes, will not be cloned. However, they will be\n\t * initialized to their default state just as if the node had been created via its constructor.\n\t *\n\t * - Value node types (i.e., numbers, strings, booleans, nulls and Fluid handles) will be returned as is.\n\t *\n\t * - The identifiers in the node's subtree will be preserved, i.e., they are not replaced with new values.\n\t *\n\t * - If the node (or any node in its subtree) contains {@link SchemaFactoryObjectOptions.allowUnknownOptionalFields|unknown optional fields},\n\t * those fields will be cloned just like the known fields.\n\t */\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): TreeFieldFromImplicitField<TSchema>;\n\n\t// TODO: support more clone options\n\t// /**\n\t//  * Like {@link (TreeBeta:interface).create}, except deeply clones existing nodes.\n\t//  * @remarks\n\t//  * This only clones the persisted data associated with a node.\n\t//  * Local state, such as properties added to customized schema classes, will not be cloned:\n\t//  * they will be initialized however they end up after running the constructor, just like if a remote client had inserted the same nodes.\n\t//  */\n\t// clone<const TSchema extends ImplicitFieldSchema>(\n\t// \toriginal: TreeFieldFromImplicitField<TSchema>,\n\t// \toptions?: {\n\t// \t\t/**\n\t// \t\t * If set, all identifier's in the cloned tree (See {@link SchemaFactory.identifier}) will be replaced with new ones allocated using the default identifier allocation schema.\n\t// \t\t * Otherwise any identifiers will be preserved as is.\n\t// \t\t */\n\t// \t\treplaceIdentifiers?: true;\n\t// \t},\n\t// ): TreeFieldFromImplicitField<TSchema>;\n}\n\n/**\n * Extensions to {@link (Tree:variable)} which are not yet stable.\n * @see {@link (TreeBeta:interface)}.\n * @beta\n */\nexport const TreeBeta: TreeBeta = {\n\ton<K extends keyof TreeChangeEventsBeta<TNode>, TNode extends TreeNode>(\n\t\tnode: TNode,\n\t\teventName: K,\n\t\tlistener: NoInfer<TreeChangeEventsBeta<TNode>[K]>,\n\t): () => void {\n\t\treturn treeNodeApi.on(node, eventName, listener);\n\t},\n\tclone<const TSchema extends ImplicitFieldSchema>(\n\t\tnode: TreeFieldFromImplicitField<TSchema>,\n\t): Unhydrated<TreeFieldFromImplicitField<TSchema>> {\n\t\t// The only non-TreeNode cases are {@link TreeLeafValue} and `undefined` (for an empty optional field) which can be returned as is.\n\t\tif (!isTreeNode(node)) {\n\t\t\treturn node;\n\t\t}\n\n\t\tconst kernel = getKernel(node);\n\t\tconst cursor = kernel.getOrCreateInnerNode().borrowCursor();\n\n\t\t// To handle when the node transitively contains unknown optional fields,\n\t\t// derive the context from the source node's stored schema which has stored schema for any such fields and their contents.\n\t\tconst flexContext = new UnhydratedContext(\n\t\t\tdefaultSchemaPolicy,\n\t\t\tkernel.context.flexContext.schema,\n\t\t);\n\t\tconst context = new Context(flexContext, getUnhydratedContext(kernel.schema).schema);\n\n\t\tconst fieldSchema: TreeFieldStoredSchema = {\n\t\t\tkind: FieldKinds.required.identifier,\n\t\t\ttypes: new Set([brand(kernel.schema.identifier)]),\n\t\t\tpersistedMetadata: undefined,\n\t\t};\n\t\treturn createFromCursor(kernel.schema, cursor, fieldSchema, context) as Unhydrated<\n\t\t\tTreeFieldFromImplicitField<TSchema>\n\t\t>;\n\t},\n};\n"]}