@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/class-tree/schemaFactory.d.ts

@@ -0,0 +1,225 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { RestrictiveReadonlyRecord } from "../util";
+import { FlexTreeNode } from "../feature-libraries";
+import { TreeValue } from "../core";
+import { TreeArrayNode } from "../simple-tree";
+import { AllowedTypes, FieldKind, FieldSchema, ImplicitAllowedTypes, ImplicitFieldSchema, InsertableObjectFromSchemaRecord, InsertableTreeNodeFromImplicitAllowedTypes, InsertableTypedNode, NodeFromSchema, NodeKind, ObjectFromSchemaRecord, TreeMapNode, TreeNodeFromImplicitAllowedTypes, TreeNodeSchema, TreeNodeSchemaClass } from "./schemaTypes";
+/**
+ * Gets the leaf domain schema compatible with a given {@link TreeValue}.
+ */
+export declare function schemaFromValue(value: TreeValue): TreeNodeSchema;
+/**
+ * Builds schema libraries, and the schema within them.
+ *
+ * @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.
+ * @typeParam TName - Type of names used to identify each schema produced in this factory.
+ * 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.
+ *
+ * @sealed @beta
+ */
+export declare class SchemaFactory<TScope extends string = string, TName extends number | string = string> {
+    readonly scope: TScope;
+    private readonly structuralTypes;
+    /**
+     * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
+     * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
+     */
+    constructor(scope: TScope);
+    private scoped;
+    /**
+     * {@link TreeNodeSchema} for holding a JavaScript `string`.
+     *
+     * @remarks
+     * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.
+     *
+     * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.
+     * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.
+     * @privateRemarks
+     * TODO:
+     * We should be much more clear about what happens if you use problematic values.
+     * We should validate and/or normalize them when inserting content.
+     */
+    readonly string: TreeNodeSchema<"com.fluidframework.leaf.string", NodeKind.Leaf, string, string>;
+    /**
+     * {@link TreeNodeSchema} for holding a JavaScript `number`.
+     *
+     * @remarks
+     * 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:
+     * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+     * - `-0` may be converted to `0` in some cases.
+     *
+     * These limitations match the limitations of JSON.
+     * @privateRemarks
+     * TODO:
+     * We should be much more clear about what happens if you use problematic values.
+     * We should validate and/or normalize them when inserting content.
+     */
+    readonly number: TreeNodeSchema<"com.fluidframework.leaf.number", NodeKind.Leaf, number, number>;
+    /**
+     * {@link TreeNodeSchema} for holding a boolean.
+     */
+    readonly boolean: TreeNodeSchema<"com.fluidframework.leaf.boolean", NodeKind.Leaf, boolean, boolean>;
+    /**
+     * {@link TreeNodeSchema} for JavaScript `null`.
+     *
+     * @remarks
+     * 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.
+     * This {@link TreeNodeSchema} node provides the option to include nulls in trees when desired.
+     * Unless directly inter-operating with existing data using null, consider other approaches, like wrapping the value in an optional field, or using a more specifically named empty object node.
+     */
+    readonly null: TreeNodeSchema<"com.fluidframework.leaf.null", NodeKind.Leaf, null, null>;
+    /**
+     * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#IFluidHandle}.
+     */
+    readonly handle: TreeNodeSchema<"com.fluidframework.leaf.handle", NodeKind.Leaf, import("@fluidframework/core-interfaces").IFluidHandle<import("@fluidframework/core-interfaces").FluidObject & import("@fluidframework/core-interfaces").IFluidLoadable>, import("@fluidframework/core-interfaces").IFluidHandle<import("@fluidframework/core-interfaces").FluidObject & import("@fluidframework/core-interfaces").IFluidLoadable>>;
+    /**
+     * Construct a class that provides the common parts all TreeNodeSchemaClass share.
+     * More specific schema extend this class.
+     */
+    private nodeSchema;
+    /**
+     * Define a {@link TreeNodeSchema} for an object node.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     */
+    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, t: T): TreeNodeSchemaClass<`${TScope}.${Name}`, NodeKind.Object, ObjectFromSchemaRecord<T>, InsertableObjectFromSchemaRecord<T>, true>;
+    /**
+     * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNodeBase}.
+     *
+     * @remarks
+     * The {@link TreeNodeSchemaIdentifier} for this Map is defined as a function of the provided types.
+     * It is still scoped to this SchemaBuilder, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.
+     * This does not support recursive types.
+     *
+     * If using these structurally named maps, other types in this schema builder should avoid names of the form `Map<${string}>`.
+     *
+     * @example
+     * The returned schema should be used as a schema directly:
+     * ```typescript
+     * const MyMap = factory.map(factory.number);
+     * type MyMap = NodeFromSchema<typeof MyMap>;
+     * ```
+     * Or inline:
+     * ```typescript
+     * factory.object("Foo", {myMap: factory.map(factory.number)});
+     * ```
+     * @privateRemarks
+     * See note on list.
+     */
+    map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<`${TScope}.Map<${string}>`, NodeKind.Map, TreeMapNode<T>, ReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>, true>;
+    /**
+     * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeBase}.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     *
+     * @example
+     * ```typescript
+     * class NamedMap extends factory.map("name", factory.number) {}
+     * ```
+     */
+    map<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<`${TScope}.${Name}`, NodeKind.Map, TreeMapNode<T>, ReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>, 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}.
+     */
+    namedMap<Name extends TName | string, const T extends ImplicitAllowedTypes, const ImplicitlyConstructable extends boolean>(name: Name, allowedTypes: T, customizable: boolean, implicitlyConstructable: ImplicitlyConstructable): TreeNodeSchemaClass<`${TScope}.${Name}`, NodeKind.Map, TreeMapNode<T>, ReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>, ImplicitlyConstructable>;
+    /**
+     * Define a structurally typed {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
+     *
+     * @remarks
+     * The identifier for this List is defined as a function of the provided types.
+     * It is still scoped to this SchemaFactory, but multiple calls with the same arguments will return the same schema object, providing somewhat structural typing.
+     * This does not support recursive types.
+     *
+     * If using these structurally named lists, other types in this schema builder should avoid names of the form `List<${string}>`.
+     *
+     * @example
+     * The returned schema should be used as a schema directly:
+     * ```typescript
+     * const MyList = factory.list(factory.number);
+     * type MyList = NodeFromSchema<typeof MyList>;
+     * ```
+     * Or inline:
+     * ```typescript
+     * factory.object("Foo", {myList: factory.list(factory.number)});
+     * ```
+     * @privateRemarks
+     * 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.
+     * There are cases where not having this full type provided will be less than ideal since TypeScript's structural types.
+     * For example attempts to narrow unions of structural lists by name won't work.
+     * Planned future changes to move to a class based schema system as well as factor function based node construction should mostly avoid these issues,
+     * though there may still be some problematic cases even after that work is done.
+     *
+     * The return value is a class, but its the type is intentionally not specific enough to indicate it is a class.
+     * 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)
+     * when working with structural typing.
+     */
+    array<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(allowedTypes: T): TreeNodeSchema<`${TScope}.List<${string}>`, NodeKind.Array, TreeArrayNode<T>, Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>, true>;
+    /**
+     * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeArrayNode:interface)}.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     *
+     * @example
+     * ```typescript
+     * class NamedList extends factory.list("name", factory.number) {}
+     * ```
+     */
+    array<const Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): TreeNodeSchemaClass<`${TScope}.${Name}`, NodeKind.Array, TreeArrayNode<T>, Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>, true>;
+    /**
+     * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     *
+     * @remarks
+     * This is not intended to be used directly, use the overload of `list` which takes a name instead.
+     * This is only public to work around a compiler limitation.
+     *
+     * @privateRemarks
+     * TODO: this should be made private or protected.
+     * Doing so breaks due to:
+     * `src/class-tree/schemaFactoryRecursive.ts:42:9 - error TS2310: Type 'List' recursively references itself as a base type.`
+     * Once recursive APIs are better sorted out and integrated into this class, switch this back to private.
+     */
+    namedArray<Name extends TName | string, const T extends ImplicitAllowedTypes, const ImplicitlyConstructable extends boolean>(name: Name, allowedTypes: T, customizable: boolean, implicitlyConstructable: ImplicitlyConstructable): TreeNodeSchemaClass<`${TScope}.${Name}`, NodeKind.Array, TreeArrayNode<T>, Iterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>, ImplicitlyConstructable>;
+    /**
+     * Make a field optional instead of the default which is required.
+     */
+    optional<const T extends ImplicitAllowedTypes>(t: T): FieldSchema<FieldKind.Optional, T>;
+    /**
+     * Function which can be used for its compile time side-effects to tweak the evaluation order of recursive types to make them compile.
+     * @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],
+     * }) {}
+     * ```
+     */
+    fixRecursiveReference<T extends AllowedTypes>(...types: T): void;
+}
+export declare function createTree<T extends TreeNodeSchema>(schema: T, data: InsertableTypedNode<T> | FlexTreeNode): NodeFromSchema<T>;
+export declare function structuralName<const T extends string>(collectionName: T, allowedTypes: TreeNodeSchema | readonly TreeNodeSchema[]): `${T}<${string}>`;
+//# sourceMappingURL=schemaFactory.d.ts.map

package/dist/class-tree/schemaFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaFactory.d.ts","sourceRoot":"","sources":["../../src/class-tree/schemaFactory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,yBAAyB,EAAgC,MAAM,SAAS,CAAC;AAClF,OAAO,EACN,YAAY,EASZ,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAA4B,SAAS,EAAE,MAAM,SAAS,CAAC;AAU9D,OAAO,EAAE,aAAa,EAAY,MAAM,gBAAgB,CAAC;AAEzD,OAAO,EACN,YAAY,EACZ,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,gCAAgC,EAChC,0CAA0C,EAC1C,mBAAmB,EACnB,cAAc,EACd,QAAQ,EACR,sBAAsB,EACtB,WAAW,EACX,gCAAgC,EAChC,cAAc,EACd,mBAAmB,EAEnB,MAAM,eAAe,CAAC;AA6CvB;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CAkBhE;AAQD;;;;;;;;GAQG;AACH,qBAAa,aAAa,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM,EAAE,KAAK,SAAS,MAAM,GAAG,MAAM,GAAG,MAAM;aAO7D,KAAK,EAAE,MAAM;IANhD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAE1E;;;OAGG;gBACgC,KAAK,EAAE,MAAM;IAEhD,OAAO,CAAC,MAAM;IAId;;;;;;;;;;;;OAYG;IACH,SAAgB,MAAM,kFAAgB;IAEtC;;;;;;;;;;;;;OAaG;IACH,SAAgB,MAAM,kFAAgB;IAEtC;;OAEG;IACH,SAAgB,OAAO,qFAAiB;IAExC;;;;;;;OAOG;IACH,SAAgB,IAAI,4EAAc;IAElC;;OAEG;IACH,SAAgB,MAAM,sZAAgB;IAEtC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAiDlB;;;;OAIG;IACI,MAAM,CACZ,KAAK,CAAC,IAAI,SAAS,KAAK,EACxB,KAAK,CAAC,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAEtE,IAAI,EAAE,IAAI,EACV,CAAC,EAAE,CAAC,GACF,mBAAmB,CACrB,GAAG,MAAM,IAAI,IAAI,EAAE,EACnB,QAAQ,CAAC,MAAM,EACf,sBAAsB,CAAC,CAAC,CAAC,EACzB,gCAAgC,CAAC,CAAC,CAAC,EACnC,IAAI,CACJ;IA4BD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,GAAG,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,SAAS,cAAc,EAAE,EACpE,YAAY,EAAE,CAAC,GACb,cAAc,CAChB,GAAG,MAAM,QAAQ,MAAM,GAAG,EAC1B,QAAQ,CAAC,GAAG,EACZ,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAC,CAAC,CAAC,EACxD,IAAI,CACJ;IAED;;;;;;;;;OASG;IACI,GAAG,CAAC,IAAI,SAAS,KAAK,EAAE,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAClE,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,CAAC,GACb,mBAAmB,CACrB,GAAG,MAAM,IAAI,IAAI,EAAE,EACnB,QAAQ,CAAC,GAAG,EACZ,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CAAC,MAAM,EAAE,0CAA0C,CAAC,CAAC,CAAC,CAAC,EAClE,IAAI,CACJ;IAoCD;;;;;;OAMG;IACI,QAAQ,CACd,IAAI,SAAS,KAAK,GAAG,MAAM,EAC3B,KAAK,CAAC,CAAC,SAAS,oBAAoB,EACpC,KAAK,CAAC,uBAAuB,SAAS,OAAO,EAE7C,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,CAAC,EACf,YAAY,EAAE,OAAO,EACrB,uBAAuB,EAAE,uBAAuB,GAC9C,mBAAmB,CACrB,GAAG,MAAM,IAAI,IAAI,EAAE,EACnB,QAAQ,CAAC,GAAG,EACZ,WAAW,CAAC,CAAC,CAAC,EACd,WAAW,CAAC,MAAM,EAAE,0CAA0C,CAAC,CAAC,CAAC,CAAC,EAClE,uBAAuB,CACvB;IAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACI,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,SAAS,cAAc,EAAE,EACtE,YAAY,EAAE,CAAC,GACb,cAAc,CAChB,GAAG,MAAM,SAAS,MAAM,GAAG,EAC3B,QAAQ,CAAC,KAAK,EACd,aAAa,CAAC,CAAC,CAAC,EAChB,QAAQ,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAC,EACvD,IAAI,CACJ;IAED;;;;;;;;;OASG;IACI,KAAK,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,KAAK,CAAC,CAAC,SAAS,oBAAoB,EAC1E,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,CAAC,GACb,mBAAmB,CACrB,GAAG,MAAM,IAAI,IAAI,EAAE,EACnB,QAAQ,CAAC,KAAK,EACd,aAAa,CAAC,CAAC,CAAC,EAChB,QAAQ,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAC,EACvD,IAAI,CACJ;IA4BD;;;;;;;;;;;;;;OAcG;IACI,UAAU,CAChB,IAAI,SAAS,KAAK,GAAG,MAAM,EAC3B,KAAK,CAAC,CAAC,SAAS,oBAAoB,EACpC,KAAK,CAAC,uBAAuB,SAAS,OAAO,EAE7C,IAAI,EAAE,IAAI,EACV,YAAY,EAAE,CAAC,EACf,YAAY,EAAE,OAAO,EACrB,uBAAuB,EAAE,uBAAuB,GAC9C,mBAAmB,CACrB,GAAG,MAAM,IAAI,IAAI,EAAE,EACnB,QAAQ,CAAC,KAAK,EACd,aAAa,CAAC,CAAC,CAAC,EAChB,QAAQ,CAAC,0CAA0C,CAAC,CAAC,CAAC,CAAC,EACvD,uBAAuB,CACvB;IA6CD;;OAEG;IACI,QAAQ,CAAC,KAAK,CAAC,CAAC,SAAS,oBAAoB,EACnD,CAAC,EAAE,CAAC,GACF,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,qBAAqB,CAAC,CAAC,SAAS,YAAY,EAAE,GAAG,KAAK,EAAE,CAAC,GAAG,IAAI;CACvE;AAGD,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EAClD,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,YAAY,GACzC,cAAc,CAAC,CAAC,CAAC,CAYnB;AAED,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EACpD,cAAc,EAAE,CAAC,EACjB,YAAY,EAAE,cAAc,GAAG,SAAS,cAAc,EAAE,GACtD,GAAG,CAAC,IAAI,MAAM,GAAG,CAkBnB"}

package/dist/class-tree/schemaFactory.js

@@ -0,0 +1,330 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * 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 util_1 = require("../util");
+const feature_libraries_1 = require("../feature-libraries");
+const domains_1 = require("../domains");
+const proxies_1 = require("../simple-tree/proxies");
+const simple_tree_1 = require("../simple-tree");
+const toFlexSchema_1 = require("./toFlexSchema");
+const schemaTypes_1 = require("./schemaTypes");
+/**
+ * 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_1.NodeKind.Leaf;
+        this.implicitlyConstructable = true;
+        (0, toFlexSchema_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(domains_1.leaf.string);
+const numberSchema = makeLeaf(domains_1.leaf.number);
+const booleanSchema = makeLeaf(domains_1.leaf.boolean);
+const nullSchema = makeLeaf(domains_1.leaf.null);
+const handleSchema = makeLeaf(domains_1.leaf.handle);
+/**
+ * Gets the leaf domain schema compatible with a given {@link TreeValue}.
+ */
+function schemaFromValue(value) {
+    switch (typeof value) {
+        case "boolean":
+            return booleanSchema;
+        case "number":
+            return numberSchema;
+        case "string":
+            return stringSchema;
+        case "object": {
+            if (value === null) {
+                return nullSchema;
+            }
+            (0, core_utils_1.assert)((0, feature_libraries_1.isFluidHandle)(value), "invalid TreeValue");
+            return handleSchema;
+        }
+        default:
+            (0, core_utils_1.unreachableCase)(value);
+    }
+}
+exports.schemaFromValue = schemaFromValue;
+/**
+ * Builds schema libraries, and the schema within them.
+ *
+ * @typeParam TScope - Scope added as a prefix to the name of every schema produced by this factory.
+ * @typeParam TName - Type of names used to identify each schema produced in this factory.
+ * 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.
+ *
+ * @sealed @beta
+ */
+class SchemaFactory {
+    /**
+     * @param scope - Prefix appended to the identifiers of all {@link TreeNodeSchema} produced by this builder.
+     * Use of [Reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) or a UUIDv4 is recommended to avoid collisions.
+     */
+    constructor(scope) {
+        this.scope = scope;
+        this.structuralTypes = new Map();
+        /**
+         * {@link TreeNodeSchema} for holding a JavaScript `string`.
+         *
+         * @remarks
+         * Strings containing unpaired UTF-16 surrogate pair code units may not be handled correctly.
+         *
+         * These limitations come from the use of UTF-8 encoding of the strings, which requires them to be valid unicode.
+         * JavaScript does not make this requirement for its strings so not all possible JavaScript strings are supported.
+         * @privateRemarks
+         * TODO:
+         * We should be much more clear about what happens if you use problematic values.
+         * We should validate and/or normalize them when inserting content.
+         */
+        this.string = stringSchema;
+        /**
+         * {@link TreeNodeSchema} for holding a JavaScript `number`.
+         *
+         * @remarks
+         * 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:
+         * - `NaN`, and the infinities are converted to `null` (and may therefore only be used where `null` is allowed by the schema).
+         * - `-0` may be converted to `0` in some cases.
+         *
+         * These limitations match the limitations of JSON.
+         * @privateRemarks
+         * TODO:
+         * We should be much more clear about what happens if you use problematic values.
+         * We should validate and/or normalize them when inserting content.
+         */
+        this.number = numberSchema;
+        /**
+         * {@link TreeNodeSchema} for holding a boolean.
+         */
+        this.boolean = booleanSchema;
+        /**
+         * {@link TreeNodeSchema} for JavaScript `null`.
+         *
+         * @remarks
+         * 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.
+         * 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;
+        /**
+         * {@link TreeNodeSchema} for holding an {@link @fluidframework/core-interfaces#IFluidHandle}.
+         */
+        this.handle = handleSchema;
+    }
+    scoped(name) {
+        return `${this.scope}.${name}`;
+    }
+    /**
+     * Construct a class that provides the common parts all TreeNodeSchemaClass share.
+     * More specific schema extend this class.
+     */
+    nodeSchema(name, kind, t, implicitlyConstructable) {
+        const identifier = this.scoped(name);
+        class schema extends simple_tree_1.TreeNode {
+            /**
+             * This constructor only does validation of the input, and should be passed the argument from the derived type unchanged.
+             * It is up to the derived type to actually do something with this value.
+             */
+            constructor(input) {
+                super();
+                // Currently this just does validation. All other logic is in the subclass.
+                if ((0, feature_libraries_1.isFlexTreeNode)(input)) {
+                    (0, core_utils_1.assert)((0, proxies_1.getClassSchema)(input.schema) === this.constructor, 0x83b /* building node with wrong schema */);
+                }
+                // TODO: make this a better user facing error, and explain how to copy explicitly.
+                (0, core_utils_1.assert)(!(input instanceof simple_tree_1.TreeNode), 0x83c /* Existing nodes cannot be used as new content to insert. They must either be moved or explicitly copied */);
+            }
+        }
+        schema.identifier = identifier;
+        schema.kind = kind;
+        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, feature_libraries_1.markEager)(schema);
+        return schema;
+    }
+    /**
+     * Define a {@link TreeNodeSchema} for an object node.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     */
+    object(name, t) {
+        const allowAdditionalProperties = true;
+        class schema extends this.nodeSchema(name, schemaTypes_1.NodeKind.Object, t, true) {
+            constructor(input) {
+                super(input);
+                if ((0, feature_libraries_1.isFlexTreeNode)(input)) {
+                    return (0, proxies_1.createNodeProxy)(input, allowAdditionalProperties, this);
+                }
+                else {
+                    const flexSchema = (0, toFlexSchema_1.getFlexSchema)(this.constructor);
+                    return (0, proxies_1.createRawNodeProxy)(flexSchema, input, allowAdditionalProperties, this);
+                }
+            }
+        }
+        return schema;
+    }
+    map(nameOrAllowedTypes, allowedTypes) {
+        if (allowedTypes === undefined) {
+            const types = nameOrAllowedTypes;
+            const fullName = structuralName("Map", types);
+            return (0, util_1.getOrCreate)(this.structuralTypes, fullName, () => this.namedMap(fullName, nameOrAllowedTypes, false, 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}.
+     */
+    namedMap(name, allowedTypes, customizable, implicitlyConstructable) {
+        class schema extends this.nodeSchema(name, schemaTypes_1.NodeKind.Map, allowedTypes, implicitlyConstructable) {
+            constructor(input) {
+                super(input);
+                if ((0, feature_libraries_1.isFlexTreeNode)(input)) {
+                    return (0, proxies_1.createNodeProxy)(input, customizable, customizable ? this : undefined);
+                }
+                else {
+                    const flexSchema = (0, toFlexSchema_1.getFlexSchema)(this.constructor);
+                    return (0, proxies_1.createRawNodeProxy)(flexSchema, input, customizable, customizable ? this : undefined);
+                }
+            }
+        }
+        // Setup map functionality
+        Object.defineProperties(schema.prototype, proxies_1.mapStaticDispatchMap);
+        return schema;
+    }
+    array(nameOrAllowedTypes, allowedTypes) {
+        if (allowedTypes === undefined) {
+            const types = nameOrAllowedTypes;
+            const fullName = structuralName("List", types);
+            return (0, util_1.getOrCreate)(this.structuralTypes, fullName, () => this.namedArray(fullName, nameOrAllowedTypes, false, true));
+        }
+        return this.namedArray(nameOrAllowedTypes, allowedTypes, true, true);
+    }
+    /**
+     * Define a {@link TreeNodeSchema} for a {@link (TreeArrayNode:interface)}.
+     *
+     * @param name - Unique identifier for this schema within this factory's scope.
+     *
+     * @remarks
+     * This is not intended to be used directly, use the overload of `list` which takes a name instead.
+     * This is only public to work around a compiler limitation.
+     *
+     * @privateRemarks
+     * TODO: this should be made private or protected.
+     * Doing so breaks due to:
+     * `src/class-tree/schemaFactoryRecursive.ts:42:9 - error TS2310: Type 'List' recursively references itself as a base type.`
+     * Once recursive APIs are better sorted out and integrated into this class, switch this back to private.
+     */
+    namedArray(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_1.NodeKind.Array, allowedTypes, implicitlyConstructable) {
+            get length() {
+                return (0, proxies_1.getSequenceField)(this).length;
+            }
+            constructor(input) {
+                super(input);
+                if ((0, feature_libraries_1.isFlexTreeNode)(input)) {
+                    return (0, proxies_1.createNodeProxy)(input, customizable, customizable ? this : undefined);
+                }
+                else {
+                    const flexSchema = (0, toFlexSchema_1.getFlexSchema)(this.constructor);
+                    return (0, proxies_1.createRawNodeProxy)(flexSchema, [...input], customizable, customizable ? this : undefined);
+                }
+            }
+        }
+        // Setup list functionality
+        Object.defineProperties(schema.prototype, proxies_1.listPrototypeProperties);
+        return schema;
+    }
+    /**
+     * Make a field optional instead of the default which is required.
+     */
+    optional(t) {
+        return new schemaTypes_1.FieldSchema(schemaTypes_1.FieldKind.Optional, t);
+    }
+    /**
+     * Function which can be used for its compile time side-effects to tweak the evaluation order of recursive types to make them compile.
+     * @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],
+     * }) {}
+     * ```
+     */
+    fixRecursiveReference(...types) { }
+}
+exports.SchemaFactory = SchemaFactory;
+// TODO: unify this with logic in getOrCreateNodeProxy
+function createTree(schema, data) {
+    if (typeof schema === "function") {
+        return new schema(data);
+    }
+    return schema.create(data);
+}
+exports.createTree = createTree;
+function structuralName(collectionName, allowedTypes) {
+    let inner;
+    if (!(0, util_1.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, feature_libraries_1.isLazy)(t), 0x83d /* invalid type provided */);
+            return t.identifier;
+        });
+        // Ensure name is order independent
+        names.sort();
+        // Ensure name can't have collisions by quoting and escaping any quotes in the names of types.
+        // Using JSON is a simple way to accomplish this.
+        // The outer `[]` around the result are also needed so that a single type name "Any" would not collide with the "any" case above.
+        inner = JSON.stringify(names);
+    }
+    return `${collectionName}<${inner}>`;
+}
+exports.structuralName = structuralName;
+//# sourceMappingURL=schemaFactory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schemaFactory.js","sourceRoot":"","sources":["../../src/class-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 { RestrictiveReadonlyRecord, getOrCreate, isReadonlyArray } from \"../util\";\nimport {\n\tFlexTreeNode,\n\tLeafNodeSchema as FlexLeafNodeSchema,\n\tisFlexTreeNode,\n\tObjectNodeSchema,\n\tisLazy,\n\tmarkEager,\n\tMapNodeSchema,\n\tFieldNodeSchema,\n\tisFluidHandle,\n} from \"../feature-libraries\";\nimport { leaf } from \"../domains\";\nimport { TreeNodeSchemaIdentifier, TreeValue } from \"../core\";\nimport {\n\tcreateNodeProxy,\n\tcreateRawNodeProxy,\n\tgetClassSchema,\n\tgetSequenceField,\n\tlistPrototypeProperties,\n\tmapStaticDispatchMap,\n\t// eslint-disable-next-line import/no-internal-modules\n} from \"../simple-tree/proxies\";\nimport { TreeArrayNode, TreeNode } from \"../simple-tree\";\nimport { getFlexSchema, setFlexSchemaFromClassSchema } from \"./toFlexSchema\";\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} from \"./schemaTypes\";\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), \"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 * Builds schema libraries, and the schema within them.\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 * @sealed @beta\n */\nexport class SchemaFactory<TScope extends string = string, TName extends number | string = string> {\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 */\n\tpublic constructor(public readonly scope: TScope) {}\n\n\tprivate scoped<Name extends TName | string>(name: Name): `${TScope}.${Name}` {\n\t\treturn `${this.scope}.${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}.\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\t`${TScope}.${Name}`,\n\t\tTKind,\n\t\tTreeNode,\n\t\tFlexTreeNode | unknown,\n\t\tTImplicitlyConstructable\n\t> {\n\t\tconst identifier = this.scoped(name);\n\t\tclass schema extends TreeNode {\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\t\t\t\t// TODO: make this a better user facing error, and explain how to copy explicitly.\n\t\t\t\tassert(\n\t\t\t\t\t!(input instanceof TreeNode),\n\t\t\t\t\t0x83c /* Existing nodes cannot be used as new content to insert. They must either be moved or explicitly copied */,\n\t\t\t\t);\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>(\n\t\tname: Name,\n\t\tt: T,\n\t): TreeNodeSchemaClass<\n\t\t`${TScope}.${Name}`,\n\t\tNodeKind.Object,\n\t\tObjectFromSchemaRecord<T>,\n\t\tInsertableObjectFromSchemaRecord<T>,\n\t\ttrue\n\t> {\n\t\tconst allowAdditionalProperties = true;\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\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(input, allowAdditionalProperties, this) 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 ObjectNodeSchema,\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tallowAdditionalProperties,\n\t\t\t\t\t\tthis,\n\t\t\t\t\t) as schema;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn schema as TreeNodeSchemaClass<\n\t\t\t`${TScope}.${Name}`,\n\t\t\tNodeKind.Object,\n\t\t\tObjectFromSchemaRecord<T>,\n\t\t\tInsertableObjectFromSchemaRecord<T>,\n\t\t\ttrue\n\t\t>;\n\t}\n\n\t/**\n\t * Define a structurally typed {@link TreeNodeSchema} for a {@link TreeMapNodeBase}.\n\t *\n\t * @remarks\n\t * The {@link TreeNodeSchemaIdentifier} 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 list.\n\t */\n\tpublic map<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchema<\n\t\t`${TScope}.Map<${string}>`,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tReadonlyMap<string, TreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\n\t>;\n\n\t/**\n\t * Define a {@link TreeNodeSchema} for a {@link TreeMapNodeBase}.\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\t`${TScope}.${Name}`,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\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\t`${TScope}.${string}`,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\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\t`${TScope}.${string}`,\n\t\t\t\tNodeKind.Map,\n\t\t\t\tTreeMapNode<T>,\n\t\t\t\tReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t\ttrue\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\t * @remarks See remarks on {@link SchemaFactory.namedArray}.\n\t */\n\tpublic 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\t`${TScope}.${Name}`,\n\t\tNodeKind.Map,\n\t\tTreeMapNode<T>,\n\t\tReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable\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: ReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\t) {\n\t\t\t\tsuper(input);\n\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tcustomizable ? this : undefined,\n\t\t\t\t\t) 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 MapNodeSchema,\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tcustomizable ? this : undefined,\n\t\t\t\t\t) 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\t`${TScope}.${Name}`,\n\t\t\tNodeKind.Map,\n\t\t\tTreeMapNode<T>,\n\t\t\tReadonlyMap<string, InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\tImplicitlyConstructable\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 List 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 lists, other types in this schema builder should avoid names of the form `List<${string}>`.\n\t *\n\t * @example\n\t * The returned schema should be used as a schema directly:\n\t * ```typescript\n\t * const MyList = factory.list(factory.number);\n\t * type MyList = NodeFromSchema<typeof MyList>;\n\t * ```\n\t * Or inline:\n\t * ```typescript\n\t * factory.object(\"Foo\", {myList: factory.list(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 lists 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\tpublic array<const T extends TreeNodeSchema | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): TreeNodeSchema<\n\t\t`${TScope}.List<${string}>`,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\n\t>;\n\n\t/**\n\t * Define (and add to this library) a {@link FieldNodeSchema} 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 NamedList extends factory.list(\"name\", factory.number) {}\n\t * ```\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\t`${TScope}.${Name}`,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\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\t`${TScope}.${string}`,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\ttrue\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as (T & TreeNodeSchema) | readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"List\", 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\t`${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>;\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 `list` 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 'List' 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<\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\t`${TScope}.${Name}`,\n\t\tNodeKind.Array,\n\t\tTreeArrayNode<T>,\n\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\tImplicitlyConstructable\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\t\t\t\tif (isFlexTreeNode(input)) {\n\t\t\t\t\treturn createNodeProxy(\n\t\t\t\t\t\tinput,\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tcustomizable ? this : undefined,\n\t\t\t\t\t) 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 FieldNodeSchema,\n\t\t\t\t\t\t[...input],\n\t\t\t\t\t\tcustomizable,\n\t\t\t\t\t\tcustomizable ? this : undefined,\n\t\t\t\t\t) as schema;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Setup list functionality\n\t\tObject.defineProperties(schema.prototype, listPrototypeProperties);\n\n\t\treturn schema as unknown as TreeNodeSchemaClass<\n\t\t\t`${TScope}.${Name}`,\n\t\t\tNodeKind.Array,\n\t\t\tTreeArrayNode<T>,\n\t\t\tIterable<InsertableTreeNodeFromImplicitAllowedTypes<T>>,\n\t\t\tImplicitlyConstructable\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 */\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"]}