@fluidframework/tree 2.4.0 → 2.5.0

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

@@ -1 +1 @@
-{"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactory.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, unreachableCase } from \"@fluidframework/core-utils/internal\";\n// Include this unused import to avoid TypeScript generating an inline import for IFluidHandle in the d.ts file\n// which degrades the API-Extractor report quality since API-Extractor can not tell the inline import is the same as the non-inline one.\n// eslint-disable-next-line unused-imports/no-unused-imports\nimport type { IFluidHandle as _dummyImport } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\n\nimport type { TreeValue } from \"../../core/index.js\";\nimport type { NodeKeyManager } from \"../../feature-libraries/index.js\";\nimport {\n\ttype RestrictiveStringRecord,\n\tgetOrCreate,\n\tisReadonlyArray,\n} from \"../../util/index.js\";\n\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tLeafNodeSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport {\n\tFieldKind,\n\ttype FieldSchema,\n\ttype ImplicitAllowedTypes,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeNodeFromImplicitAllowedTypes,\n\ttype FieldProps,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n\tgetDefaultProvider,\n} from \"../schemaTypes.js\";\nimport { inPrototypeChain } from \"../core/index.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tTreeNodeSchemaBoth,\n} from \"../core/index.js\";\nimport { type TreeArrayNode, arraySchema } from \"../arrayNode.js\";\nimport {\n\ttype InsertableObjectFromSchemaRecord,\n\ttype TreeObjectNode,\n\tobjectSchema,\n} from \"../objectNode.js\";\nimport { type MapNodeInsertableData, type TreeMapNode, mapSchema } from \"../mapNode.js\";\nimport type {\n\tFieldSchemaUnsafe,\n\t// Adding these unused imports makes the generated d.ts file produced by TypeScript stop breaking API-Extractor's rollup generation.\n\t// Without this import, TypeScript generates inline `import(\"../..\")` statements in the d.ts file,\n\t// which API-Extractor leaves as is when generating the rollup, leaving them pointing at the wrong directory.\n\t// API-Extractor issue: https://github.com/microsoft/rushstack/issues/4507\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\tFieldHasDefaultUnsafe,\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\tInsertableTreeFieldFromImplicitFieldUnsafe,\n\tInsertableObjectFromSchemaRecordUnsafe,\n\tInsertableTreeNodeFromImplicitAllowedTypesUnsafe,\n\tTreeArrayNodeUnsafe,\n\tTreeMapNodeUnsafe,\n\tTreeObjectNodeUnsafe,\n\tUnenforced,\n} from \"./typesUnsafe.js\";\nimport { createFieldSchemaUnsafe } from \"./schemaFactoryRecursive.js\";\nimport { TreeNodeValid } from \"../treeNodeValid.js\";\nimport { isLazy } from \"../flexList.js\";\n/**\n * Gets the leaf domain schema compatible with a given {@link TreeValue}.\n */\nexport function schemaFromValue(value: TreeValue): TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema;\n\t\tcase \"number\":\n\t\t\treturn numberSchema;\n\t\tcase \"string\":\n\t\t\treturn stringSchema;\n\t\tcase \"object\": {\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tassert(isFluidHandle(value), 0x87e /* invalid TreeValue */);\n\t\t\treturn handleSchema;\n\t\t}\n\t\tdefault:\n\t\t\tunreachableCase(value);\n\t}\n}\n\n/**\n * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.\n *\n * @system @public\n */\nexport type ScopedSchemaName<\n\tTScope extends string | undefined,\n\tTName extends number | string,\n> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;\n// > = `${TScope extends undefined ? \"\" : `${TScope}.`}${TName}`;\n\n// TODO:\n// SchemaFactory.array references should link to the correct overloads, however the syntax for this does not seems to work currently for methods unless the they are not qualified with the class.\n// API-Extractor requires such links to be qualified with the class, so it can't work.\n// Since linking the overload set as a whole also doesn't work, these have been made non-links for now.\n/**\n * Creates various types of {@link TreeNodeSchema|schema} for {@link TreeNode}s.\n *\n * @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.\n * @typeParam TName - Type of names used to identify each schema produced in this factory.\n * Typically this is just `string` but it is also possible to use `string` or `number` based enums if you prefer to identify your types that way.\n *\n * @remarks\n * All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.\n * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.\n * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.\n * Therefor two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.\n * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances\n * and it is an error to use both in the same tree (since their identifiers are not unique).\n *\n * Note:\n * POJO stands for Plain Old JavaScript Object.\n * This means an object that works like a `{}` style object literal.\n * In this case it means the prototype is `Object.prototype` and acts like a set of key value pairs (data, not methods).\n * The usage below generalizes this to include array and map like objects as well.\n *\n * There are two ways to use these APIs:\n *\n * Customizable Approach:\n *\n * 1. Declaration: `class X extends schemaFactory.object(\"x\", {}) {}`\n *\n * 2. Allows adding \"local\" (non-persisted) members: Yes. Members (including methods) can be added to the class.\n *\n * 3. Prototype: The user-defined class.\n *\n * 4. Structurally named Schema: Not Supported.\n *\n * 5. Explicitly named Objects: Supported.\n *\n * 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.\n *\n * 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.\n *\n * 8. IntelliSense: Shows and links to user-defined class by name: `X`.\n *\n * 9. Recursion: Supported with special declaration patterns.\n *\n * POJO Emulation Approach:\n *\n * 1. Declaration: `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>;`\n *\n * 2. Allows adding \"local\" (non-persisted) members: No. Attempting to set non-field members will result in an error.\n *\n * 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.\n *\n * 4. Structurally named Schema: Supported.\n *\n * 5. Explicitly named Objects: Supported.\n *\n * 6. Explicitly named Maps and Arrays: Not Supported.\n *\n * 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.\n *\n * 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">`.\n *\n * 9. Recursion: Unsupported: Generated `.d.ts` files replace recursive references with `any`, breaking the use of recursive schema across compilation boundaries.\n *\n * Note that while \"POJO Emulation\" nodes act a lot like POJO objects, they are not true POJO objects:\n *\n * - Adding new arbitrary fields will error, as well some cases of invalid edits.\n *\n * - They are implemented using proxies.\n *\n * - They have state that is not exposed via enumerable own properties, including a {@link TreeNodeSchema}.\n * This makes libraries like node.js `assert.deepEqual` fail to detect differences in type.\n *\n * - Assigning members has side effects (in this case editing the persisted/shared tree).\n *\n * - Not all operations implied by the prototype will work correctly: stick to the APIs explicitly declared in the TypeScript types.\n *\n * @privateRemarks\n * It's perfectly possible to make `POJO Emulation` mode (or even just hiding the prototype) selectable even when using the custom user class declaration syntax.\n * When doing this, it's still possible to make `instanceof` perform correctly.\n * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.\n * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.\n *\n * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.\n *\n * @sealed @public\n */\nexport class SchemaFactory<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> {\n\t/**\n\t * TODO:\n\t * If users of this generate the same name because two different schema with the same identifier were used,\n\t * the second use can get a cache hit, and reference the wrong schema.\n\t * Such usage should probably return a distinct type or error but currently does not.\n\t * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.\n\t */\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\n\t/**\n\t * Construct a SchemaFactory with a given scope.\n\t * @remarks\n\t * There are no restrictions on mixing schema from different schema factories:\n\t * this is encouraged when a single schema references schema from different libraries.\n\t * If each library exporting schema picks its own globally unique scope for its SchemaFactory,\n\t * then all schema an application might depend on, directly or transitively,\n\t * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.\n\t *\n\t * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.\n\t * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.\n\t * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.\n\t */\n\tpublic constructor(public readonly scope: TScope) {}\n\n\tprivate scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {\n\t\treturn (\n\t\t\tthis.scope === undefined ? `${name}` : `${this.scope}.${name}`\n\t\t) as ScopedSchemaName<TScope, Name>;\n\t}\n\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\tpublic readonly string = stringSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a JavaScript `number`.\n\t *\n\t * @remarks\n\t * The number is a [double-precision 64-bit binary format IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) value, however there are some exceptions:\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 * - `-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\tpublic readonly number = numberSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a boolean.\n\t */\n\tpublic readonly boolean = booleanSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for JavaScript `null`.\n\t *\n\t * @remarks\n\t * There are good [reasons to avoid using null](https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-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\tpublic readonly null = nullSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.\n\t */\n\tpublic readonly handle = handleSchema;\n\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t */\n\tpublic object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\treturn objectSchema(this.scoped(name), fields, true);\n\t}\n\n\t/**\n\t * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t *\n\t * @remarks\n\t * The unique identifier for this Map is defined as a function of the provided types.\n\t * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t *\n\t * If using these structurally named maps, other types in this schema builder should avoid names of the form `Map<${string}>`.\n\t *\n\t * @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyMap = factory.map(factory.number);\n\t * type MyMap = NodeFromSchema<typeof MyMap>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myMap: factory.map(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * See note on array.\n\t */\n\tpublic map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic map<Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\t/**\n\t * @privateRemarks\n\t * This should return `TreeNodeSchemaBoth`, however TypeScript gives an error if one of the overloads implicitly up-casts the return type of the implementation.\n\t * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload\n\t * and the implementation is type safe, and forcing an unsafe typing instead.\n\t */\n\tpublic map<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<string, NodeKind.Map, TreeMapNode<T>, MapNodeInsertableData<T>, true, T> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Map\", types);\n\t\t\treturn getOrCreate(\n\t\t\t\tthis.structuralTypes,\n\t\t\t\tfullName,\n\t\t\t\t() =>\n\t\t\t\t\tthis.namedMap(\n\t\t\t\t\t\tfullName as TName,\n\t\t\t\t\t\tnameOrAllowedTypes as T,\n\t\t\t\t\t\tfalse,\n\t\t\t\t\t\ttrue,\n\t\t\t\t\t) as TreeNodeSchema,\n\t\t\t) as TreeNodeSchemaBoth<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tMapNodeInsertableData<T>,\n\t\t\t\ttrue,\n\t\t\t\tT\n\t\t\t>;\n\t\t}\n\t\t// To actually have type safety, assign to the type this method should return before implicitly upcasting when returning.\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tstring,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T>,\n\t\t\tMapNodeInsertableData<T>,\n\t\t\ttrue,\n\t\t\tT\n\t\t> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true);\n\t\treturn out;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link (TreeMapNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t */\n\tprivate namedMap<\n\t\tName extends TName | string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\tImplicitlyConstructable,\n\t\tT\n\t> {\n\t\treturn mapSchema(\n\t\t\tthis.scoped(name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\t// The current policy is customizable nodes don't get fake prototypes.\n\t\t\t!customizable,\n\t\t);\n\t}\n\n\t/**\n\t * Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @remarks\n\t * The identifier for this Array is defined as a function of the provided types.\n\t * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t *\n\t * If using these structurally named arrays, other types in this schema builder should avoid names of the form `Array<${string}>`.\n\t *\n\t * @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyArray = factory.array(factory.number);\n\t * type MyArray = NodeFromSchema<typeof MyArray>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myArray: factory.array(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * The name produced at the type level here is not as specific as it could be, however doing type level sorting and escaping is a real mess.\n\t * There are cases where not having this full type provided will be less than ideal since TypeScript's structural types.\n\t * For example attempts to narrow unions of structural arrays by name won't work.\n\t * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,\n\t * though there may still be some problematic cases even after that work is done.\n\t *\n\t * The return value is a class, but its the type is intentionally not specific enough to indicate it is a class.\n\t * This prevents callers of this from sub-classing it, which is unlikely to work well (due to the ease of accidentally giving two different calls o this different subclasses)\n\t * when working with structural typing.\n\t *\n\t * {@label STRUCTURAL}\n\t */\n\tpublic array<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\t/**\n\t * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedArray extends factory.array(\"name\", factory.number) {}\n\t * ```\n\t *\n\t * {@label NAMED}\n\t */\n\tpublic array<const Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\t/**\n\t * @privateRemarks\n\t * This should return TreeNodeSchemaBoth: see note on \"map\" implementation for details.\n\t */\n\tpublic array<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, string>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Array\", types);\n\t\t\treturn getOrCreate(this.structuralTypes, fullName, () =>\n\t\t\t\tthis.namedArray(fullName, nameOrAllowedTypes as T, false, true),\n\t\t\t) as TreeNodeSchemaClass<\n\t\t\t\tScopedSchemaName<TScope, string>,\n\t\t\t\tNodeKind.Array,\n\t\t\t\tTreeArrayNode<T>,\n\t\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t\ttrue,\n\t\t\t\tT\n\t\t\t>;\n\t\t}\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tScopedSchemaName<TScope, string>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\ttrue,\n\t\t\tT\n\t\t> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true);\n\t\treturn out;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @remarks\n\t * This is not intended to be used directly, use the overload of `array` which takes a name instead.\n\t * This is only public to work around a compiler limitation.\n\t */\n\tprivate namedArray<\n\t\tName extends TName | string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable,\n\t\tT\n\t> {\n\t\treturn arraySchema(this.scoped(name), allowedTypes, implicitlyConstructable, customizable);\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\tpublic 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\t\tconst defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {\n\t\t\treturn undefined;\n\t\t});\n\t\treturn createFieldSchema(FieldKind.Optional, t, {\n\t\t\tdefaultProvider: defaultOptionalProvider,\n\t\t\t...props,\n\t\t});\n\t}\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\tpublic 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\t\treturn createFieldSchema(FieldKind.Required, t, props);\n\t}\n\n\t/**\n\t * {@link SchemaFactory.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 SchemaFactory.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\tpublic optionalRecursive<const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps, \"defaultProvider\">,\n\t): FieldSchemaUnsafe<FieldKind.Optional, T> {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Optional, t, props);\n\t}\n\n\t/**\n\t * {@link SchemaFactory.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 SchemaFactory.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\tpublic requiredRecursive<const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps, \"defaultProvider\">,\n\t): FieldSchemaUnsafe<FieldKind.Required, T> {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Required, t, props);\n\t}\n\n\t/**\n\t * A special field which holds a unique identifier for an object node.\n\t * @remarks\n\t * The value of this field, a \"node identifier\", uniquely identifies a node among all other nodes in the tree.\n\t * Node identifiers are strings, and can therefore be used as lookup keys in maps or written to a database.\n\t * When the node is constructed, the identifier field does not need to be populated.\n\t * The SharedTree will provide an identifier for the node automatically.\n\t * An identifier provided automatically by the SharedTree has the following properties:\n\t * - It is a UUID.\n\t * - It is compressed to a space-efficient representation when stored in the document.\n\t * - A compressed form of the identifier can be accessed at runtime via the `Tree.shortId()` API.\n\t * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into the tree.\n\t *\n\t * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).\n\t * In that case, it is up to the user to ensure that the identifier is unique within the current tree - no other node should have the same identifier at the same time.\n\t * If the identifier is not unique, it may be read, but may cause libraries or features which operate over node identifiers to misbehave.\n\t * User-supplied identifiers may be read immediately, even before insertion into the tree.\n\t *\n\t * A node may have more than one identifier field (though note that this precludes the use of the `Tree.shortId()` API).\n\t */\n\tpublic get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {\n\t\tconst defaultIdentifierProvider: DefaultProvider = getDefaultProvider(\n\t\t\t(nodeKeyManager: NodeKeyManager) => {\n\t\t\t\treturn nodeKeyManager.stabilizeNodeKey(nodeKeyManager.generateLocalNodeKey());\n\t\t\t},\n\t\t);\n\t\treturn createFieldSchema(FieldKind.Identifier, this.string, {\n\t\t\tdefaultProvider: defaultIdentifierProvider,\n\t\t});\n\t}\n\n\t/**\n\t * {@link SchemaFactory.object} 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 SchemaFactory.object} 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\t * Additionally `ImplicitlyConstructable` is disabled (forcing use of constructor) to avoid\n\t * `error TS2589: Type instantiation is excessively deep and possibly infinite.`\n\t * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,\n\t>(name: Name, t: T) {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.object(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tTreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/**\n\t * `SchemaFactory.array` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<ImplicitAllowedTypes>,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst RecursiveArray = this.namedArray(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t);\n\n\t\treturn RecursiveArray as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\t\t{\n\t\t\t\t/**\n\t\t\t\t * Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t *\n\t\t\t\t * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t */\n\t\t\t\t[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/**\n\t * `SchemaFactory.map` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.map` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t) {\n\t\tconst MapSchema = this.namedMap(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t);\n\n\t\treturn MapSchema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\t\t{\n\t\t\t\t/**\n\t\t\t\t * Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t *\n\t\t\t\t * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t */\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t>;\n\t\t\t},\n\t\t\t// Ideally this would be included, but doing so breaks recursive types.\n\t\t\t// | RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n}\n\nexport function structuralName<const T extends string>(\n\tcollectionName: T,\n\tallowedTypes: TreeNodeSchema | readonly TreeNodeSchema[],\n): `${T}<${string}>` {\n\tlet inner: string;\n\tif (!isReadonlyArray(allowedTypes)) {\n\t\treturn structuralName(collectionName, [allowedTypes]);\n\t} else {\n\t\tconst names = allowedTypes.map((t): string => {\n\t\t\t// Ensure that lazy types (functions) don't slip through here.\n\t\t\tassert(!isLazy(t), 0x83d /* invalid type provided */);\n\t\t\tmarkSchemaMostDerived(t);\n\t\t\treturn t.identifier;\n\t\t});\n\t\t// Ensure name is order independent\n\t\tnames.sort();\n\t\t// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.\n\t\t// Using JSON is a simple way to accomplish this.\n\t\t// The outer `[]` around the result were needed so that a single type name \"Any\" would not collide with the \"any\" case which used to exist.\n\t\tinner = JSON.stringify(names);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n\n/**\n * Indicates that a schema is the \"most derived\" version which is allowed to be used, see {@link MostDerivedData}.\n * Calling helps with error messages about invalid schema usage (using more than one type from single schema factor produced type,\n * and thus calling this for one than one subclass).\n * @remarks\n * Helper for invoking {@link TreeNodeValid.markMostDerived} for any {@link TreeNodeSchema} if it needed.\n */\nexport function markSchemaMostDerived(schema: TreeNodeSchema): void {\n\tif (schema instanceof LeafNodeSchema) {\n\t\treturn;\n\t}\n\n\tif (!inPrototypeChain(schema, TreeNodeValid)) {\n\t\t// Use JSON.stringify to quote and escape identifier string.\n\t\tthrow new UsageError(\n\t\t\t`Schema for ${JSON.stringify(\n\t\t\t\tschema.identifier,\n\t\t\t)} does not extend a SchemaFactory generated class. This is invalid.`,\n\t\t);\n\t}\n\n\t(schema as typeof TreeNodeValid & TreeNodeSchema).markMostDerived();\n}\n"]}
+{"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../../src/simple-tree/api/schemaFactory.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert, unreachableCase } from \"@fluidframework/core-utils/internal\";\n// Include this unused import to avoid TypeScript generating an inline import for IFluidHandle in the d.ts file\n// which degrades the API-Extractor report quality since API-Extractor can not tell the inline import is the same as the non-inline one.\n// eslint-disable-next-line unused-imports/no-unused-imports\nimport type { IFluidHandle as _dummyImport } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\n\nimport type { TreeValue } from \"../../core/index.js\";\nimport type { NodeKeyManager } from \"../../feature-libraries/index.js\";\nimport {\n\ttype RestrictiveStringRecord,\n\tgetOrCreate,\n\tisReadonlyArray,\n} from \"../../util/index.js\";\n\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tLeafNodeSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport {\n\tFieldKind,\n\ttype FieldSchema,\n\ttype ImplicitAllowedTypes,\n\ttype ImplicitFieldSchema,\n\ttype InsertableTreeNodeFromImplicitAllowedTypes,\n\ttype FieldProps,\n\tcreateFieldSchema,\n\ttype DefaultProvider,\n\tgetDefaultProvider,\n} from \"../schemaTypes.js\";\nimport { inPrototypeChain } from \"../core/index.js\";\nimport type {\n\tNodeKind,\n\tWithType,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tTreeNodeSchemaBoth,\n} from \"../core/index.js\";\nimport { type TreeArrayNode, arraySchema } from \"../arrayNode.js\";\nimport {\n\ttype InsertableObjectFromSchemaRecord,\n\ttype TreeObjectNode,\n\tobjectSchema,\n} from \"../objectNode.js\";\nimport { type MapNodeInsertableData, type TreeMapNode, mapSchema } from \"../mapNode.js\";\nimport type {\n\tFieldSchemaUnsafe,\n\t// Adding these unused imports makes the generated d.ts file produced by TypeScript stop breaking API-Extractor's rollup generation.\n\t// Without this import, TypeScript generates inline `import(\"../..\")` statements in the d.ts file,\n\t// which API-Extractor leaves as is when generating the rollup, leaving them pointing at the wrong directory.\n\t// API-Extractor issue: https://github.com/microsoft/rushstack/issues/4507\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\tFieldHasDefaultUnsafe,\n\t// eslint-disable-next-line unused-imports/no-unused-imports, @typescript-eslint/no-unused-vars\n\tInsertableTreeFieldFromImplicitFieldUnsafe,\n\tInsertableObjectFromSchemaRecordUnsafe,\n\tInsertableTreeNodeFromImplicitAllowedTypesUnsafe,\n\tTreeArrayNodeUnsafe,\n\tTreeMapNodeUnsafe,\n\tTreeObjectNodeUnsafe,\n\tUnenforced,\n} from \"./typesUnsafe.js\";\nimport { createFieldSchemaUnsafe } from \"./schemaFactoryRecursive.js\";\nimport { TreeNodeValid } from \"../treeNodeValid.js\";\nimport { isLazy } from \"../flexList.js\";\n/**\n * Gets the leaf domain schema compatible with a given {@link TreeValue}.\n */\nexport function schemaFromValue(value: TreeValue): TreeNodeSchema {\n\tswitch (typeof value) {\n\t\tcase \"boolean\":\n\t\t\treturn booleanSchema;\n\t\tcase \"number\":\n\t\t\treturn numberSchema;\n\t\tcase \"string\":\n\t\t\treturn stringSchema;\n\t\tcase \"object\": {\n\t\t\tif (value === null) {\n\t\t\t\treturn nullSchema;\n\t\t\t}\n\t\t\tassert(isFluidHandle(value), 0x87e /* invalid TreeValue */);\n\t\t\treturn handleSchema;\n\t\t}\n\t\tdefault:\n\t\t\tunreachableCase(value);\n\t}\n}\n\n/**\n * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.\n *\n * @system @public\n */\nexport type ScopedSchemaName<\n\tTScope extends string | undefined,\n\tTName extends number | string,\n> = TScope extends undefined ? `${TName}` : `${TScope}.${TName}`;\n// > = `${TScope extends undefined ? \"\" : `${TScope}.`}${TName}`;\n\n// TODO:\n// SchemaFactory.array references should link to the correct overloads, however the syntax for this does not seems to work currently for methods unless the they are not qualified with the class.\n// API-Extractor requires such links to be qualified with the class, so it can't work.\n// Since linking the overload set as a whole also doesn't work, these have been made non-links for now.\n/**\n * Creates various types of {@link TreeNodeSchema|schema} for {@link TreeNode}s.\n *\n * @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.\n * @typeParam TName - Type of names used to identify each schema produced in this factory.\n * Typically this is just `string` but it is also possible to use `string` or `number` based enums if you prefer to identify your types that way.\n *\n * @remarks\n * For details related to inputting data constrained by schema (including via assignment), and how non-exact schema types are handled in general refer to {@link Input}.\n * For information about recursive schema support, see methods postfixed with \"recursive\" and {@link ValidateRecursiveSchema}.\n * To apply schema defined with this factory to a tree, see {@link ViewableTree.viewWith} and {@link TreeViewConfiguration}.\n *\n * All schema produced by this factory get a {@link TreeNodeSchemaCore.identifier|unique identifier} by combining the {@link SchemaFactory.scope} with the schema's `Name`.\n * The `Name` part may be explicitly provided as a parameter, or inferred as a structural combination of the provided types.\n * The APIs which use this second approach, structural naming, also deduplicate all equivalent calls.\n * Therefor two calls to `array(allowedTypes)` with the same allowedTypes will return the same {@link TreeNodeSchema} instance.\n * On the other hand, two calls to `array(name, allowedTypes)` will always return different {@link TreeNodeSchema} instances\n * and it is an error to use both in the same tree (since their identifiers are not unique).\n *\n * Note:\n * POJO stands for Plain Old JavaScript Object.\n * This means an object that works like a `{}` style object literal.\n * In this case it means the prototype is `Object.prototype` and acts like a set of key value pairs (data, not methods).\n * The usage below generalizes this to include array and map like objects as well.\n *\n * There are two ways to use these APIs:\n *\n * Customizable Approach:\n *\n * 1. Declaration: `class X extends schemaFactory.object(\"x\", {}) {}`\n *\n * 2. Allows adding \"local\" (non-persisted) members: Yes. Members (including methods) can be added to the class.\n *\n * 3. Prototype: The user-defined class.\n *\n * 4. Structurally named Schema: Not Supported.\n *\n * 5. Explicitly named Objects: Supported.\n *\n * 6. Explicitly named Maps and Arrays: Supported: Both declaration approaches can be used.\n *\n * 7. Node.js `assert.deepEqual`: Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields.\n *\n * 8. IntelliSense: Shows and links to user-defined class by name: `X`.\n *\n * 9. Recursion: Supported with special declaration patterns.\n *\n * POJO Emulation Approach:\n *\n * 1. Declaration: `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>;`\n *\n * 2. Allows adding \"local\" (non-persisted) members: No. Attempting to set non-field members will result in an error.\n *\n * 3. Prototype: `Object.prototype`, `Map.prototype`, or `Array.prototype` depending on node kind.\n *\n * 4. Structurally named Schema: Supported.\n *\n * 5. Explicitly named Objects: Supported.\n *\n * 6. Explicitly named Maps and Arrays: Not Supported.\n *\n * 7. Node.js `assert.deepEqual`: Compares like plain objects: equal to plain JavaScript objects with the same fields, and other nodes with the same fields, even if the types are different.\n *\n * 8. IntelliSense: Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">`.\n *\n * 9. Recursion: Unsupported: Generated `.d.ts` files replace recursive references with `any`, breaking the use of recursive schema across compilation boundaries.\n *\n * Note that while \"POJO Emulation\" nodes act a lot like POJO objects, they are not true POJO objects:\n *\n * - Adding new arbitrary fields will error, as well some cases of invalid edits.\n *\n * - They are implemented using proxies.\n *\n * - They have state that is not exposed via enumerable own properties, including a {@link TreeNodeSchema}.\n * This makes libraries like node.js `assert.deepEqual` fail to detect differences in type.\n *\n * - Assigning members has side effects (in this case editing the persisted/shared tree).\n *\n * - Not all operations implied by the prototype will work correctly: stick to the APIs explicitly declared in the TypeScript types.\n *\n * @privateRemarks\n * It's perfectly possible to make `POJO Emulation` mode (or even just hiding the prototype) selectable even when using the custom user class declaration syntax.\n * When doing this, it's still possible to make `instanceof` perform correctly.\n * Allowing (or banning) custom/out-of-schema properties on the class is also possible in both modes: it could be orthogonal.\n * Also for consistency, if keeping the current approach to detecting `POJO Emulation` mode it might make sense to make explicitly named Maps and Arrays do the detection the same as how object does it.\n *\n * Note: the comparison between the customizable and POJO modes is not done in a table because TSDoc does not currently have support for embedded markdown.\n *\n * @sealed @public\n */\nexport class SchemaFactory<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> {\n\t/**\n\t * TODO:\n\t * If users of this generate the same name because two different schema with the same identifier were used,\n\t * the second use can get a cache hit, and reference the wrong schema.\n\t * Such usage should probably return a distinct type or error but currently does not.\n\t * The use of markSchemaMostDerived in structuralName at least ensure an error in the case where the collision is from two types extending the same schema factor class.\n\t */\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\n\t/**\n\t * Construct a SchemaFactory with a given scope.\n\t * @remarks\n\t * There are no restrictions on mixing schema from different schema factories:\n\t * this is encouraged when a single schema references schema from different libraries.\n\t * If each library exporting schema picks its own globally unique scope for its SchemaFactory,\n\t * then all schema an application might depend on, directly or transitively,\n\t * will end up with a unique fully qualified name which is required to refer to it in persisted data and errors.\n\t *\n\t * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.\n\t * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.\n\t * You may opt out of using a scope by passing `undefined`, but note that this increases the risk of collisions.\n\t */\n\tpublic constructor(public readonly scope: TScope) {}\n\n\tprivate scoped<Name extends TName | string>(name: Name): ScopedSchemaName<TScope, Name> {\n\t\treturn (\n\t\t\tthis.scope === undefined ? `${name}` : `${this.scope}.${name}`\n\t\t) as ScopedSchemaName<TScope, Name>;\n\t}\n\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\tpublic readonly string = stringSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a JavaScript `number`.\n\t *\n\t * @remarks\n\t * The number is a [double-precision 64-bit binary format IEEE 754](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) value, however there are some exceptions:\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 * - `-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\tpublic readonly number = numberSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding a boolean.\n\t */\n\tpublic readonly boolean = booleanSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for JavaScript `null`.\n\t *\n\t * @remarks\n\t * There are good [reasons to avoid using null](https://www.npmjs.com/package/%40rushstack/eslint-plugin#rushstackno-new-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\tpublic readonly null = nullSchema;\n\n\t/**\n\t * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.\n\t */\n\tpublic readonly handle = handleSchema;\n\n\t/**\n\t * Define a {@link TreeNodeSchemaClass} for a {@link TreeObjectNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n\t */\n\tpublic object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveStringRecord<ImplicitFieldSchema>,\n\t>(\n\t\tname: Name,\n\t\tfields: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Object,\n\t\tTreeObjectNode<T, ScopedSchemaName<TScope, Name>>,\n\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\treturn objectSchema(this.scoped(name), fields, true);\n\t}\n\n\t/**\n\t * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t *\n\t * @remarks\n\t * The unique identifier for this Map is defined as a function of the provided types.\n\t * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t *\n\t * If using these structurally named maps, other types in this schema builder should avoid names of the form `Map<${string}>`.\n\t *\n\t * @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyMap = factory.map(factory.number);\n\t * type MyMap = NodeFromSchema<typeof MyMap>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myMap: factory.map(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * See note on array.\n\t */\n\tpublic map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link TreeMapNode}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedMap extends factory.map(\"name\", factory.number) {}\n\t * ```\n\t */\n\tpublic map<Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/**\n\t * @privateRemarks\n\t * This should return `TreeNodeSchemaBoth`, however TypeScript gives an error if one of the overloads implicitly up-casts the return type of the implementation.\n\t * This seems like a TypeScript bug getting variance backwards for overload return types since it's erroring when the relation between the overload\n\t * and the implementation is type safe, and forcing an unsafe typing instead.\n\t */\n\tpublic map<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<string, NodeKind.Map, TreeMapNode<T>, MapNodeInsertableData<T>, true, T> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Map\", types);\n\t\t\treturn getOrCreate(\n\t\t\t\tthis.structuralTypes,\n\t\t\t\tfullName,\n\t\t\t\t() =>\n\t\t\t\t\tthis.namedMap(\n\t\t\t\t\t\tfullName as TName,\n\t\t\t\t\t\tnameOrAllowedTypes as T,\n\t\t\t\t\t\tfalse,\n\t\t\t\t\t\ttrue,\n\t\t\t\t\t) as TreeNodeSchema,\n\t\t\t) as TreeNodeSchemaBoth<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tMapNodeInsertableData<T>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined\n\t\t\t>;\n\t\t}\n\t\t// To actually have type safety, assign to the type this method should return before implicitly upcasting when returning.\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tstring,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T>,\n\t\t\tMapNodeInsertableData<T>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined\n\t\t> = this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true);\n\t\treturn out;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link (TreeMapNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t */\n\tprivate namedMap<\n\t\tName extends TName | string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\tMapNodeInsertableData<T>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined\n\t> {\n\t\treturn mapSchema(\n\t\t\tthis.scoped(name),\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t\t// The current policy is customizable nodes don't get fake prototypes.\n\t\t\t!customizable,\n\t\t);\n\t}\n\n\t/**\n\t * Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @remarks\n\t * The identifier for this Array is defined as a function of the provided types.\n\t * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.\n\t * This does not support recursive types.\n\t *\n\t * If using these structurally named arrays, other types in this schema builder should avoid names of the form `Array<${string}>`.\n\t *\n\t * @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyArray = factory.array(factory.number);\n\t * type MyArray = NodeFromSchema<typeof MyArray>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myArray: factory.array(factory.number)});\n\t * ```\n\t * @privateRemarks\n\t * The name produced at the type level here is not as specific as it could be, however doing type level sorting and escaping is a real mess.\n\t * There are cases where not having this full type provided will be less than ideal since TypeScript's structural types.\n\t * For example attempts to narrow unions of structural arrays by name won't work.\n\t * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,\n\t * though there may still be some problematic cases even after that work is done.\n\t *\n\t * The return value is a class, but its the type is intentionally not specific enough to indicate it is a class.\n\t * This prevents callers of this from sub-classing it, which is unlikely to work well (due to the ease of accidentally giving two different calls o this different subclasses)\n\t * when working with structural typing.\n\t *\n\t * {@label STRUCTURAL}\n\t */\n\tpublic array<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaNonClass<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/**\n\t * Define (and add to this library) a {@link TreeNodeSchemaClass} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @example\n\t * ```typescript\n\t * class NamedArray extends factory.array(\"name\", factory.number) {}\n\t * ```\n\t *\n\t * {@label NAMED}\n\t */\n\tpublic array<const Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT,\n\t\tundefined\n\t>;\n\n\t/**\n\t * @privateRemarks\n\t * This should return TreeNodeSchemaBoth: see note on \"map\" implementation for details.\n\t */\n\tpublic array<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, string>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"Array\", types);\n\t\t\treturn getOrCreate(this.structuralTypes, fullName, () =>\n\t\t\t\tthis.namedArray(fullName, nameOrAllowedTypes as T, false, true),\n\t\t\t) as TreeNodeSchemaClass<\n\t\t\t\tScopedSchemaName<TScope, string>,\n\t\t\t\tNodeKind.Array,\n\t\t\t\tTreeArrayNode<T>,\n\t\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t\ttrue,\n\t\t\t\tT,\n\t\t\t\tundefined\n\t\t\t>;\n\t\t}\n\t\tconst out: TreeNodeSchemaBoth<\n\t\t\tScopedSchemaName<TScope, string>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\ttrue,\n\t\t\tT,\n\t\t\tundefined\n\t\t> = this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true);\n\t\treturn out;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t *\n\t * @remarks\n\t * This is not intended to be used directly, use the overload of `array` which takes a name instead.\n\t * This is only public to work around a compiler limitation.\n\t */\n\tprivate namedArray<\n\t\tName extends TName | string,\n\t\tconst T extends ImplicitAllowedTypes,\n\t\tconst ImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t\tcustomizable: boolean,\n\t\timplicitlyConstructable: ImplicitlyConstructable,\n\t): TreeNodeSchemaBoth<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>, NodeKind.Array>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable,\n\t\tT,\n\t\tundefined\n\t> {\n\t\treturn arraySchema(this.scoped(name), allowedTypes, implicitlyConstructable, customizable);\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\tpublic 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\t\tconst defaultOptionalProvider: DefaultProvider = getDefaultProvider(() => {\n\t\t\treturn undefined;\n\t\t});\n\t\treturn createFieldSchema(FieldKind.Optional, t, {\n\t\t\tdefaultProvider: defaultOptionalProvider,\n\t\t\t...props,\n\t\t});\n\t}\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\tpublic 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\t\treturn createFieldSchema(FieldKind.Required, t, props);\n\t}\n\n\t/**\n\t * {@link SchemaFactory.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 SchemaFactory.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\tpublic optionalRecursive<const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps, \"defaultProvider\">,\n\t): FieldSchemaUnsafe<FieldKind.Optional, T> {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Optional, t, props);\n\t}\n\n\t/**\n\t * {@link SchemaFactory.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 SchemaFactory.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\tpublic requiredRecursive<const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tt: T,\n\t\tprops?: Omit<FieldProps, \"defaultProvider\">,\n\t): FieldSchemaUnsafe<FieldKind.Required, T> {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Required, t, props);\n\t}\n\n\t/**\n\t * A special field which holds a unique identifier for an object node.\n\t * @remarks\n\t * The value of this field, a \"node identifier\", uniquely identifies a node among all other nodes in the tree.\n\t * Node identifiers are strings, and can therefore be used as lookup keys in maps or written to a database.\n\t * When the node is constructed, the identifier field does not need to be populated.\n\t * The SharedTree will provide an identifier for the node automatically.\n\t * An identifier provided automatically by the SharedTree has the following properties:\n\t * - It is a UUID.\n\t * - It is compressed to a space-efficient representation when stored in the document.\n\t * - A compressed form of the identifier can be accessed at runtime via the `Tree.shortId()` API.\n\t * - It will error if read (and will not be present in the object's iterable properties) before the node has been inserted into the tree.\n\t *\n\t * However, a user may alternatively supply their own string as the identifier if desired (for example, if importing identifiers from another system).\n\t * In that case, it is up to the user to ensure that the identifier is unique within the current tree - no other node should have the same identifier at the same time.\n\t * If the identifier is not unique, it may be read, but may cause libraries or features which operate over node identifiers to misbehave.\n\t * User-supplied identifiers may be read immediately, even before insertion into the tree.\n\t *\n\t * A node may have more than one identifier field (though note that this precludes the use of the `Tree.shortId()` API).\n\t */\n\tpublic get identifier(): FieldSchema<FieldKind.Identifier, typeof this.string> {\n\t\tconst defaultIdentifierProvider: DefaultProvider = getDefaultProvider(\n\t\t\t(nodeKeyManager: NodeKeyManager) => {\n\t\t\t\treturn nodeKeyManager.stabilizeNodeKey(nodeKeyManager.generateLocalNodeKey());\n\t\t\t},\n\t\t);\n\t\treturn createFieldSchema(FieldKind.Identifier, this.string, {\n\t\t\tdefaultProvider: defaultIdentifierProvider,\n\t\t});\n\t}\n\n\t/**\n\t * {@link SchemaFactory.object} 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 SchemaFactory.object} 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\t * Additionally `ImplicitlyConstructable` is disabled (forcing use of constructor) to avoid\n\t * `error TS2589: Type instantiation is excessively deep and possibly infinite.`\n\t * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<RestrictiveStringRecord<ImplicitFieldSchema>>,\n\t>(name: Name, t: T) {\n\t\ttype TScopedName = ScopedSchemaName<TScope, Name>;\n\t\treturn this.object(\n\t\t\tname,\n\t\t\tt as T & RestrictiveStringRecord<ImplicitFieldSchema>,\n\t\t) as unknown as TreeNodeSchemaClass<\n\t\t\tTScopedName,\n\t\t\tNodeKind.Object,\n\t\t\tTreeObjectNodeUnsafe<T, TScopedName>,\n\t\t\tobject & InsertableObjectFromSchemaRecordUnsafe<T>,\n\t\t\tfalse,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/**\n\t * `SchemaFactory.array` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<ImplicitAllowedTypes>,\n\t>(name: Name, allowedTypes: T) {\n\t\tconst RecursiveArray = this.namedArray(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t);\n\n\t\treturn RecursiveArray as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Array>,\n\t\t\t{\n\t\t\t\t/**\n\t\t\t\t * Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t *\n\t\t\t\t * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t */\n\t\t\t\t[Symbol.iterator](): Iterator<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>;\n\t\t\t},\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n\n\t/**\n\t * `SchemaFactory.map` except tweaked to work better for recursive types.\n\t * Use with {@link ValidateRecursiveSchema} for improved type safety.\n\t * @remarks\n\t * This version of `SchemaFactory.map` uses the same workarounds as {@link SchemaFactory.objectRecursive}.\n\t * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.\n\t */\n\t// eslint-disable-next-line @typescript-eslint/explicit-function-return-type\n\tpublic mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t) {\n\t\tconst MapSchema = this.namedMap(\n\t\t\tname,\n\t\t\tallowedTypes as T & ImplicitAllowedTypes,\n\t\t\ttrue,\n\t\t\tfalse,\n\t\t);\n\n\t\treturn MapSchema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Map>,\n\t\t\t{\n\t\t\t\t/**\n\t\t\t\t * Iterator for the iterable of content for this node.\n\t\t\t\t * @privateRemarks\n\t\t\t\t * Wrapping the constructor parameter for recursive arrays and maps in an inlined object type avoids (for unknown reasons)\n\t\t\t\t * the following compile error when declaring the recursive schema:\n\t\t\t\t * `Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.`\n\t\t\t\t * To benefit from this without impacting the API, the definition of `Iterable` has been inlined as such an object.\n\t\t\t\t *\n\t\t\t\t * If this workaround is kept, ideally this comment would be deduplicated with the other instance of it.\n\t\t\t\t * Unfortunately attempts to do this failed to avoid the compile error this was introduced to solve.\n\t\t\t\t */\n\t\t\t\t[Symbol.iterator](): Iterator<\n\t\t\t\t\t[string, InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>]\n\t\t\t\t>;\n\t\t\t},\n\t\t\t// Ideally this would be included, but doing so breaks recursive types.\n\t\t\t// | RestrictiveStringRecord<InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>>,\n\t\t\tfalse,\n\t\t\tT,\n\t\t\tundefined\n\t\t>;\n\t}\n}\n\nexport function structuralName<const T extends string>(\n\tcollectionName: T,\n\tallowedTypes: TreeNodeSchema | readonly TreeNodeSchema[],\n): `${T}<${string}>` {\n\tlet inner: string;\n\tif (!isReadonlyArray(allowedTypes)) {\n\t\treturn structuralName(collectionName, [allowedTypes]);\n\t} else {\n\t\tconst names = allowedTypes.map((t): string => {\n\t\t\t// Ensure that lazy types (functions) don't slip through here.\n\t\t\tassert(!isLazy(t), 0x83d /* invalid type provided */);\n\t\t\tmarkSchemaMostDerived(t);\n\t\t\treturn t.identifier;\n\t\t});\n\t\t// Ensure name is order independent\n\t\tnames.sort();\n\t\t// Ensure name can't have collisions by quoting and escaping any quotes in the names of types.\n\t\t// Using JSON is a simple way to accomplish this.\n\t\t// The outer `[]` around the result were needed so that a single type name \"Any\" would not collide with the \"any\" case which used to exist.\n\t\tinner = JSON.stringify(names);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n\n/**\n * Indicates that a schema is the \"most derived\" version which is allowed to be used, see {@link MostDerivedData}.\n * Calling helps with error messages about invalid schema usage (using more than one type from single schema factor produced type,\n * and thus calling this for one than one subclass).\n * @remarks\n * Helper for invoking {@link TreeNodeValid.markMostDerived} for any {@link TreeNodeSchema} if it needed.\n */\nexport function markSchemaMostDerived(schema: TreeNodeSchema): void {\n\tif (schema instanceof LeafNodeSchema) {\n\t\treturn;\n\t}\n\n\tif (!inPrototypeChain(schema, TreeNodeValid)) {\n\t\t// Use JSON.stringify to quote and escape identifier string.\n\t\tthrow new UsageError(\n\t\t\t`Schema for ${JSON.stringify(\n\t\t\t\tschema.identifier,\n\t\t\t)} does not extend a SchemaFactory generated class. This is invalid.`,\n\t\t);\n\t}\n\n\t(schema as typeof TreeNodeValid & TreeNodeSchema).markMostDerived();\n}\n"]}

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

@@ -65,7 +65,7 @@ function convertArrayNodeSchema(schema) {
     schema.allowedTypes.forEach((type) => {
         allowedTypes.push(createSchemaRef(type));
     });
-    const items = allowedTypes.length === 1 ? allowedTypes[0] ?? oob() : { anyOf: allowedTypes };
+    const items = allowedTypes.length === 1 ? (allowedTypes[0] ?? oob()) : { anyOf: allowedTypes };
     return {
         type: "array",
         _treeNodeSchemaKind: NodeKind.Array,
@@ -106,7 +106,7 @@ function convertObjectNodeSchema(schema) {
             allowedTypes.push(createSchemaRef(allowedType));
         }
         const output = allowedTypes.length === 1
-            ? allowedTypes[0] ?? oob()
+            ? (allowedTypes[0] ?? oob())
             : {
                 anyOf: allowedTypes,
             };
@@ -137,7 +137,7 @@ function convertMapNodeSchema(schema) {
         _treeNodeSchemaKind: NodeKind.Map,
         patternProperties: {
             "^.*$": allowedTypes.length === 1
-                ? allowedTypes[0] ?? oob()
+                ? (allowedTypes[0] ?? oob())
                 : {
                     anyOf: allowedTypes,
                 },

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

@@ -1 +1 @@
-{"version":3,"file":"simpleSchemaToJsonSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleSchemaToJsonSchema.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { oob, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { ValueSchema } from \"../../core/index.js\";\nimport { getOrCreate, type Mutable } from \"../../util/index.js\";\nimport type {\n\tJsonArrayNodeSchema,\n\tJsonFieldSchema,\n\tJsonSchemaRef,\n\tJsonRefPath,\n\tJsonLeafNodeSchema,\n\tJsonMapNodeSchema,\n\tJsonNodeSchema,\n\tJsonObjectNodeSchema,\n\tJsonTreeSchema,\n\tJsonLeafSchemaType,\n} from \"./jsonSchema.js\";\nimport { FieldKind } from \"../schemaTypes.js\";\nimport type {\n\tSimpleArrayNodeSchema,\n\tSimpleLeafNodeSchema,\n\tSimpleMapNodeSchema,\n\tSimpleNodeSchema,\n\tSimpleObjectNodeSchema,\n\tSimpleTreeSchema,\n} from \"./simpleSchema.js\";\nimport { NodeKind } from \"../core/index.js\";\n\n/**\n * Generates a JSON Schema representation from a simple tree schema.\n * @internal\n */\nexport function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {\n\tconst definitions = convertDefinitions(schema.definitions);\n\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tfor (const allowedType of schema.allowedTypes) {\n\t\tallowedTypes.push(createSchemaRef(allowedType));\n\t}\n\n\treturn allowedTypes.length === 1\n\t\t? {\n\t\t\t\t...(allowedTypes[0] ?? oob()),\n\t\t\t\t$defs: definitions,\n\t\t\t}\n\t\t: {\n\t\t\t\t$defs: definitions,\n\t\t\t\tanyOf: allowedTypes,\n\t\t\t};\n}\n\nfunction convertDefinitions(\n\tdefinitions: ReadonlyMap<string, SimpleNodeSchema>,\n): Record<string, JsonNodeSchema> {\n\tconst result: Record<string, JsonNodeSchema> = {};\n\tfor (const [key, value] of definitions) {\n\t\tresult[key] = convertNodeSchema(value);\n\t}\n\treturn result;\n}\n\n/**\n * Private symbol under which the results of {@link convertNodeSchema} are cached on an input {@link SimpleNodeSchema}.\n */\nconst nodeJsonSchemaCache = new WeakMap<SimpleNodeSchema, JsonNodeSchema>();\n\n/**\n * Converts an input {@link SimpleNodeSchema} to a {@link JsonNodeSchema}.\n *\n * @remarks Caches the result on the input schema for future calls.\n */\nfunction convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {\n\treturn getOrCreate(nodeJsonSchemaCache, schema, () => {\n\t\tswitch (schema.kind) {\n\t\t\tcase NodeKind.Array:\n\t\t\t\treturn convertArrayNodeSchema(schema);\n\t\t\tcase NodeKind.Leaf:\n\t\t\t\treturn convertLeafNodeSchema(schema);\n\t\t\tcase NodeKind.Map:\n\t\t\t\treturn convertMapNodeSchema(schema);\n\t\t\tcase NodeKind.Object:\n\t\t\t\treturn convertObjectNodeSchema(schema);\n\t\t\tdefault:\n\t\t\t\tthrow new TypeError(`Unknown node schema kind: ${(schema as SimpleNodeSchema).kind}`);\n\t\t}\n\t});\n}\n\nfunction convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tschema.allowedTypes.forEach((type) => {\n\t\tallowedTypes.push(createSchemaRef(type));\n\t});\n\n\tconst items: JsonFieldSchema =\n\t\tallowedTypes.length === 1 ? allowedTypes[0] ?? oob() : { anyOf: allowedTypes };\n\n\treturn {\n\t\ttype: \"array\",\n\t\t_treeNodeSchemaKind: NodeKind.Array,\n\t\titems,\n\t};\n}\n\nfunction convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {\n\tlet type: JsonLeafSchemaType;\n\tswitch (schema.leafKind) {\n\t\tcase ValueSchema.String:\n\t\t\ttype = \"string\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Number:\n\t\t\ttype = \"number\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Boolean:\n\t\t\ttype = \"boolean\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Null:\n\t\t\ttype = \"null\";\n\t\t\tbreak;\n\t\tcase ValueSchema.FluidHandle:\n\t\t\tthrow new UsageError(\"Fluid handles are not supported via JSON Schema.\");\n\t\tdefault:\n\t\t\tunreachableCase(schema.leafKind);\n\t}\n\n\treturn {\n\t\ttype,\n\t\t_treeNodeSchemaKind: NodeKind.Leaf,\n\t};\n}\n\nfunction convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {\n\tconst properties: Record<string, JsonFieldSchema> = {};\n\tconst required: string[] = [];\n\tfor (const [key, value] of Object.entries(schema.fields)) {\n\t\tconst allowedTypes: JsonSchemaRef[] = [];\n\t\tfor (const allowedType of value.allowedTypes) {\n\t\t\tallowedTypes.push(createSchemaRef(allowedType));\n\t\t}\n\n\t\tconst output: Mutable<JsonFieldSchema> =\n\t\t\tallowedTypes.length === 1\n\t\t\t\t? allowedTypes[0] ?? oob()\n\t\t\t\t: {\n\t\t\t\t\t\tanyOf: allowedTypes,\n\t\t\t\t\t};\n\n\t\t// Don't include \"description\" property at all if it's not present in the input.\n\t\tif (value.description !== undefined) {\n\t\t\toutput.description = value.description;\n\t\t}\n\n\t\tproperties[key] = output;\n\n\t\tif (value.kind === FieldKind.Required) {\n\t\t\trequired.push(key);\n\t\t}\n\t}\n\treturn {\n\t\ttype: \"object\",\n\t\t_treeNodeSchemaKind: NodeKind.Object,\n\t\tproperties,\n\t\trequired,\n\t\tadditionalProperties: false,\n\t};\n}\n\nfunction convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tschema.allowedTypes.forEach((type) => {\n\t\tallowedTypes.push(createSchemaRef(type));\n\t});\n\treturn {\n\t\ttype: \"object\",\n\t\t_treeNodeSchemaKind: NodeKind.Map,\n\t\tpatternProperties: {\n\t\t\t\"^.*$\":\n\t\t\t\tallowedTypes.length === 1\n\t\t\t\t\t? allowedTypes[0] ?? oob()\n\t\t\t\t\t: {\n\t\t\t\t\t\t\tanyOf: allowedTypes,\n\t\t\t\t\t\t},\n\t\t},\n\t};\n}\n\nfunction createSchemaRef(schemaId: string): JsonSchemaRef {\n\treturn {\n\t\t\"$ref\": createRefPath(schemaId),\n\t};\n}\n\nfunction createRefPath(schemaId: string): JsonRefPath {\n\treturn `#/$defs/${schemaId}`;\n}\n"]}
+{"version":3,"file":"simpleSchemaToJsonSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/simpleSchemaToJsonSchema.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { oob, unreachableCase } from \"@fluidframework/core-utils/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport { ValueSchema } from \"../../core/index.js\";\nimport { getOrCreate, type Mutable } from \"../../util/index.js\";\nimport type {\n\tJsonArrayNodeSchema,\n\tJsonFieldSchema,\n\tJsonSchemaRef,\n\tJsonRefPath,\n\tJsonLeafNodeSchema,\n\tJsonMapNodeSchema,\n\tJsonNodeSchema,\n\tJsonObjectNodeSchema,\n\tJsonTreeSchema,\n\tJsonLeafSchemaType,\n} from \"./jsonSchema.js\";\nimport { FieldKind } from \"../schemaTypes.js\";\nimport type {\n\tSimpleArrayNodeSchema,\n\tSimpleLeafNodeSchema,\n\tSimpleMapNodeSchema,\n\tSimpleNodeSchema,\n\tSimpleObjectNodeSchema,\n\tSimpleTreeSchema,\n} from \"./simpleSchema.js\";\nimport { NodeKind } from \"../core/index.js\";\n\n/**\n * Generates a JSON Schema representation from a simple tree schema.\n * @internal\n */\nexport function toJsonSchema(schema: SimpleTreeSchema): JsonTreeSchema {\n\tconst definitions = convertDefinitions(schema.definitions);\n\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tfor (const allowedType of schema.allowedTypes) {\n\t\tallowedTypes.push(createSchemaRef(allowedType));\n\t}\n\n\treturn allowedTypes.length === 1\n\t\t? {\n\t\t\t\t...(allowedTypes[0] ?? oob()),\n\t\t\t\t$defs: definitions,\n\t\t\t}\n\t\t: {\n\t\t\t\t$defs: definitions,\n\t\t\t\tanyOf: allowedTypes,\n\t\t\t};\n}\n\nfunction convertDefinitions(\n\tdefinitions: ReadonlyMap<string, SimpleNodeSchema>,\n): Record<string, JsonNodeSchema> {\n\tconst result: Record<string, JsonNodeSchema> = {};\n\tfor (const [key, value] of definitions) {\n\t\tresult[key] = convertNodeSchema(value);\n\t}\n\treturn result;\n}\n\n/**\n * Private symbol under which the results of {@link convertNodeSchema} are cached on an input {@link SimpleNodeSchema}.\n */\nconst nodeJsonSchemaCache = new WeakMap<SimpleNodeSchema, JsonNodeSchema>();\n\n/**\n * Converts an input {@link SimpleNodeSchema} to a {@link JsonNodeSchema}.\n *\n * @remarks Caches the result on the input schema for future calls.\n */\nfunction convertNodeSchema(schema: SimpleNodeSchema): JsonNodeSchema {\n\treturn getOrCreate(nodeJsonSchemaCache, schema, () => {\n\t\tswitch (schema.kind) {\n\t\t\tcase NodeKind.Array:\n\t\t\t\treturn convertArrayNodeSchema(schema);\n\t\t\tcase NodeKind.Leaf:\n\t\t\t\treturn convertLeafNodeSchema(schema);\n\t\t\tcase NodeKind.Map:\n\t\t\t\treturn convertMapNodeSchema(schema);\n\t\t\tcase NodeKind.Object:\n\t\t\t\treturn convertObjectNodeSchema(schema);\n\t\t\tdefault:\n\t\t\t\tthrow new TypeError(`Unknown node schema kind: ${(schema as SimpleNodeSchema).kind}`);\n\t\t}\n\t});\n}\n\nfunction convertArrayNodeSchema(schema: SimpleArrayNodeSchema): JsonArrayNodeSchema {\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tschema.allowedTypes.forEach((type) => {\n\t\tallowedTypes.push(createSchemaRef(type));\n\t});\n\n\tconst items: JsonFieldSchema =\n\t\tallowedTypes.length === 1 ? (allowedTypes[0] ?? oob()) : { anyOf: allowedTypes };\n\n\treturn {\n\t\ttype: \"array\",\n\t\t_treeNodeSchemaKind: NodeKind.Array,\n\t\titems,\n\t};\n}\n\nfunction convertLeafNodeSchema(schema: SimpleLeafNodeSchema): JsonLeafNodeSchema {\n\tlet type: JsonLeafSchemaType;\n\tswitch (schema.leafKind) {\n\t\tcase ValueSchema.String:\n\t\t\ttype = \"string\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Number:\n\t\t\ttype = \"number\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Boolean:\n\t\t\ttype = \"boolean\";\n\t\t\tbreak;\n\t\tcase ValueSchema.Null:\n\t\t\ttype = \"null\";\n\t\t\tbreak;\n\t\tcase ValueSchema.FluidHandle:\n\t\t\tthrow new UsageError(\"Fluid handles are not supported via JSON Schema.\");\n\t\tdefault:\n\t\t\tunreachableCase(schema.leafKind);\n\t}\n\n\treturn {\n\t\ttype,\n\t\t_treeNodeSchemaKind: NodeKind.Leaf,\n\t};\n}\n\nfunction convertObjectNodeSchema(schema: SimpleObjectNodeSchema): JsonObjectNodeSchema {\n\tconst properties: Record<string, JsonFieldSchema> = {};\n\tconst required: string[] = [];\n\tfor (const [key, value] of Object.entries(schema.fields)) {\n\t\tconst allowedTypes: JsonSchemaRef[] = [];\n\t\tfor (const allowedType of value.allowedTypes) {\n\t\t\tallowedTypes.push(createSchemaRef(allowedType));\n\t\t}\n\n\t\tconst output: Mutable<JsonFieldSchema> =\n\t\t\tallowedTypes.length === 1\n\t\t\t\t? (allowedTypes[0] ?? oob())\n\t\t\t\t: {\n\t\t\t\t\t\tanyOf: allowedTypes,\n\t\t\t\t\t};\n\n\t\t// Don't include \"description\" property at all if it's not present in the input.\n\t\tif (value.description !== undefined) {\n\t\t\toutput.description = value.description;\n\t\t}\n\n\t\tproperties[key] = output;\n\n\t\tif (value.kind === FieldKind.Required) {\n\t\t\trequired.push(key);\n\t\t}\n\t}\n\treturn {\n\t\ttype: \"object\",\n\t\t_treeNodeSchemaKind: NodeKind.Object,\n\t\tproperties,\n\t\trequired,\n\t\tadditionalProperties: false,\n\t};\n}\n\nfunction convertMapNodeSchema(schema: SimpleMapNodeSchema): JsonMapNodeSchema {\n\tconst allowedTypes: JsonSchemaRef[] = [];\n\tschema.allowedTypes.forEach((type) => {\n\t\tallowedTypes.push(createSchemaRef(type));\n\t});\n\treturn {\n\t\ttype: \"object\",\n\t\t_treeNodeSchemaKind: NodeKind.Map,\n\t\tpatternProperties: {\n\t\t\t\"^.*$\":\n\t\t\t\tallowedTypes.length === 1\n\t\t\t\t\t? (allowedTypes[0] ?? oob())\n\t\t\t\t\t: {\n\t\t\t\t\t\t\tanyOf: allowedTypes,\n\t\t\t\t\t\t},\n\t\t},\n\t};\n}\n\nfunction createSchemaRef(schemaId: string): JsonSchemaRef {\n\treturn {\n\t\t\"$ref\": createRefPath(schemaId),\n\t};\n}\n\nfunction createRefPath(schemaId: string): JsonRefPath {\n\treturn `#/$defs/${schemaId}`;\n}\n"]}

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

@@ -4,7 +4,7 @@
  */
 import { Compatibility } from "../../core/index.js";
 import { defaultSchemaPolicy, encodeTreeSchema, makeSchemaCodec, } from "../../feature-libraries/index.js";
-import { toStoredSchema } from "../toFlexSchema.js";
+import { toStoredSchema } from "../toStoredSchema.js";
 import { ViewSchema } from "./view.js";
 /**
  * Dumps the "persisted" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.

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

@@ -1 +1 @@
-{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAyB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACN,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GACf,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IACjE,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAoB,EACpB,OAAsB,EACtB,aAAsB;IAEtB,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAmB,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,IAAc,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,mBAAmB,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACvE,OAAO,8BAA8B,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;AAC1E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC7C,MAAwB,EACxB,UAAsB,EACtB,aAAsB;IAEtB,MAAM,MAAM,GAAG,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAErD,sFAAsF;IACtF,2HAA2H;IAC3H,mHAAmH;IACnH,kIAAkI;IAClI,MAAM,OAAO,GACZ,MAAM,CAAC,KAAK,KAAK,aAAa,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,UAAU,CAAC;IACvF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,UAAU,CAAC;IAC5D,MAAM,YAAY,GAAG,OAAO,IAAI,UAAU,CAAC;IAC3C,MAAM,aAAa,GAA8B;QAChD,OAAO;QACP,UAAU;QACV,YAAY;QACZ,aAAa;KACb,CAAC;IAEF,OAAO,aAAa,CAAC;AACtB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ICodecOptions } from \"../../codec/index.js\";\nimport { Compatibility, type TreeStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tencodeTreeSchema,\n\tmakeSchemaCodec,\n} from \"../../feature-libraries/index.js\";\n// eslint-disable-next-line import/no-internal-modules\nimport type { Format } from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { ImplicitFieldSchema } from \"../schemaTypes.js\";\nimport { toStoredSchema } from \"../toFlexSchema.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\nimport { ViewSchema } from \"./view.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.\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 *\n * This format may change across major versions of this package: such changes are considered breaking.\n * Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.\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), 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(schema: ImplicitFieldSchema): JsonCompatible {\n\tconst stored = toStoredSchema(schema);\n\treturn encodeTreeSchema(stored);\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. Use {@link extractPersistedSchema} to convert the view schema into this format.\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\textractPersistedSchema(MySchema),\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: JsonCompatible,\n\toptions: ICodecOptions,\n\tcanInitialize: boolean,\n): SchemaCompatibilityStatus {\n\tconst schemaCodec = makeSchemaCodec(options);\n\tconst stored = schemaCodec.decode(persisted as Format);\n\tconst viewParsed = schemaCodec.decode(view as Format);\n\tconst viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);\n\treturn comparePersistedSchemaInternal(stored, viewSchema, canInitialize);\n}\n\n/**\n * Compute compatibility for viewing a document with `stored` schema using `viewSchema`.\n * `canInitialize` is passed through to the return value unchanged and otherwise unused.\n */\nexport function comparePersistedSchemaInternal(\n\tstored: TreeStoredSchema,\n\tviewSchema: ViewSchema,\n\tcanInitialize: boolean,\n): SchemaCompatibilityStatus {\n\tconst result = viewSchema.checkCompatibility(stored);\n\n\t// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.\n\t// In the near term, this should support viewing documents with additional optional fields in their schema on object types.\n\t// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility\n\t// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)\n\tconst canView =\n\t\tresult.write === Compatibility.Compatible && result.read === Compatibility.Compatible;\n\tconst canUpgrade = result.read === Compatibility.Compatible;\n\tconst isEquivalent = canView && canUpgrade;\n\tconst compatibility: SchemaCompatibilityStatus = {\n\t\tcanView,\n\t\tcanUpgrade,\n\t\tisEquivalent,\n\t\tcanInitialize,\n\t};\n\n\treturn compatibility;\n}\n"]}
+{"version":3,"file":"storedSchema.js","sourceRoot":"","sources":["../../../src/simple-tree/api/storedSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAyB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACN,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,GACf,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IACjE,MAAM,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CACrC,SAAyB,EACzB,IAAoB,EACpB,OAAsB,EACtB,aAAsB;IAEtB,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,SAAmB,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,IAAc,CAAC,CAAC;IACtD,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,mBAAmB,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACvE,OAAO,8BAA8B,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;AAC1E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B,CAC7C,MAAwB,EACxB,UAAsB,EACtB,aAAsB;IAEtB,MAAM,MAAM,GAAG,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAErD,sFAAsF;IACtF,2HAA2H;IAC3H,mHAAmH;IACnH,kIAAkI;IAClI,MAAM,OAAO,GACZ,MAAM,CAAC,KAAK,KAAK,aAAa,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,UAAU,CAAC;IACvF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,UAAU,CAAC;IAC5D,MAAM,YAAY,GAAG,OAAO,IAAI,UAAU,CAAC;IAC3C,MAAM,aAAa,GAA8B;QAChD,OAAO;QACP,UAAU;QACV,YAAY;QACZ,aAAa;KACb,CAAC;IAEF,OAAO,aAAa,CAAC;AACtB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { ICodecOptions } from \"../../codec/index.js\";\nimport { Compatibility, type TreeStoredSchema } from \"../../core/index.js\";\nimport {\n\tdefaultSchemaPolicy,\n\tencodeTreeSchema,\n\tmakeSchemaCodec,\n} from \"../../feature-libraries/index.js\";\n// eslint-disable-next-line import/no-internal-modules\nimport type { Format } from \"../../feature-libraries/schema-index/index.js\";\nimport type { JsonCompatible } from \"../../util/index.js\";\nimport type { ImplicitFieldSchema } from \"../schemaTypes.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\nimport type { SchemaCompatibilityStatus } from \"./tree.js\";\nimport { ViewSchema } from \"./view.js\";\n\n/**\n * Dumps the \"persisted\" schema subset of the provided `schema` into a deterministic JSON-compatible, semi-human-readable, but unspecified format.\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 *\n * This format may change across major versions of this package: such changes are considered breaking.\n * Beyond that, no compatibility guarantee is provided for this format: it should never be relied upon to load data, it should only be used for comparing outputs from this function.\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), 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(schema: ImplicitFieldSchema): JsonCompatible {\n\tconst stored = toStoredSchema(schema);\n\treturn encodeTreeSchema(stored);\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. Use {@link extractPersistedSchema} to convert the view schema into this format.\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\textractPersistedSchema(MySchema),\n * \t\t{ jsonValidator: typeboxValidator },\n * \t\tfalse,\n * \t).canUpgrade,\n * );\n * ```\n * @alpha\n */\nexport function comparePersistedSchema(\n\tpersisted: JsonCompatible,\n\tview: JsonCompatible,\n\toptions: ICodecOptions,\n\tcanInitialize: boolean,\n): SchemaCompatibilityStatus {\n\tconst schemaCodec = makeSchemaCodec(options);\n\tconst stored = schemaCodec.decode(persisted as Format);\n\tconst viewParsed = schemaCodec.decode(view as Format);\n\tconst viewSchema = new ViewSchema(defaultSchemaPolicy, {}, viewParsed);\n\treturn comparePersistedSchemaInternal(stored, viewSchema, canInitialize);\n}\n\n/**\n * Compute compatibility for viewing a document with `stored` schema using `viewSchema`.\n * `canInitialize` is passed through to the return value unchanged and otherwise unused.\n */\nexport function comparePersistedSchemaInternal(\n\tstored: TreeStoredSchema,\n\tviewSchema: ViewSchema,\n\tcanInitialize: boolean,\n): SchemaCompatibilityStatus {\n\tconst result = viewSchema.checkCompatibility(stored);\n\n\t// TODO: AB#8121: Weaken this check to support viewing under additional circumstances.\n\t// In the near term, this should support viewing documents with additional optional fields in their schema on object types.\n\t// Longer-term (as demand arises), we could also add APIs to constructing view schema to allow for more flexibility\n\t// (e.g. out-of-schema content handlers could allow support for viewing docs which have extra allowed types in a particular field)\n\tconst canView =\n\t\tresult.write === Compatibility.Compatible && result.read === Compatibility.Compatible;\n\tconst canUpgrade = result.read === Compatibility.Compatible;\n\tconst isEquivalent = canView && canUpgrade;\n\tconst compatibility: SchemaCompatibilityStatus = {\n\t\tcanView,\n\t\tcanUpgrade,\n\t\tisEquivalent,\n\t\tcanInitialize,\n\t};\n\n\treturn compatibility;\n}\n"]}

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

@@ -16,14 +16,14 @@ import type { NodeKind } from "../core/index.js";
  */
 export declare const base: import("../core/treeNodeSchema.js").TreeNodeSchemaClass<"Test Recursive Domain.testObject", NodeKind.Object, import("./typesUnsafe.js").TreeObjectNodeUnsafe<{
     readonly recursive: import("./typesUnsafe.js").FieldSchemaUnsafe<FieldKind.Optional, readonly [() => typeof RecursiveObject]>;
-    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchemaNonClass<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number, true, unknown, never>;
 }, "Test Recursive Domain.testObject">, object & {
     readonly number: number;
 } & {
     readonly recursive?: RecursiveObject | undefined;
 }, false, {
     readonly recursive: import("./typesUnsafe.js").FieldSchemaUnsafe<FieldKind.Optional, readonly [() => typeof RecursiveObject]>;
-    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchemaNonClass<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number, true, unknown, never>;
 }>;
 /**
  * @internal
@@ -41,7 +41,7 @@ export declare const RecursiveObjectPojoMode: import("../core/treeNodeSchema.js"
     } & {
         readonly recursive?: import("./typesUnsafe.js").TreeObjectNodeUnsafe<any, "Test Recursive Domain.testPOJOObject"> | undefined;
     }, false, any>]>;
-    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchemaNonClass<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number, true, unknown, never>;
 }, "Test Recursive Domain.testPOJOObject">, object & {
     readonly number: number;
 } & {
@@ -49,7 +49,7 @@ export declare const RecursiveObjectPojoMode: import("../core/treeNodeSchema.js"
         readonly recursive: import("./typesUnsafe.js").FieldSchemaUnsafe<FieldKind.Optional, readonly [() => import("../core/treeNodeSchema.js").TreeNodeSchemaClass<"Test Recursive Domain.testPOJOObject", NodeKind.Object, import("./typesUnsafe.js").TreeObjectNodeUnsafe<any, "Test Recursive Domain.testPOJOObject">, object & {
             readonly number: number;
         } & any, false, any>]>;
-        readonly number: import("../core/treeNodeSchema.js").TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+        readonly number: import("../core/treeNodeSchema.js").TreeNodeSchemaNonClass<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number, true, unknown, never>;
     }, "Test Recursive Domain.testPOJOObject"> | undefined;
 }, false, {
     readonly recursive: import("./typesUnsafe.js").FieldSchemaUnsafe<FieldKind.Optional, readonly [() => import("../core/treeNodeSchema.js").TreeNodeSchemaClass<"Test Recursive Domain.testPOJOObject", NodeKind.Object, import("./typesUnsafe.js").TreeObjectNodeUnsafe<any, "Test Recursive Domain.testPOJOObject">, object & {
@@ -57,6 +57,6 @@ export declare const RecursiveObjectPojoMode: import("../core/treeNodeSchema.js"
     } & {
         readonly recursive?: import("./typesUnsafe.js").TreeObjectNodeUnsafe<any, "Test Recursive Domain.testPOJOObject"> | undefined;
     }, false, any>]>;
-    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+    readonly number: import("../core/treeNodeSchema.js").TreeNodeSchemaNonClass<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number, true, unknown, never>;
 }>;
 //# sourceMappingURL=testRecursiveDomain.d.ts.map

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

@@ -5,11 +5,19 @@
 import type { IFluidLoadable, IDisposable } from "@fluidframework/core-interfaces";
 import type { CommitMetadata, RevertibleFactory } from "../../core/index.js";
 import type { Listenable } from "../../events/index.js";
-import { type ImplicitFieldSchema, type InsertableTreeFieldFromImplicitField, type TreeFieldFromImplicitField } from "../schemaTypes.js";
+import { type ImplicitFieldSchema, type InsertableField, type InsertableTreeFieldFromImplicitField, type ReadableField, type ReadSchema, type TreeFieldFromImplicitField, type UnsafeUnknownSchema } from "../schemaTypes.js";
 import { type TreeNodeSchema } from "../core/index.js";
 import type { MakeNominal } from "../../util/index.js";
 /**
  * A tree from which a {@link TreeView} can be created.
+ *
+ * @privateRemarks
+ * TODO:
+ * Add stored key versions of {@link TreeAlpha.(exportVerbose:2)}, {@link TreeAlpha.(exportConcise:2)} and {@link TreeAlpha.exportCompressed} here so tree content can be accessed without a view schema.
+ * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).
+ * Maybe rename "exportJsonSchema" to align on "concise" terminology.
+ * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).
+ * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).
  * @system @sealed @public
  */
 export interface ViewableTree {
@@ -29,7 +37,7 @@ export interface ViewableTree {
      * Only one schematized view may exist for a given ITree at a time.
      * If creating a second, the first must be disposed before calling `viewWith` again.
      *
-     * @privateRemarks
+     *
      * TODO: Provide a way to make a generic view schema for any document.
      * TODO: Support adapters for handling out-of-schema data.
      *
@@ -161,7 +169,7 @@ export interface ITreeViewConfiguration<TSchema extends ImplicitFieldSchema = Im
  * Configuration for {@link ViewableTree.viewWith}.
  * @sealed @public
  */
-export declare class TreeViewConfiguration<TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
+export declare class TreeViewConfiguration<const TSchema extends ImplicitFieldSchema = ImplicitFieldSchema> implements Required<ITreeViewConfiguration<TSchema>> {
     protected _typeCheck: MakeNominal;
     /**
      * {@inheritDoc ITreeViewConfiguration.schema}
@@ -184,6 +192,76 @@ export declare class TreeViewConfiguration<TSchema extends ImplicitFieldSchema =
  * Detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}.
  */
 export declare function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): void;
+/**
+ * A collection of functionality associated with a (version-control-style) branch of a SharedTree.
+ * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork | creation of branches} and for those branches to later be {@link TreeBranch.merge | merged}.
+ *
+ * The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.
+ *
+ * A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha | view with a schema}, use {@link TreeBranch.hasRootSchema | hasRootSchema()}.
+ *
+ * The branch associated directly with the {@link ITree | SharedTree} is the "main" branch, and all other branches fork (directly or transitively) from that main branch.
+ * @sealed @alpha
+ */
+export interface TreeBranch extends IDisposable {
+    /**
+     * Events for the branch
+     */
+    readonly events: Listenable<TreeBranchEvents>;
+    /**
+     * Returns true if this branch has the given schema as its root schema.
+     * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha | view} of the given schema.
+     *
+     * To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.
+     * For example, a schema of `Foo | Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo | Bar`.
+     * @example
+     * ```typescript
+     * if (branch.hasRootSchema(MySchema)) {
+     *   const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>
+     *   // ...
+     * }
+     * ```
+     */
+    hasRootSchema<TSchema extends ImplicitFieldSchema>(schema: TSchema): this is TreeViewAlpha<TSchema>;
+    /**
+     * Fork a new branch off of this branch which is based off of this branch's current state.
+     * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge | merged} back into this branch.
+     * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose | explicitly} or {@link TreeBranch.merge | implicitly when merging} into another branch.
+     */
+    fork(): TreeBranch;
+    /**
+     * Apply all the new changes on the given branch to this branch.
+     * @param branch - a branch which was created by a call to `branch()`.
+     * @param disposeMerged - whether or not to dispose `branch` after the merge completes.
+     * Defaults to true.
+     * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
+     * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.
+     */
+    merge(branch: TreeBranch, disposeMerged?: boolean): void;
+    /**
+     * Advance this branch forward such that all new changes on the target branch become part of this branch.
+     * @param branch - The branch to rebase onto.
+     * @remarks After rebasing, this branch will be "ahead" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.
+     * This method may only be called on branches produced via {@link TreeBranch.fork | branch} - attempting to rebase the main branch will throw.
+     *
+     * Rebasing long-lived branches is important to avoid consuming memory unnecessarily.
+     * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last rebased.
+     *
+     * The {@link TreeBranch | main branch} cannot be rebased onto another branch - attempting to do so will throw an error.
+     */
+    rebaseOnto(branch: TreeBranch): void;
+    /**
+     * Dispose of this branch, cleaning up any resources associated with it.
+     * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.
+     * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge | they are merged} into another branch.
+     *
+     * Disposing branches is important to avoid consuming memory unnecessarily.
+     * In particular, the SharedTree retains all sequenced changes made to the tree since the "most-behind" branch was created or last {@link TreeBranch.rebaseOnto | rebased}.
+     *
+     * The {@link TreeBranch | main branch} cannot be disposed - attempting to do so will have no effect.
+     */
+    dispose(error?: Error): void;
+}
 /**
  * An editable view of a (version control style) branch of a shared tree based on some schema.
  *
@@ -201,7 +279,7 @@ export declare function checkUnion(union: Iterable<TreeNodeSchema>, errors: stri
  * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.
  * @sealed @public
  */
-export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposable {
+export interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {
     /**
      * The current root of the tree.
      *
@@ -255,6 +333,16 @@ export interface TreeView<TSchema extends ImplicitFieldSchema> extends IDisposab
      */
     readonly schema: TSchema;
 }
+/**
+ * {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.
+ * @sealed @alpha
+ */
+export interface TreeViewAlpha<in out TSchema extends ImplicitFieldSchema | UnsafeUnknownSchema> extends Omit<TreeView<ReadSchema<TSchema>>, "root" | "initialize">, Omit<TreeBranch, "events"> {
+    get root(): ReadableField<TSchema>;
+    set root(newRoot: InsertableField<TSchema>);
+    initialize(content: InsertableField<TSchema>): void;
+    fork(): ReturnType<TreeBranch["fork"]> & TreeViewAlpha<TSchema>;
+}
 /**
  * Information about a view schema's compatibility with the document's stored schema.
  *
@@ -319,10 +407,34 @@ export interface SchemaCompatibilityStatus {
      *
      * @remarks
      * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from
-     * context that they're in a flow which creates a new `SharedTree` and would like to initialize it.
+     * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.
      */
     readonly canInitialize: boolean;
 }
+/**
+ * Events for {@link TreeBranch}.
+ * @sealed @alpha
+ */
+export interface TreeBranchEvents {
+    /**
+     * The stored schema for the document has changed.
+     */
+    schemaChanged(): void;
+    /**
+     * Fired when:
+     * - a local commit is applied outside of a transaction
+     * - a local transaction is committed
+     *
+     * The event is not fired when:
+     * - a local commit is applied within a transaction
+     * - a remote commit is applied
+     *
+     * @param data - information about the commit that was applied
+     * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,
+     * this commit is not revertible.
+     */
+    commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
+}
 /**
  * Events for {@link TreeView}.
  * @sealed @public
@@ -360,4 +472,9 @@ export interface TreeViewEvents {
      */
     commitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;
 }
+/**
+ * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
+ * @alpha
+ */
+export declare function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(view: TreeView<TSchema>): TreeViewAlpha<TSchema>;
 //# sourceMappingURL=tree.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAGnF,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,oCAAoC,EACzC,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EAExB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAOjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,QAAQ,CAAC,KAAK,SAAS,mBAAmB,EACzC,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAClC,QAAQ,CAAC,KAAK,CAAC,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAM,SAAQ,YAAY,EAAE,cAAc;CAAG;AAE9D;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyEG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACpC;AAOD;;;GAGG;AACH,MAAM,WAAW,sBAAsB,CACtC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,CACxD,SAAQ,yBAAyB;IAClC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,qBAAqB,CACjC,KAAK,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,CAC9D,YAAW,QAAQ,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAErD,SAAS,CAAC,UAAU,EAAG,WAAW,CAAC;IAEnC;;OAEG;IACH,SAAgB,MAAM,EAAE,OAAO,CAAC;IAEhC;;OAEG;IACH,SAAgB,sBAAsB,EAAE,OAAO,CAAC;IAEhD;;OAEG;IACH,SAAgB,gBAAgB,EAAE,OAAO,CAAC;IAE1C;;OAEG;gBACgB,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC;CA+BzD;AAWD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAsFlF;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAE9C;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,OAAO,SAAS,mBAAmB,EAChD,MAAM,EAAE,OAAO,GACb,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAElC;;;;OAIG;IACH,IAAI,IAAI,UAAU,CAAC;IAEnB;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAEzD;;;;;;;;;;OAUG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAErC;;;;;;;;;OASG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,QAAQ,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,CAAE,SAAQ,WAAW;IACxF;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,IAAI,0BAA0B,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,IAAI,CAAC,OAAO,EAAE,oCAAoC,CAAC,OAAO,CAAC,EAAE;IAEjE;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC;IAElD;;;;;;;;;;;;;OAaG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,oCAAoC,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAEzE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAC7B,EAAE,CAAC,GAAG,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,CAC/D,SAAQ,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,EAClE,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC3B,IAAI,IAAI,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAEnC,IAAI,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE;IAE5C,UAAU,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;IAGpD,IAAI,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;CAChE;AAED;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACzC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CAKhC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI,CAAC;IAEtB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAC7E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,mBAAmB,EAClE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,GACrB,aAAa,CAAC,OAAO,CAAC,CAExB"}

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

@@ -5,7 +5,7 @@
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
 import { FieldKind, } from "../schemaTypes.js";
 import { NodeKind } from "../core/index.js";
-import { toStoredSchema } from "../toFlexSchema.js";
+import { toStoredSchema } from "../toStoredSchema.js";
 import { LeafNodeSchema } from "../leafNodeSchema.js";
 import { assert } from "@fluidframework/core-utils/internal";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
@@ -45,7 +45,7 @@ export class TreeViewConfiguration {
         if (ambiguityErrors.length !== 0) {
             // Duplicate errors are common since when two types conflict, both orders error:
             const deduplicated = new Set(ambiguityErrors);
-            throw new UsageError(`Ambigious schema found:\n${[...deduplicated].join("\n")}`);
+            throw new UsageError(`Ambiguous schema found:\n${[...deduplicated].join("\n")}`);
         }
         // Eagerly perform this conversion to surface errors sooner.
         toStoredSchema(config.schema);
@@ -130,4 +130,11 @@ export function checkUnion(union, errors) {
         }
     }
 }
+/**
+ * Retrieve the {@link TreeViewAlpha | alpha API} for a {@link TreeView}.
+ * @alpha
+ */
+export function asTreeViewAlpha(view) {
+    return view;
+}
 //# sourceMappingURL=tree.js.map