@fluidframework/tree 2.0.0-rc.2.0.2 → 2.0.0-rc.3.0.0

package/dist/simple-tree/schemaFactory.js

@@ -4,69 +4,40 @@
  * Licensed under the MIT License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.structuralName = exports.createTree = exports.SchemaFactory = exports.schemaFromValue = void 0;
-const core_utils_1 = require("@fluidframework/core-utils");
-const telemetry_utils_1 = require("@fluidframework/telemetry-utils");
-const index_js_1 = require("../util/index.js");
-const index_js_2 = require("../feature-libraries/index.js");
-const index_js_3 = require("../domains/index.js");
+exports.structuralName = exports.SchemaFactory = exports.schemaFromValue = void 0;
+const internal_1 = require("@fluidframework/core-utils/internal");
+const internal_2 = require("@fluidframework/telemetry-utils/internal");
+const index_js_1 = require("../feature-libraries/index.js");
+const index_js_2 = require("../util/index.js");
+const leafNodeSchema_js_1 = require("./leafNodeSchema.js");
 const proxies_js_1 = require("./proxies.js");
-const toFlexSchema_js_1 = require("./toFlexSchema.js");
+const schemaCaching_js_1 = require("./schemaCaching.js");
 const schemaTypes_js_1 = require("./schemaTypes.js");
+const arrayNode_js_1 = require("./arrayNode.js");
 const types_js_1 = require("./types.js");
-/**
- * Instances of this class are schema for leaf nodes.
- * @remarks
- * Unlike other schema, leaf schema are class instances instead of classes themselves.
- * This is because the instance type (the tree node type) for leaves are not objects,
- * so those instances can't be instances of a schema based class.
- * @privateRemarks
- * This class refers to the underlying flex tree schema in its constructor, so this class can't be included in the package API.
- */
-class LeafNodeSchema {
-    create(data) {
-        return data;
-    }
-    constructor(schema) {
-        this.kind = schemaTypes_js_1.NodeKind.Leaf;
-        this.implicitlyConstructable = true;
-        (0, toFlexSchema_js_1.setFlexSchemaFromClassSchema)(this, schema);
-        this.identifier = schema.name;
-        this.info = schema.info;
-    }
-}
-/**
- * Wrapper around LeafNodeSchema's constructor that provides the return type that is desired in the package public API.
- */
-function makeLeaf(schema) {
-    return new LeafNodeSchema(schema);
-}
-// Leaf schema shared between all SchemaFactory instances.
-const stringSchema = makeLeaf(index_js_3.leaf.string);
-const numberSchema = makeLeaf(index_js_3.leaf.number);
-const booleanSchema = makeLeaf(index_js_3.leaf.boolean);
-const nullSchema = makeLeaf(index_js_3.leaf.null);
-const handleSchema = makeLeaf(index_js_3.leaf.handle);
+const objectNode_js_1 = require("./objectNode.js");
+const mapNode_js_1 = require("./mapNode.js");
+const schemaFactoryRecursive_js_1 = require("./schemaFactoryRecursive.js");
 /**
  * Gets the leaf domain schema compatible with a given {@link TreeValue}.
  */
 function schemaFromValue(value) {
     switch (typeof value) {
         case "boolean":
-            return booleanSchema;
+            return leafNodeSchema_js_1.booleanSchema;
         case "number":
-            return numberSchema;
+            return leafNodeSchema_js_1.numberSchema;
         case "string":
-            return stringSchema;
+            return leafNodeSchema_js_1.stringSchema;
         case "object": {
             if (value === null) {
-                return nullSchema;
+                return leafNodeSchema_js_1.nullSchema;
             }
-            (0, core_utils_1.assert)((0, index_js_2.isFluidHandle)(value), 0x87e /* invalid TreeValue */);
-            return handleSchema;
+            (0, internal_1.assert)((0, index_js_1.isFluidHandle)(value), 0x87e /* invalid TreeValue */);
+            return leafNodeSchema_js_1.handleSchema;
         }
         default:
-            (0, core_utils_1.unreachableCase)(value);
+            (0, internal_1.unreachableCase)(value);
     }
 }
 exports.schemaFromValue = schemaFromValue;
@@ -152,7 +123,7 @@ class SchemaFactory {
          * We should be much more clear about what happens if you use problematic values.
          * We should validate and/or normalize them when inserting content.
          */
-        this.string = stringSchema;
+        this.string = leafNodeSchema_js_1.stringSchema;
         /**
          * {@link TreeNodeSchema} for holding a JavaScript `number`.
          *
@@ -167,11 +138,11 @@ class SchemaFactory {
          * We should be much more clear about what happens if you use problematic values.
          * We should validate and/or normalize them when inserting content.
          */
-        this.number = numberSchema;
+        this.number = leafNodeSchema_js_1.numberSchema;
         /**
          * {@link TreeNodeSchema} for holding a boolean.
          */
-        this.boolean = booleanSchema;
+        this.boolean = leafNodeSchema_js_1.booleanSchema;
         /**
          * {@link TreeNodeSchema} for JavaScript `null`.
          *
@@ -180,11 +151,11 @@ class SchemaFactory {
          * This {@link TreeNodeSchema} node provides the option to include nulls in trees when desired.
          * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.
          */
-        this.null = nullSchema;
+        this.null = leafNodeSchema_js_1.nullSchema;
         /**
          * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#(IFluidHandle:interface)}.
          */
-        this.handle = handleSchema;
+        this.handle = leafNodeSchema_js_1.handleSchema;
     }
     scoped(name) {
         return (this.scope === undefined ? `${name}` : `${this.scope}.${name}`);
@@ -203,12 +174,12 @@ class SchemaFactory {
             constructor(input) {
                 super();
                 // Currently this just does validation. All other logic is in the subclass.
-                if ((0, index_js_2.isFlexTreeNode)(input)) {
-                    (0, core_utils_1.assert)((0, proxies_js_1.getClassSchema)(input.schema) === this.constructor, 0x83b /* building node with wrong schema */);
+                if ((0, index_js_1.isFlexTreeNode)(input)) {
+                    (0, internal_1.assert)((0, schemaCaching_js_1.tryGetSimpleNodeSchema)(input.schema) === this.constructor, 0x83b /* building node with wrong schema */);
                 }
                 if ((0, proxies_js_1.isTreeNode)(input)) {
                     // TODO: update this once we have better support for deep-copying and move operations.
-                    throw new telemetry_utils_1.UsageError("Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.");
+                    throw new internal_2.UsageError("Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.");
                 }
             }
             get [schemaTypes_js_1.type]() {
@@ -220,89 +191,41 @@ class SchemaFactory {
         schema.info = t;
         schema.implicitlyConstructable = implicitlyConstructable;
         // Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.
-        (0, index_js_2.markEager)(schema);
+        (0, index_js_1.markEager)(schema);
         return schema;
     }
     /**
-     * Define a {@link TreeNodeSchema} for an object node.
+     * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
      *
      * @param name - Unique identifier for this schema within this factory's scope.
+     * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
      */
-    object(name, t) {
-        class schema extends this.nodeSchema(name, schemaTypes_js_1.NodeKind.Object, t, true) {
-            constructor(input) {
-                super(input);
-                // Differentiate between the following cases:
-                //
-                // Case 1: Direct construction (POJO emulation)
-                //
-                //     const Foo = schemaFactory.object("Foo", {bar: schemaFactory.number});
-                //
-                //     assert.deepEqual(new Foo({ bar: 42 }), { bar: 42 },
-                //		   "Prototype chain equivalent to POJO.");
-                //
-                // Case 2: Subclass construction (Customizable Object)
-                //
-                // 	   class Foo extends schemaFactory.object("Foo", {bar: schemaFactory.number}) {}
-                //
-                // 	   assert.notDeepEqual(new Foo({ bar: 42 }), { bar: 42 },
-                // 	       "Subclass prototype chain differs from POJO.");
-                //
-                // In Case 1 (POJO emulation), the prototype chain match '{}' (proxyTarget = undefined)
-                // In Case 2 (Customizable Object), the prototype chain include the user's subclass (proxyTarget = this)
-                const customizable = this.constructor !== schema;
-                const proxyTarget = customizable ? this : undefined;
-                if ((0, index_js_2.isFlexTreeNode)(input)) {
-                    return (0, proxies_js_1.createNodeProxy)(input, customizable, proxyTarget);
-                }
-                else {
-                    const flexSchema = (0, toFlexSchema_js_1.getFlexSchema)(this.constructor);
-                    return (0, proxies_js_1.createRawNodeProxy)(flexSchema, input, customizable, proxyTarget);
-                }
-            }
-        }
-        return schema;
+    object(name, fields) {
+        return (0, objectNode_js_1.objectSchema)(this.nodeSchema(name, schemaTypes_js_1.NodeKind.Object, fields, true));
     }
     map(nameOrAllowedTypes, allowedTypes) {
         if (allowedTypes === undefined) {
             const types = nameOrAllowedTypes;
             const fullName = structuralName("Map", types);
-            return (0, index_js_1.getOrCreate)(this.structuralTypes, fullName, () => this.namedMap_internal(fullName, nameOrAllowedTypes, false, true));
+            return (0, index_js_2.getOrCreate)(this.structuralTypes, fullName, () => this.namedMap(fullName, nameOrAllowedTypes, false, true));
         }
-        return this.namedMap_internal(nameOrAllowedTypes, allowedTypes, true, true);
+        return this.namedMap(nameOrAllowedTypes, allowedTypes, true, true);
     }
     /**
      * Define a {@link TreeNodeSchema} for a {@link (TreeMapNode:interface)}.
      *
      * @param name - Unique identifier for this schema within this factory's scope.
-     *
-     * @remarks See remarks on {@link SchemaFactory.namedArray_internal}.
      */
-    namedMap_internal(name, allowedTypes, customizable, implicitlyConstructable) {
-        class schema extends this.nodeSchema(name, schemaTypes_js_1.NodeKind.Map, allowedTypes, implicitlyConstructable) {
-            constructor(input) {
-                super(input);
-                const proxyTarget = customizable ? this : undefined;
-                if ((0, index_js_2.isFlexTreeNode)(input)) {
-                    return (0, proxies_js_1.createNodeProxy)(input, customizable, proxyTarget);
-                }
-                else {
-                    const flexSchema = (0, toFlexSchema_js_1.getFlexSchema)(this.constructor);
-                    return (0, proxies_js_1.createRawNodeProxy)(flexSchema, input, customizable, proxyTarget);
-                }
-            }
-        }
-        // Setup map functionality
-        Object.defineProperties(schema.prototype, proxies_js_1.mapStaticDispatchMap);
-        return schema;
+    namedMap(name, allowedTypes, customizable, implicitlyConstructable) {
+        return (0, mapNode_js_1.mapSchema)(this.nodeSchema(name, schemaTypes_js_1.NodeKind.Map, allowedTypes, implicitlyConstructable), customizable);
     }
     array(nameOrAllowedTypes, allowedTypes) {
         if (allowedTypes === undefined) {
             const types = nameOrAllowedTypes;
             const fullName = structuralName("Array", types);
-            return (0, index_js_1.getOrCreate)(this.structuralTypes, fullName, () => this.namedArray_internal(fullName, nameOrAllowedTypes, false, true));
+            return (0, index_js_2.getOrCreate)(this.structuralTypes, fullName, () => this.namedArray(fullName, nameOrAllowedTypes, false, true));
         }
-        return this.namedArray_internal(nameOrAllowedTypes, allowedTypes, true, true);
+        return this.namedArray(nameOrAllowedTypes, allowedTypes, true, true);
     }
     /**
      * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
@@ -312,89 +235,113 @@ class SchemaFactory {
      * @remarks
      * This is not intended to be used directly, use the overload of `array` which takes a name instead.
      * This is only public to work around a compiler limitation.
+     */
+    namedArray(name, allowedTypes, customizable, implicitlyConstructable) {
+        return (0, arrayNode_js_1.arraySchema)(this.nodeSchema(name, schemaTypes_js_1.NodeKind.Array, allowedTypes, implicitlyConstructable), customizable);
+    }
+    /**
+     * Make a field optional instead of the default, which is required.
      *
-     * @privateRemarks
-     * TODO: this should be made private or protected.
-     * Doing so breaks due to:
-     * `src/class-tree/schemaFactoryRecursive.ts:42:9 - error TS2310: Type 'Array' recursively references itself as a base type.`
-     * Once recursive APIs are better sorted out and integrated into this class, switch this back to private.
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
      */
-    namedArray_internal(name, allowedTypes, customizable, implicitlyConstructable) {
-        // This class returns a proxy from its constructor to handle numeric indexing.
-        // Alternatively it could extend a normal class which gets tons of numeric properties added.
-        class schema extends this.nodeSchema(name, schemaTypes_js_1.NodeKind.Array, allowedTypes, implicitlyConstructable) {
-            get length() {
-                return (0, proxies_js_1.getSequenceField)(this).length;
-            }
-            constructor(input) {
-                super(input);
-                const proxyTarget = customizable ? this : undefined;
-                if ((0, index_js_2.isFlexTreeNode)(input)) {
-                    return (0, proxies_js_1.createNodeProxy)(input, customizable, proxyTarget);
+    optional(t, props) {
+        return new schemaTypes_js_1.FieldSchema(schemaTypes_js_1.FieldKind.Optional, t, props);
+    }
+    /**
+     * Make a field explicitly required.
+     *
+     * @param t - The types allowed under the field.
+     * @param props - Optional properties to associate with the field.
+     *
+     * @remarks
+     * Fields are required by default, but this API can be used to make the required nature explicit in the schema,
+     * and allows associating custom {@link FieldProps | properties} with the field.
+     */
+    required(t, props) {
+        return new schemaTypes_js_1.FieldSchema(schemaTypes_js_1.FieldKind.Required, t, props);
+    }
+    /**
+     * Make a field of type identifier instead of the default which is required.
+     */
+    get identifier() {
+        return new schemaTypes_js_1.FieldSchema(schemaTypes_js_1.FieldKind.Identifier, this.string);
+    }
+    /**
+     * {@link SchemaFactory.object} except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
+     * @remarks
+     * This version of {@link SchemaFactory.object} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+     *
+     * Additionally `ImplicitlyConstructable` is disabled (forcing use of constructor) to avoid
+     * `error TS2589: Type instantiation is excessively deep and possibly infinite.`
+     * which otherwise gets reported at sometimes incorrect source locations that vary based on incremental builds.
+     */
+    objectRecursive(name, t) {
+        return this.object(name, t);
+    }
+    /**
+     * {@link SchemaFactory.optional} except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
+     * @remarks
+     * This version of {@link SchemaFactory.optional} has fewer type constraints to work around TypeScript limitations, see {@link Unenforced}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+     */
+    optionalRecursive(t) {
+        return (0, schemaFactoryRecursive_js_1.createFieldSchemaUnsafe)(schemaTypes_js_1.FieldKind.Optional, t);
+    }
+    /**
+     * `SchemaFactory.array` except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
+     * @remarks
+     * This version of `SchemaFactory.array` uses the same workarounds as {@link SchemaFactory.objectRecursive}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
+     */
+    arrayRecursive(name, allowedTypes) {
+        class RecursiveArray extends this.namedArray(name, allowedTypes, true, false) {
+            constructor(data) {
+                if ((0, index_js_1.isFlexTreeNode)(data)) {
+                    super(data);
                 }
                 else {
-                    const flexSchema = (0, toFlexSchema_js_1.getFlexSchema)(this.constructor);
-                    return (0, proxies_js_1.createRawNodeProxy)(flexSchema, [...input], customizable, proxyTarget);
+                    super(data);
                 }
             }
         }
-        // Setup array functionality
-        Object.defineProperties(schema.prototype, proxies_js_1.arrayNodePrototypeProperties);
-        return schema;
-    }
-    /**
-     * Make a field optional instead of the default which is required.
-     */
-    optional(t) {
-        return new schemaTypes_js_1.FieldSchema(schemaTypes_js_1.FieldKind.Optional, t);
+        return RecursiveArray;
     }
     /**
-     * Function which can be used for its compile time side-effects to tweak the evaluation order of recursive types to make them compile.
+     * `SchemaFactory.map` except tweaked to work better for recursive types.
+     * Use with {@link ValidateRecursiveSchema} for improved type safety.
      * @remarks
-     * Some related information in https://github.com/microsoft/TypeScript/issues/55758.
-     *
-     * Also be aware that code which relies on this tends to break VSCode's IntelliSense every time anything related to that code (even comments) is edited.
-     * Running the command `TypeScript: Restart TS Server` with the schema file focused should fix it.
-     * Sometimes this does not work: closing all open files except the schema before running the command can help.
-     * Real compile errors (for example elsewhere in the file) can also cause the IntelliSense to not work correctly ever after `TypeScript: Restart TS Server`.
-     *
-     * Intellisense has also shown problems when schema files with recursive types are part of a cyclic file dependency.
-     * Splitting the schema into its own file with minimal dependencies can help with this.
-     *
-     * Ensure `"noImplicitAny": true` is set in the `tsconfig.json`.
-     * Without it, recursive types that are not working properly can infer `any` and give very non-type-safe results instead of erroring.
-     *
-     * @example
-     * ```typescript
-     * const factory = new SchemaFactory("example");
-     * const recursiveReference = () => RecursiveObject;
-     * factory.fixRecursiveReference(recursiveReference);
-     * export class RecursiveObject extends factory.object("exampleObject", {
-     * 	recursive: [recursiveReference],
-     * }) {}
-     * ```
-     * @deprecated Use special `recursive` versions of builders instead of relying on this.
+     * This version of `SchemaFactory.map` uses the same workarounds as {@link SchemaFactory.objectRecursive}.
+     * See {@link ValidateRecursiveSchema} for additional information about using recursive schema.
      */
-    fixRecursiveReference(...types) { }
-}
-exports.SchemaFactory = SchemaFactory;
-// TODO: unify this with logic in getOrCreateNodeProxy
-function createTree(schema, data) {
-    if (typeof schema === "function") {
-        return new schema(data);
+    mapRecursive(name, allowedTypes) {
+        class MapSchema extends this.namedMap(name, allowedTypes, true, false) {
+            constructor(data) {
+                if ((0, index_js_1.isFlexTreeNode)(data)) {
+                    super(data);
+                }
+                else {
+                    super(new Map(data));
+                }
+            }
+        }
+        return MapSchema;
     }
-    return schema.create(data);
 }
-exports.createTree = createTree;
+exports.SchemaFactory = SchemaFactory;
 function structuralName(collectionName, allowedTypes) {
     let inner;
-    if (!(0, index_js_1.isReadonlyArray)(allowedTypes)) {
+    if (!(0, index_js_2.isReadonlyArray)(allowedTypes)) {
         return structuralName(collectionName, [allowedTypes]);
     }
     else {
         const names = allowedTypes.map((t) => {
             // Ensure that lazy types (functions) don't slip through here.
-            (0, core_utils_1.assert)(!(0, index_js_2.isLazy)(t), 0x83d /* invalid type provided */);
+            (0, internal_1.assert)(!(0, index_js_1.isLazy)(t), 0x83d /* invalid type provided */);
             return t.identifier;
         });
         // Ensure name is order independent

package/dist/simple-tree/schemaFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../src/simple-tree/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\";\nimport { UsageError } from \"@fluidframework/telemetry-utils\";\nimport { RestrictiveReadonlyRecord, getOrCreate, isReadonlyArray } from \"../util/index.js\";\nimport {\n\tFlexTreeNode,\n\tLeafNodeSchema as FlexLeafNodeSchema,\n\tisFlexTreeNode,\n\tFlexObjectNodeSchema,\n\tisLazy,\n\tmarkEager,\n\tFlexMapNodeSchema,\n\tFlexFieldNodeSchema,\n\tisFluidHandle,\n} from \"../feature-libraries/index.js\";\nimport { leaf } from \"../domains/index.js\";\nimport { TreeNodeSchemaIdentifier, TreeValue } from \"../core/index.js\";\nimport {\n\tcreateNodeProxy,\n\tcreateRawNodeProxy,\n\tgetClassSchema,\n\tgetSequenceField,\n\tarrayNodePrototypeProperties,\n\tmapStaticDispatchMap,\n\tisTreeNode,\n} from \"./proxies.js\";\nimport { getFlexSchema, setFlexSchemaFromClassSchema } from \"./toFlexSchema.js\";\nimport {\n\tAllowedTypes,\n\tFieldKind,\n\tFieldSchema,\n\tImplicitAllowedTypes,\n\tImplicitFieldSchema,\n\tInsertableObjectFromSchemaRecord,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n\tInsertableTypedNode,\n\tNodeFromSchema,\n\tNodeKind,\n\tObjectFromSchemaRecord,\n\tTreeMapNode,\n\tTreeNodeFromImplicitAllowedTypes,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tTreeNodeSchemaNonClass,\n\tWithType,\n\ttype,\n} from \"./schemaTypes.js\";\nimport { TreeNode } from \"./types.js\";\nimport { TreeArrayNode } from \"./treeArrayNode.js\";\n\n/**\n * Instances of this class are schema for leaf nodes.\n * @remarks\n * Unlike other schema, leaf schema are class instances instead of classes themselves.\n * This is because the instance type (the tree node type) for leaves are not objects,\n * so those instances can't be instances of a schema based class.\n * @privateRemarks\n * This class refers to the underlying flex tree schema in its constructor, so this class can't be included in the package API.\n */\nclass LeafNodeSchema<T extends FlexLeafNodeSchema>\n\timplements TreeNodeSchemaNonClass<UnbrandedName<T>, NodeKind.Leaf, TreeValue<T[\"info\"]>>\n{\n\tpublic readonly identifier: UnbrandedName<T>;\n\tpublic readonly kind = NodeKind.Leaf;\n\tpublic readonly info: T[\"info\"];\n\tpublic readonly implicitlyConstructable = true as const;\n\tpublic create(data: TreeValue<T[\"info\"]>): TreeValue<T[\"info\"]> {\n\t\treturn data;\n\t}\n\n\tpublic constructor(schema: T) {\n\t\tsetFlexSchemaFromClassSchema(this, schema);\n\t\tthis.identifier = schema.name as UnbrandedName<T>;\n\t\tthis.info = schema.info;\n\t}\n}\n\n/**\n * Wrapper around LeafNodeSchema's constructor that provides the return type that is desired in the package public API.\n */\nfunction makeLeaf<T extends FlexLeafNodeSchema>(\n\tschema: T,\n): TreeNodeSchema<UnbrandedName<T>, NodeKind.Leaf, TreeValue<T[\"info\"]>, TreeValue<T[\"info\"]>> {\n\treturn new LeafNodeSchema(schema);\n}\n\n// Leaf schema shared between all SchemaFactory instances.\nconst stringSchema = makeLeaf(leaf.string);\nconst numberSchema = makeLeaf(leaf.number);\nconst booleanSchema = makeLeaf(leaf.boolean);\nconst nullSchema = makeLeaf(leaf.null);\nconst handleSchema = makeLeaf(leaf.handle);\n\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\ntype UnbrandedName<T extends FlexLeafNodeSchema> = T[\"name\"] extends TreeNodeSchemaIdentifier<\n\tinfer Name extends string\n>\n\t? Name\n\t: T[\"name\"];\n\n/**\n * The name of a schema produced by {@link SchemaFactory}, including its optional scope prefix.\n *\n * @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 {@link ScopedSchemaName|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 * |                     | Customizable | POJO Emulation |\n * | ------------------- | ------------ |--------------- |\n * | Declaration         | `class X extends schemaFactory.object(\"x\", {}) {}` | `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>; `\n * | Allows adding \"local\" (non-persisted) members | Yes. Members (including methods) can be added to class.        | No. Attempting to set non-field members will error. |\n * | Prototype | The user defined class | `Object.prototype`, `Map.prototype` or `Array.prototype` depending on node kind |\n * | Structurally named Schema | Not Supported | Supported |\n * | Explicitly named Objects | Supported | Supported |\n * | Explicitly named Maps and Arrays | Supported: Both declaration approaches can be used | Not Supported |\n * | node.js assert.deepEqual | Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields. | 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 * | IntelliSense | Shows and links to user defined class by name: `X` | Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">` |\n * | Recursion | Supported with special declaration patterns. | Unsupported: Generated d.ts files replace recursive references with `any`, breaking 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 * @sealed @public\n */\nexport class SchemaFactory<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> {\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\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 (this.scope === undefined ? `${name}` : `${this.scope}.${name}`) as ScopedSchemaName<\n\t\t\tTScope,\n\t\t\tName\n\t\t>;\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 * Construct a class that provides the common parts all TreeNodeSchemaClass share.\n\t * More specific schema extend this class.\n\t */\n\tprivate nodeSchema<\n\t\tconst Name extends TName | string,\n\t\tconst TKind extends NodeKind,\n\t\tT,\n\t\tconst TImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tkind: TKind,\n\t\tt: T,\n\t\timplicitlyConstructable: TImplicitlyConstructable,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tTKind,\n\t\tTreeNode & WithType<ScopedSchemaName<TScope, Name>>,\n\t\tFlexTreeNode | unknown,\n\t\tTImplicitlyConstructable,\n\t\tT\n\t> {\n\t\tconst identifier = this.scoped(name);\n\t\tclass schema extends TreeNode implements WithType<ScopedSchemaName<TScope, Name>> {\n\t\t\tpublic static readonly identifier = identifier;\n\t\t\tpublic static readonly kind = kind;\n\t\t\tpublic static readonly info = t;\n\t\t\tpublic static readonly implicitlyConstructable: TImplicitlyConstructable =\n\t\t\t\timplicitlyConstructable;\n\t\t\t/**\n\t\t\t * This constructor only does validation of the input, and should be passed the argument from the derived type unchanged.\n\t\t\t * It is up to the derived type to actually do something with this value.\n\t\t\t */\n\t\t\tpublic constructor(input: FlexTreeNode | unknown) {\n\t\t\t\tsuper();\n\t\t\t\t// Currently this just does validation. All other logic is in the subclass.\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\tassert(\n\t\t\t\t\t\tgetClassSchema(input.schema) === this.constructor,\n\t\t\t\t\t\t0x83b /* building node with wrong schema */,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tif (isTreeNode(input)) {\n\t\t\t\t\t// TODO: update this once we have better support for deep-copying and move operations.\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tpublic get [type](): ScopedSchemaName<TScope, Name> {\n\t\t\t\treturn identifier;\n\t\t\t}\n\t\t}\n\t\t// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\n\t\tmarkEager(schema);\n\t\treturn schema;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for an object node.\n\t *\n\t * @param name - Unique identifier for this schema within this factory's scope.\n\t */\n\tpublic object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n\t>(name: Name, t: T) {\n\t\tclass schema extends this.nodeSchema(name, NodeKind.Object, t, true) {\n\t\t\tpublic constructor(input: InsertableObjectFromSchemaRecord<T>) {\n\t\t\t\tsuper(input);\n\n\t\t\t\t// Differentiate between the following cases:\n\t\t\t\t//\n\t\t\t\t// Case 1: Direct construction (POJO emulation)\n\t\t\t\t//\n\t\t\t\t//     const Foo = schemaFactory.object(\"Foo\", {bar: schemaFactory.number});\n\t\t\t\t//\n\t\t\t\t//     assert.deepEqual(new Foo({ bar: 42 }), { bar: 42 },\n\t\t\t\t//\t\t   \"Prototype chain equivalent to POJO.\");\n\t\t\t\t//\n\t\t\t\t// Case 2: Subclass construction (Customizable Object)\n\t\t\t\t//\n\t\t\t\t// \t   class Foo extends schemaFactory.object(\"Foo\", {bar: schemaFactory.number}) {}\n\t\t\t\t//\n\t\t\t\t// \t   assert.notDeepEqual(new Foo({ bar: 42 }), { bar: 42 },\n\t\t\t\t// \t       \"Subclass prototype chain differs from POJO.\");\n\t\t\t\t//\n\t\t\t\t// In Case 1 (POJO emulation), the prototype chain match '{}' (proxyTarget = undefined)\n\t\t\t\t// In Case 2 (Customizable Object), the prototype chain include the user's subclass (proxyTarget = this)\n\t\t\t\tconst customizable = this.constructor !== schema;\n\t\t\t\tconst proxyTarget = customizable ? this : undefined;\n\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(input, customizable, proxyTarget) as schema;\n\t\t\t\t} else {\n\t\t\t\t\tconst flexSchema = getFlexSchema(this.constructor as TreeNodeSchema);\n\t\t\t\t\treturn createRawNodeProxy(\n\t\t\t\t\t\tflexSchema as FlexObjectNodeSchema,\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tproxyTarget,\n\t\t\t\t\t) as unknown as schema;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn schema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Object,\n\t\t\tTreeNode & ObjectFromSchemaRecord<T> & WithType<ScopedSchemaName<TScope, Name>>,\n\t\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\t\ttrue,\n\t\t\tT\n\t\t>;\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): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>,\n\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<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>>,\n\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\tpublic map<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<\n\t\tstring,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tIterable<[string, 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(\"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_internal(\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 TreeNodeSchemaClass<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\t\t\ttrue,\n\t\t\t\tT\n\t\t\t>;\n\t\t}\n\t\treturn this.namedMap_internal(nameOrAllowedTypes as TName, allowedTypes, true, true);\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\t * @remarks See remarks on {@link SchemaFactory.namedArray_internal}.\n\t */\n\tpublic namedMap_internal<\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) {\n\t\tclass schema extends this.nodeSchema(\n\t\t\tname,\n\t\t\tNodeKind.Map,\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t) {\n\t\t\tpublic constructor(\n\t\t\t\tinput: Iterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\t\t) {\n\t\t\t\tsuper(input);\n\n\t\t\t\tconst proxyTarget = customizable ? this : undefined;\n\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(input, customizable, proxyTarget) as schema;\n\t\t\t\t} else {\n\t\t\t\t\tconst flexSchema = getFlexSchema(this.constructor as TreeNodeSchema);\n\t\t\t\t\treturn createRawNodeProxy(\n\t\t\t\t\t\tflexSchema as FlexMapNodeSchema,\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tproxyTarget,\n\t\t\t\t\t) as unknown as schema;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Setup map functionality\n\t\tObject.defineProperties(schema.prototype, mapStaticDispatchMap);\n\n\t\treturn schema as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>,\n\t\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\t\tImplicitlyConstructable,\n\t\t\tT\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): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>>,\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>>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t>;\n\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_internal(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\treturn this.namedArray_internal(nameOrAllowedTypes as TName, allowedTypes, true, true);\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\t * @privateRemarks\n\t * TODO: this should be made private or protected.\n\t * Doing so breaks due to:\n\t * `src/class-tree/schemaFactoryRecursive.ts:42:9 - error TS2310: Type 'Array' recursively references itself as a base type.`\n\t * Once recursive APIs are better sorted out and integrated into this class, switch this back to private.\n\t */\n\tpublic namedArray_internal<\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) {\n\t\t// This class returns a proxy from its constructor to handle numeric indexing.\n\t\t// Alternatively it could extend a normal class which gets tons of numeric properties added.\n\t\tclass schema extends this.nodeSchema(\n\t\t\tname,\n\t\t\tNodeKind.Array,\n\t\t\tallowedTypes,\n\t\t\timplicitlyConstructable,\n\t\t) {\n\t\t\t[x: number]: TreeNodeFromImplicitAllowedTypes<T>;\n\t\t\tpublic get length(): number {\n\t\t\t\treturn getSequenceField(this as unknown as TreeArrayNode).length;\n\t\t\t}\n\t\t\tpublic constructor(input: Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>) {\n\t\t\t\tsuper(input);\n\n\t\t\t\tconst proxyTarget = customizable ? this : undefined;\n\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(input, customizable, proxyTarget) as schema;\n\t\t\t\t} else {\n\t\t\t\t\tconst flexSchema = getFlexSchema(this.constructor as TreeNodeSchema);\n\t\t\t\t\treturn createRawNodeProxy(\n\t\t\t\t\t\tflexSchema as FlexFieldNodeSchema,\n\t\t\t\t\t\t[...input],\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tproxyTarget,\n\t\t\t\t\t) as unknown as schema;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Setup array functionality\n\t\tObject.defineProperties(schema.prototype, arrayNodePrototypeProperties);\n\n\t\treturn schema as unknown as TreeNodeSchemaClass<\n\t\t\tScopedSchemaName<TScope, Name>,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\tImplicitlyConstructable,\n\t\t\tT\n\t\t>;\n\t}\n\n\t/**\n\t * Make a field optional instead of the default which is required.\n\t */\n\tpublic optional<const T extends ImplicitAllowedTypes>(\n\t\tt: T,\n\t): FieldSchema<FieldKind.Optional, T> {\n\t\treturn new FieldSchema(FieldKind.Optional, t);\n\t}\n\n\t/**\n\t * Function which can be used for its compile time side-effects to tweak the evaluation order of recursive types to make them compile.\n\t * @remarks\n\t * Some related information in https://github.com/microsoft/TypeScript/issues/55758.\n\t *\n\t * Also be aware that code which relies on this tends to break VSCode's IntelliSense every time anything related to that code (even comments) is edited.\n\t * Running the command `TypeScript: Restart TS Server` with the schema file focused should fix it.\n\t * Sometimes this does not work: closing all open files except the schema before running the command can help.\n\t * Real compile errors (for example elsewhere in the file) can also cause the IntelliSense to not work correctly ever after `TypeScript: Restart TS Server`.\n\t *\n\t * Intellisense has also shown problems when schema files with recursive types are part of a cyclic file dependency.\n\t * Splitting the schema into its own file with minimal dependencies can help with this.\n\t *\n\t * Ensure `\"noImplicitAny\": true` is set in the `tsconfig.json`.\n\t * Without it, recursive types that are not working properly can infer `any` and give very non-type-safe results instead of erroring.\n\t *\n\t * @example\n\t * ```typescript\n\t * const factory = new SchemaFactory(\"example\");\n\t * const recursiveReference = () => RecursiveObject;\n\t * factory.fixRecursiveReference(recursiveReference);\n\t * export class RecursiveObject extends factory.object(\"exampleObject\", {\n\t * \trecursive: [recursiveReference],\n\t * }) {}\n\t * ```\n\t * @deprecated Use special `recursive` versions of builders instead of relying on this.\n\t */\n\tpublic fixRecursiveReference<T extends AllowedTypes>(...types: T): void {}\n}\n\n// TODO: unify this with logic in getOrCreateNodeProxy\nexport function createTree<T extends TreeNodeSchema>(\n\tschema: T,\n\tdata: InsertableTypedNode<T> | FlexTreeNode,\n): NodeFromSchema<T> {\n\tif (typeof schema === \"function\") {\n\t\treturn new (schema as TreeNodeSchemaClass<\n\t\t\tany,\n\t\t\tany,\n\t\t\tany,\n\t\t\tInsertableTypedNode<T> | FlexTreeNode\n\t\t>)(data) as NodeFromSchema<T>;\n\t}\n\treturn (\n\t\tschema as TreeNodeSchemaNonClass<any, any, any, InsertableTypedNode<T> | FlexTreeNode>\n\t).create(data) as NodeFromSchema<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\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 are also needed so that a single type name \"Any\" would not collide with the \"any\" case above.\n\t\tinner = JSON.stringify(names);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n"]}
+{"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../src/simple-tree/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\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { TreeValue } from \"../core/index.js\";\nimport {\n\tFlexTreeNode,\n\tUnenforced,\n\tisFlexTreeNode,\n\tisFluidHandle,\n\tisLazy,\n\tmarkEager,\n} from \"../feature-libraries/index.js\";\nimport { RestrictiveReadonlyRecord, getOrCreate, isReadonlyArray } from \"../util/index.js\";\n\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"./leafNodeSchema.js\";\nimport { isTreeNode } from \"./proxies.js\";\nimport { tryGetSimpleNodeSchema } from \"./schemaCaching.js\";\nimport {\n\tFieldKind,\n\tFieldSchema,\n\tImplicitAllowedTypes,\n\tImplicitFieldSchema,\n\tInsertableTreeNodeFromImplicitAllowedTypes,\n\tNodeKind,\n\tTreeNodeSchema,\n\tTreeNodeSchemaClass,\n\tWithType,\n\ttype,\n\ttype FieldProps,\n} from \"./schemaTypes.js\";\nimport { TreeArrayNode, arraySchema } from \"./arrayNode.js\";\nimport { TreeNode } from \"./types.js\";\nimport { InsertableObjectFromSchemaRecord, TreeObjectNode, objectSchema } from \"./objectNode.js\";\nimport { TreeMapNode, mapSchema } from \"./mapNode.js\";\nimport {\n\tInsertableObjectFromSchemaRecordUnsafe,\n\tInsertableTreeNodeFromImplicitAllowedTypesUnsafe,\n\tTreeArrayNodeUnsafe,\n\tTreeMapNodeUnsafe,\n\tTreeObjectNodeUnsafe,\n} from \"./typesUnsafe.js\";\nimport { createFieldSchemaUnsafe } from \"./schemaFactoryRecursive.js\";\n\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 * @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 {@link ScopedSchemaName|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 * |                     | Customizable | POJO Emulation |\n * | ------------------- | ------------ |--------------- |\n * | Declaration         | `class X extends schemaFactory.object(\"x\", {}) {}` | `const X = schemaFactory.object(\"x\", {}); type X = NodeFromSchema<typeof X>; `\n * | Allows adding \"local\" (non-persisted) members | Yes. Members (including methods) can be added to class.        | No. Attempting to set non-field members will error. |\n * | Prototype | The user defined class | `Object.prototype`, `Map.prototype` or `Array.prototype` depending on node kind |\n * | Structurally named Schema | Not Supported | Supported |\n * | Explicitly named Objects | Supported | Supported |\n * | Explicitly named Maps and Arrays | Supported: Both declaration approaches can be used | Not Supported |\n * | node.js assert.deepEqual | Compares like class instances: equal to other nodes of the same type with the same content, including custom local fields. | 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 * | IntelliSense | Shows and links to user defined class by name: `X` | Shows internal type generation logic: `object & TreeNode & ObjectFromSchemaRecord<{}> & WithType<\"test.x\">` |\n * | Recursion | Supported with special declaration patterns. | Unsupported: Generated d.ts files replace recursive references with `any`, breaking 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 * @sealed @public\n */\nexport class SchemaFactory<\n\tout TScope extends string | undefined = string | undefined,\n\tTName extends number | string = string,\n> {\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\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 (this.scope === undefined ? `${name}` : `${this.scope}.${name}`) as ScopedSchemaName<\n\t\t\tTScope,\n\t\t\tName\n\t\t>;\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 * Construct a class that provides the common parts all TreeNodeSchemaClass share.\n\t * More specific schema extend this class.\n\t */\n\tprivate nodeSchema<\n\t\tconst Name extends TName | string,\n\t\tconst TKind extends NodeKind,\n\t\tT,\n\t\tconst TImplicitlyConstructable extends boolean,\n\t>(\n\t\tname: Name,\n\t\tkind: TKind,\n\t\tt: T,\n\t\timplicitlyConstructable: TImplicitlyConstructable,\n\t): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tTKind,\n\t\tTreeNode & WithType<ScopedSchemaName<TScope, Name>>,\n\t\tFlexTreeNode | unknown,\n\t\tTImplicitlyConstructable,\n\t\tT\n\t> {\n\t\tconst identifier = this.scoped(name);\n\t\tclass schema extends TreeNode implements WithType<ScopedSchemaName<TScope, Name>> {\n\t\t\tpublic static readonly identifier = identifier;\n\t\t\tpublic static readonly kind = kind;\n\t\t\tpublic static readonly info = t;\n\t\t\tpublic static readonly implicitlyConstructable: TImplicitlyConstructable =\n\t\t\t\timplicitlyConstructable;\n\t\t\t/**\n\t\t\t * This constructor only does validation of the input, and should be passed the argument from the derived type unchanged.\n\t\t\t * It is up to the derived type to actually do something with this value.\n\t\t\t */\n\t\t\tpublic constructor(input: FlexTreeNode | unknown) {\n\t\t\t\tsuper();\n\t\t\t\t// Currently this just does validation. All other logic is in the subclass.\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\tassert(\n\t\t\t\t\t\ttryGetSimpleNodeSchema(input.schema) === this.constructor,\n\t\t\t\t\t\t0x83b /* building node with wrong schema */,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\tif (isTreeNode(input)) {\n\t\t\t\t\t// TODO: update this once we have better support for deep-copying and move operations.\n\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\"Existing nodes may not be used as the constructor parameter for a new node. The existing node may be used directly instead of creating a new one, used as a child of the new node (if it has not yet been inserted into the tree). If the desired result is copying the provided node, it must be deep copied (since any child node would be parented under both the new and old nodes). Currently no API is provided to make deep copies, but it can be done manually with object spreads - for example `new Foo({...oldFoo})` will work if all fields of `oldFoo` are leaf nodes.\",\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tpublic get [type](): ScopedSchemaName<TScope, Name> {\n\t\t\t\treturn identifier;\n\t\t\t}\n\t\t}\n\t\t// Class objects are functions (callable), so we need a strong way to distinguish between `schema` and `() => schema` when used as a `LazyItem`.\n\t\tmarkEager(schema);\n\t\treturn schema;\n\t}\n\n\t/**\n\t * Define a {@link TreeNodeSchema} 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 RestrictiveReadonlyRecord<string, 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.nodeSchema(name, NodeKind.Object, 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): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, `Map<${string}>`>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, `Map<${string}>`>>,\n\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<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>>,\n\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\ttrue,\n\t\tT\n\t>;\n\n\tpublic map<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): TreeNodeSchema<\n\t\tstring,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tIterable<[string, 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(\"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 TreeNodeSchemaClass<\n\t\t\t\tstring,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\t\t\ttrue,\n\t\t\t\tT\n\t\t\t>;\n\t\t}\n\t\treturn this.namedMap(nameOrAllowedTypes as TName, allowedTypes, true, true);\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): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T> & WithType<ScopedSchemaName<TScope, Name>>,\n\t\tIterable<[string, InsertableTreeNodeFromImplicitAllowedTypes<T>]>,\n\t\tImplicitlyConstructable,\n\t\tT\n\t> {\n\t\treturn mapSchema(\n\t\t\tthis.nodeSchema(name, NodeKind.Map, allowedTypes, implicitlyConstructable),\n\t\t\tcustomizable,\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): TreeNodeSchema<\n\t\tScopedSchemaName<TScope, `Array<${string}>`>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, `Array<${string}>`>>,\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>>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue,\n\t\tT\n\t>;\n\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\treturn this.namedArray(nameOrAllowedTypes as TName, allowedTypes, true, true);\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): TreeNodeSchemaClass<\n\t\tScopedSchemaName<TScope, Name>,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T> & WithType<ScopedSchemaName<TScope, string>>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable,\n\t\tT\n\t> {\n\t\treturn arraySchema(\n\t\t\tthis.nodeSchema(name, NodeKind.Array, allowedTypes, implicitlyConstructable),\n\t\t\tcustomizable,\n\t\t);\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\tpublic optional<const T extends ImplicitAllowedTypes>(\n\t\tt: T,\n\t\tprops?: FieldProps,\n\t): FieldSchema<FieldKind.Optional, T> {\n\t\treturn new FieldSchema(FieldKind.Optional, t, props);\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\tpublic required<const T extends ImplicitAllowedTypes>(\n\t\tt: T,\n\t\tprops?: FieldProps,\n\t): FieldSchema<FieldKind.Required, T> {\n\t\treturn new FieldSchema(FieldKind.Required, t, props);\n\t}\n\n\t/**\n\t * Make a field of type identifier instead of the default which is required.\n\t */\n\tpublic get identifier(): FieldSchema<FieldKind.Identifier> {\n\t\treturn new FieldSchema(FieldKind.Identifier, this.string);\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\tpublic objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<RestrictiveReadonlyRecord<string, 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 & RestrictiveReadonlyRecord<string, 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 * {@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<readonly (() => TreeNodeSchema)[]>>(t: T) {\n\t\treturn createFieldSchemaUnsafe(FieldKind.Optional, 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\tpublic arrayRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<ImplicitAllowedTypes>,\n\t>(name: Name, allowedTypes: T) {\n\t\tclass RecursiveArray extends 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\t\t\tpublic constructor(\n\t\t\t\tdata:\n\t\t\t\t\t| Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T & ImplicitAllowedTypes>>\n\t\t\t\t\t| FlexTreeNode,\n\t\t\t) {\n\t\t\t\tif (isFlexTreeNode(data)) {\n\t\t\t\t\tsuper(data as any);\n\t\t\t\t} else {\n\t\t\t\t\tsuper(data);\n\t\t\t\t}\n\t\t\t}\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>>,\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\tpublic mapRecursive<Name extends TName, const T extends Unenforced<ImplicitAllowedTypes>>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t) {\n\t\tclass MapSchema extends 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\t\t\tpublic constructor(\n\t\t\t\tdata:\n\t\t\t\t\t| Iterable<\n\t\t\t\t\t\t\t[\n\t\t\t\t\t\t\t\tstring,\n\t\t\t\t\t\t\t\tInsertableTreeNodeFromImplicitAllowedTypes<\n\t\t\t\t\t\t\t\t\tT & ImplicitAllowedTypes\n\t\t\t\t\t\t\t\t>,\n\t\t\t\t\t\t\t]\n\t\t\t\t\t  >\n\t\t\t\t\t| FlexTreeNode,\n\t\t\t) {\n\t\t\t\tif (isFlexTreeNode(data)) {\n\t\t\t\t\tsuper(data as any);\n\t\t\t\t} else {\n\t\t\t\t\tsuper(new Map(data));\n\t\t\t\t}\n\t\t\t}\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>>,\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\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\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 are also needed so that a single type name \"Any\" would not collide with the \"any\" case above.\n\t\tinner = JSON.stringify(names);\n\t}\n\treturn `${collectionName}<${inner}>`;\n}\n"]}