@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/domains/schemaBuilder.d.ts

@@ -0,0 +1,190 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Any, FieldKinds, TreeFieldSchema, ImplicitAllowedTypes, NormalizeAllowedTypes, NormalizeField, SchemaBuilderOptions, TreeNodeSchema, MapFieldSchema, SchemaBuilderBase, ImplicitFieldSchema, Required, ObjectNodeSchema, Unenforced, AllowedTypes, FieldNodeSchema, MapNodeSchema } from "../feature-libraries";
+import { FactoryTreeSchema } from "../simple-tree";
+import { RestrictiveReadonlyRecord } from "../util";
+/**
+ * A {@link ObjectNodeSchema} that satisfies the {@link TreeObjectFactory} and therefore can create {@link TreeObjectNode}s.
+ * @privateRemarks
+ * This type exists because TypeScript is not able to correlate the two places where it is used if the body of this type is inlined.
+ */
+export type FactoryObjectNodeSchema<TScope extends string, Name extends number | string, T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>> = FactoryTreeSchema<ObjectNodeSchema<`${TScope}.${Name}`, {
+    [key in keyof T]: NormalizeField<T[key], Required>;
+}>>;
+/**
+ * Same as `FactoryObjectNodeSchema` but with less type safety and works for recursive objects.
+ * Reduced type safety is a side effect of a workaround for a TypeScript limitation.
+ *
+ * See {@link Unenforced} for details.
+ *
+ * TODO: Make this work with ImplicitFieldSchema.
+ */
+export type FactoryObjectNodeSchemaRecursive<TScope extends string, Name extends number | string, T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>> = FactoryTreeSchema<ObjectNodeSchema<`${TScope}.${Name}`, T>>;
+/**
+ * Builds schema libraries, and the schema within them.
+ *
+ * @remarks
+ * Fields, when inferred from {@link ImplicitFieldSchema}, default to the `Required` {@link FieldKind} (except for in Maps, which default to `Optional`).
+ * Implicitly includes `leaf` schema library by default.
+ *
+ * This type has some built in defaults which impact compatibility.
+ * This includes which {@link FieldKind}s it uses.
+ * To ensure that these defaults can be updated without compatibility issues,
+ * this class is versioned: the number in its name indicates its compatibility,
+ * and if its defaults are changed to ones that would not be compatible with a version of the application using the previous versions,
+ * this number will be updated to make it impossible for an app to implicitly do a compatibility breaking change by updating this package.
+ * Major package version updates are allowed to break API compatibility, but must not break content compatibility unless a corresponding code change is made in the app to opt in.
+ *
+ * @privateRemarks
+ * TODO: Maybe rename to DefaultSchemaBuilder1 because of the versioning implications above.
+ * Same applies to SchemaBuilder.
+ * TODO: figure out a way to link `leaf` above without breaking API Extractor.
+ * @sealed
+ * @deprecated Users of this class should either use {@link SchemaBuilderBase} and explicitly work with {@link TreeFieldSchema}, or use SchemaFactory and work at its higher level of abstraction.
+ */
+export declare class SchemaBuilder<TScope extends string = string, TName extends string | number = string> extends SchemaBuilderBase<TScope, typeof FieldKinds.required, TName> {
+    private readonly structuralTypes;
+    constructor(options: SchemaBuilderOptions<TScope>);
+    object<const Name extends TName, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>(name: Name, t: T): FactoryObjectNodeSchema<TScope, Name, T>;
+    objectRecursive<const Name extends TName, const T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>>(name: Name, t: T): FactoryObjectNodeSchemaRecursive<TScope, Name, T>;
+    /**
+     * Define (and add to this library if not already present) a structurally typed {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.
+     *
+     * @remarks
+     * The {@link TreeNodeSchemaIdentifier} for this List 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 lists, other types in this schema builder should avoid names of the form `List<${string}>`.
+     *
+     * @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.
+     */
+    list<const T extends TreeNodeSchema | Any | readonly TreeNodeSchema[]>(allowedTypes: T): FieldNodeSchema<`${TScope}.List<${string}>`, TreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>>;
+    /**
+     * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.
+     *
+     * The name must be unique among all TreeNodeSchema in the the document schema.
+     */
+    list<Name extends TName, const T extends ImplicitAllowedTypes>(name: Name, allowedTypes: T): FieldNodeSchema<`${TScope}.${Name}`, TreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>>;
+    /**
+     * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.
+     *
+     * The name must be unique among all TreeNodeSchema in the the document schema.
+     *
+     * @privateRemarks
+     * TODO: If A custom "List" API is added as a subtype of {@link FieldNode}, this would opt into that.
+     */
+    private namedList;
+    /**
+     * Define (and add to this library if not already present) a structurally typed {@link MapNodeSchema} for a {@link TreeMapNode}.
+     *
+     * @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}>`.
+     *
+     * @privateRemarks
+     * See note on list.
+     */
+    map<const T extends TreeNodeSchema | Any | readonly TreeNodeSchema[]>(allowedTypes: T): MapNodeSchema<`${TScope}.Map<${string}>`, NormalizeField<T, typeof FieldKinds.optional>>;
+    /**
+     * Define (and add to this library) a {@link MapNodeSchema} for a {@link TreeMapNode}.
+     */
+    map<Name extends TName, const T extends MapFieldSchema | ImplicitAllowedTypes>(name: Name, fieldSchema: T): MapNodeSchema<`${TScope}.${Name}`, NormalizeField<T, typeof FieldKinds.optional>>;
+    /**
+     * Define a schema for an {@link FieldKinds.optional|optional field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.
+     *
+     * This method is also available as an instance method on {@link SchemaBuilder}.
+     */
+    static optional: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<import("../feature-libraries").Optional, NormalizeAllowedTypes<T>>;
+    /**
+     * Define a schema for an {@link FieldKinds.optional|optional field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.
+     *
+     * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+     * therefore this method is the same as the static version.
+     */
+    readonly optional: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<import("../feature-libraries").Optional, NormalizeAllowedTypes<T>>;
+    /**
+     * Define a schema for a {@link FieldKinds.required|required field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.
+     *
+     * This method is also available as an instance method on {@link SchemaBuilder}.
+     */
+    static required: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<Required, NormalizeAllowedTypes<T>>;
+    /**
+     * Define a schema for a {@link FieldKinds.required|required field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.
+     * Note that `FieldKinds.required` is the current default field kind, so APIs accepting {@link ImplicitFieldSchema}
+     * can be passed the `allowedTypes` and will implicitly wrap it up in a {@link FieldKinds.required|required field}.
+     *
+     * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+     * therefore this method is the same as the static version.
+     */
+    readonly required: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<Required, NormalizeAllowedTypes<T>>;
+    /**
+     * Define a schema for a {@link FieldKinds.sequence|sequence field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.
+     *
+     * This method is also available as an instance method on {@link SchemaBuilder}
+     */
+    static sequence: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<import("../feature-libraries").Sequence, NormalizeAllowedTypes<T>>;
+    /**
+     * Define a schema for a {@link FieldKinds.sequence|sequence field}.
+     * @remarks
+     * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.
+     *
+     * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+     * therefore this method is the same as the static version.
+     */
+    readonly sequence: <const T extends ImplicitAllowedTypes>(allowedTypes: T) => TreeFieldSchema<import("../feature-libraries").Sequence, NormalizeAllowedTypes<T>>;
+    /**
+     * {@link leaf.number}
+     */
+    readonly number: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", import("..").ValueSchema.Number>;
+    /**
+     * {@link leaf.boolean}
+     */
+    readonly boolean: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.boolean", import("..").ValueSchema.Boolean>;
+    /**
+     * {@link leaf.string}
+     */
+    readonly string: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.string", import("..").ValueSchema.String>;
+    /**
+     * {@link leaf.handle}
+     */
+    readonly handle: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.handle", import("..").ValueSchema.FluidHandle>;
+    /**
+     * {@link leaf.null}
+     */
+    readonly null: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.null", import("..").ValueSchema.Null>;
+    /**
+     * 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 (or the "recursive" SchemaBuilder methods tends to break VSCode's IntelliSense every time anything related to that code (even comments) is edited.
+     * The command `TypeScript: Restart TS Server` should fix it.
+     * Sometimes this does not work: the exact cause has not been confirmed but if you have the file open multiple times (for example in both sides of a window split into two columns): closing the extra copy may help.
+     * Focusing the file with the errors before running `TypeScript: Restart TS Server` can also 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`.
+     */
+    fixRecursiveReference<T extends AllowedTypes>(...types: T): void;
+}
+export declare function structuralName<const T extends string>(collectionName: T, allowedTypes: TreeNodeSchema | Any | readonly TreeNodeSchema[]): `${T}<${string}>`;
+//# sourceMappingURL=schemaBuilder.d.ts.map

package/dist/domains/schemaBuilder.d.ts.map

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

package/dist/domains/schemaBuilder.js

@@ -0,0 +1,204 @@
+"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.SchemaBuilder = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const feature_libraries_1 = require("../feature-libraries");
+const simple_tree_1 = require("../simple-tree");
+const util_1 = require("../util");
+const leafDomain_1 = require("./leafDomain");
+/**
+ * Builds schema libraries, and the schema within them.
+ *
+ * @remarks
+ * Fields, when inferred from {@link ImplicitFieldSchema}, default to the `Required` {@link FieldKind} (except for in Maps, which default to `Optional`).
+ * Implicitly includes `leaf` schema library by default.
+ *
+ * This type has some built in defaults which impact compatibility.
+ * This includes which {@link FieldKind}s it uses.
+ * To ensure that these defaults can be updated without compatibility issues,
+ * this class is versioned: the number in its name indicates its compatibility,
+ * and if its defaults are changed to ones that would not be compatible with a version of the application using the previous versions,
+ * this number will be updated to make it impossible for an app to implicitly do a compatibility breaking change by updating this package.
+ * Major package version updates are allowed to break API compatibility, but must not break content compatibility unless a corresponding code change is made in the app to opt in.
+ *
+ * @privateRemarks
+ * TODO: Maybe rename to DefaultSchemaBuilder1 because of the versioning implications above.
+ * Same applies to SchemaBuilder.
+ * TODO: figure out a way to link `leaf` above without breaking API Extractor.
+ * @sealed
+ * @deprecated Users of this class should either use {@link SchemaBuilderBase} and explicitly work with {@link TreeFieldSchema}, or use SchemaFactory and work at its higher level of abstraction.
+ */
+class SchemaBuilder extends feature_libraries_1.SchemaBuilderBase {
+    constructor(options) {
+        super(feature_libraries_1.FieldKinds.required, {
+            ...options,
+            libraries: [...(options.libraries ?? []), leafDomain_1.leaf.library],
+        });
+        this.structuralTypes = new Map();
+        /**
+         * Define a schema for an {@link FieldKinds.optional|optional field}.
+         * @remarks
+         * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.
+         *
+         * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+         * therefore this method is the same as the static version.
+         */
+        this.optional = SchemaBuilder.optional;
+        /**
+         * Define a schema for a {@link FieldKinds.required|required field}.
+         * @remarks
+         * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.
+         * Note that `FieldKinds.required` is the current default field kind, so APIs accepting {@link ImplicitFieldSchema}
+         * can be passed the `allowedTypes` and will implicitly wrap it up in a {@link FieldKinds.required|required field}.
+         *
+         * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+         * therefore this method is the same as the static version.
+         */
+        this.required = SchemaBuilder.required;
+        /**
+         * Define a schema for a {@link FieldKinds.sequence|sequence field}.
+         * @remarks
+         * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.
+         *
+         * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:
+         * therefore this method is the same as the static version.
+         */
+        this.sequence = SchemaBuilder.sequence;
+        /**
+         * {@link leaf.number}
+         */
+        this.number = leafDomain_1.leaf.number;
+        /**
+         * {@link leaf.boolean}
+         */
+        this.boolean = leafDomain_1.leaf.boolean;
+        /**
+         * {@link leaf.string}
+         */
+        this.string = leafDomain_1.leaf.string;
+        /**
+         * {@link leaf.handle}
+         */
+        this.handle = leafDomain_1.leaf.handle;
+        /**
+         * {@link leaf.null}
+         */
+        this.null = leafDomain_1.leaf.null;
+    }
+    object(name, t) {
+        const schema = super.object(name, t);
+        return (0, simple_tree_1.addFactory)(schema);
+    }
+    objectRecursive(name, t) {
+        return this.object(name, t);
+    }
+    list(nameOrAllowedTypes, allowedTypes) {
+        if (allowedTypes === undefined) {
+            const types = nameOrAllowedTypes;
+            const fullName = structuralName("List", types);
+            return (0, util_1.getOrCreate)(this.structuralTypes, fullName, () => this.namedList(fullName, nameOrAllowedTypes));
+        }
+        return this.namedList(nameOrAllowedTypes, allowedTypes);
+    }
+    /**
+     * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.
+     *
+     * The name must be unique among all TreeNodeSchema in the the document schema.
+     *
+     * @privateRemarks
+     * TODO: If A custom "List" API is added as a subtype of {@link FieldNode}, this would opt into that.
+     */
+    namedList(name, allowedTypes) {
+        const schema = feature_libraries_1.FieldNodeSchema.create(this, this.scoped(name), this.sequence(allowedTypes));
+        this.addNodeSchema(schema);
+        return schema;
+    }
+    map(nameOrAllowedTypes, allowedTypes) {
+        if (allowedTypes === undefined) {
+            const types = nameOrAllowedTypes;
+            const fullName = structuralName("Map", types);
+            return (0, util_1.getOrCreate)(this.structuralTypes, fullName, () => super.map(fullName, (0, feature_libraries_1.normalizeField)(nameOrAllowedTypes, feature_libraries_1.FieldKinds.optional)));
+        }
+        return super.map(nameOrAllowedTypes, (0, feature_libraries_1.normalizeField)(allowedTypes, feature_libraries_1.FieldKinds.optional));
+    }
+    /**
+     * 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 (or the "recursive" SchemaBuilder methods tends to break VSCode's IntelliSense every time anything related to that code (even comments) is edited.
+     * The command `TypeScript: Restart TS Server` should fix it.
+     * Sometimes this does not work: the exact cause has not been confirmed but if you have the file open multiple times (for example in both sides of a window split into two columns): closing the extra copy may help.
+     * Focusing the file with the errors before running `TypeScript: Restart TS Server` can also 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`.
+     */
+    fixRecursiveReference(...types) { }
+}
+exports.SchemaBuilder = SchemaBuilder;
+/**
+ * Define a schema for an {@link FieldKinds.optional|optional field}.
+ * @remarks
+ * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.
+ *
+ * This method is also available as an instance method on {@link SchemaBuilder}.
+ */
+SchemaBuilder.optional = fieldHelper(feature_libraries_1.FieldKinds.optional);
+/**
+ * Define a schema for a {@link FieldKinds.required|required field}.
+ * @remarks
+ * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.
+ *
+ * This method is also available as an instance method on {@link SchemaBuilder}.
+ */
+SchemaBuilder.required = fieldHelper(feature_libraries_1.FieldKinds.required);
+/**
+ * Define a schema for a {@link FieldKinds.sequence|sequence field}.
+ * @remarks
+ * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.
+ *
+ * This method is also available as an instance method on {@link SchemaBuilder}
+ */
+SchemaBuilder.sequence = fieldHelper(feature_libraries_1.FieldKinds.sequence);
+/**
+ * Returns a wrapper around SchemaBuilder.field for a specific FieldKind.
+ */
+function fieldHelper(kind) {
+    return (allowedTypes) => SchemaBuilder.field(kind, allowedTypes);
+}
+function structuralName(collectionName, allowedTypes) {
+    let inner;
+    if (allowedTypes === feature_libraries_1.Any) {
+        inner = "Any";
+    }
+    else if (allowedTypes instanceof feature_libraries_1.TreeNodeSchemaBase) {
+        return structuralName(collectionName, [allowedTypes]);
+    }
+    else {
+        (0, core_utils_1.assert)(Array.isArray(allowedTypes), 0x7c7 /* Types should be an array */);
+        const names = allowedTypes.map((t) => {
+            // Ensure that lazy types (functions) don't slip through here.
+            (0, core_utils_1.assert)(t instanceof feature_libraries_1.TreeNodeSchemaBase, 0x7c8 /* invalid type provided */);
+            // Adding `as string` here would silence the linter, but make this code less type safe (since if this became not a string, it would still build).
+            // Thus we explicitly check that this satisfies string.
+            // This would best be done by appending `satisfies string`, but the linter also rejects this.
+            // Therefor introducing a variable to do the same thing as `satisfies string` but such that the linter can understand:
+            const name = t.name;
+            // Just incase the compiler and linter really are onto something and this might sometimes not be a string, validate it:
+            (0, core_utils_1.assert)(typeof name === "string", 0x7c9 /* Name should be a string */);
+            return name;
+        });
+        // 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=schemaBuilder.js.map

package/dist/domains/schemaBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaBuilder.js","sourceRoot":"","sources":["../../src/domains/schemaBuilder.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 } from \"@fluidframework/core-utils\";\nimport {\n\tAny,\n\tFieldKind,\n\tFieldKinds,\n\tTreeFieldSchema,\n\tImplicitAllowedTypes,\n\tNormalizeAllowedTypes,\n\tNormalizeField,\n\tSchemaBuilderOptions,\n\tTreeNodeSchema,\n\tMapFieldSchema,\n\tnormalizeField,\n\tSchemaBuilderBase,\n\tImplicitFieldSchema,\n\tRequired,\n\tObjectNodeSchema,\n\tUnenforced,\n\tAllowedTypes,\n\tFieldNodeSchema,\n\tMapNodeSchema,\n\tTreeNodeSchemaBase,\n} from \"../feature-libraries\";\nimport { FactoryTreeSchema, addFactory } from \"../simple-tree\";\nimport { RestrictiveReadonlyRecord, getOrCreate, isAny, requireFalse } from \"../util\";\nimport { leaf } from \"./leafDomain\";\n\n/**\n * A {@link ObjectNodeSchema} that satisfies the {@link TreeObjectFactory} and therefore can create {@link TreeObjectNode}s.\n * @privateRemarks\n * This type exists because TypeScript is not able to correlate the two places where it is used if the body of this type is inlined.\n */\nexport type FactoryObjectNodeSchema<\n\tTScope extends string,\n\tName extends number | string,\n\tT extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n> = FactoryTreeSchema<\n\tObjectNodeSchema<`${TScope}.${Name}`, { [key in keyof T]: NormalizeField<T[key], Required> }>\n>;\n\n/**\n * Same as `FactoryObjectNodeSchema` but with less type safety and works for recursive objects.\n * Reduced type safety is a side effect of a workaround for a TypeScript limitation.\n *\n * See {@link Unenforced} for details.\n *\n * TODO: Make this work with ImplicitFieldSchema.\n */\nexport type FactoryObjectNodeSchemaRecursive<\n\tTScope extends string,\n\tName extends number | string,\n\tT extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,\n> = FactoryTreeSchema<ObjectNodeSchema<`${TScope}.${Name}`, T>>;\n\n/**\n * Builds schema libraries, and the schema within them.\n *\n * @remarks\n * Fields, when inferred from {@link ImplicitFieldSchema}, default to the `Required` {@link FieldKind} (except for in Maps, which default to `Optional`).\n * Implicitly includes `leaf` schema library by default.\n *\n * This type has some built in defaults which impact compatibility.\n * This includes which {@link FieldKind}s it uses.\n * To ensure that these defaults can be updated without compatibility issues,\n * this class is versioned: the number in its name indicates its compatibility,\n * and if its defaults are changed to ones that would not be compatible with a version of the application using the previous versions,\n * this number will be updated to make it impossible for an app to implicitly do a compatibility breaking change by updating this package.\n * Major package version updates are allowed to break API compatibility, but must not break content compatibility unless a corresponding code change is made in the app to opt in.\n *\n * @privateRemarks\n * TODO: Maybe rename to DefaultSchemaBuilder1 because of the versioning implications above.\n * Same applies to SchemaBuilder.\n * TODO: figure out a way to link `leaf` above without breaking API Extractor.\n * @sealed\n * @deprecated Users of this class should either use {@link SchemaBuilderBase} and explicitly work with {@link TreeFieldSchema}, or use SchemaFactory and work at its higher level of abstraction.\n */\nexport class SchemaBuilder<\n\tTScope extends string = string,\n\tTName extends string | number = string,\n> extends SchemaBuilderBase<TScope, typeof FieldKinds.required, TName> {\n\tprivate readonly structuralTypes: Map<string, TreeNodeSchema> = new Map();\n\n\tpublic constructor(options: SchemaBuilderOptions<TScope>) {\n\t\tsuper(FieldKinds.required, {\n\t\t\t...options,\n\t\t\tlibraries: [...(options.libraries ?? []), leaf.library],\n\t\t});\n\t}\n\n\tpublic override object<\n\t\tconst Name extends TName,\n\t\tconst T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n\t>(name: Name, t: T): FactoryObjectNodeSchema<TScope, Name, T> {\n\t\tconst schema = super.object(name, t);\n\t\treturn addFactory(schema) as unknown as FactoryObjectNodeSchema<TScope, Name, T>;\n\t}\n\n\tpublic override objectRecursive<\n\t\tconst Name extends TName,\n\t\tconst T extends Unenforced<RestrictiveReadonlyRecord<string, ImplicitFieldSchema>>,\n\t>(name: Name, t: T): FactoryObjectNodeSchemaRecursive<TScope, Name, T> {\n\t\treturn this.object(\n\t\t\tname,\n\t\t\tt as unknown as RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n\t\t) as unknown as FactoryObjectNodeSchemaRecursive<TScope, Name, T>;\n\t}\n\n\t/**\n\t * Define (and add to this library if not already present) a structurally typed {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.\n\t *\n\t * @remarks\n\t * The {@link TreeNodeSchemaIdentifier} for this List 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 lists, other types in this schema builder should avoid names of the form `List<${string}>`.\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\tpublic list<const T extends TreeNodeSchema | Any | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): FieldNodeSchema<\n\t\t`${TScope}.List<${string}>`,\n\t\tTreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>\n\t>;\n\n\t/**\n\t * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.\n\t *\n\t * The name must be unique among all TreeNodeSchema in the the document schema.\n\t */\n\tpublic list<Name extends TName, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): FieldNodeSchema<\n\t\t`${TScope}.${Name}`,\n\t\tTreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>\n\t>;\n\n\tpublic list<const T extends ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | Any | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): FieldNodeSchema<\n\t\t`${TScope}.${string}`,\n\t\tTreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>\n\t> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as\n\t\t\t\t| (T & TreeNodeSchema)\n\t\t\t\t| Any\n\t\t\t\t| readonly TreeNodeSchema[];\n\t\t\tconst fullName = structuralName(\"List\", types);\n\t\t\treturn getOrCreate(this.structuralTypes, fullName, () =>\n\t\t\t\tthis.namedList(fullName, nameOrAllowedTypes as T),\n\t\t\t) as FieldNodeSchema<\n\t\t\t\t`${TScope}.${string}`,\n\t\t\t\tTreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>\n\t\t\t>;\n\t\t}\n\t\treturn this.namedList(nameOrAllowedTypes as TName, allowedTypes);\n\t}\n\n\t/**\n\t * Define (and add to this library) a {@link FieldNodeSchema} for a {@link (TreeListNode:interface)}.\n\t *\n\t * The name must be unique among all TreeNodeSchema in the the document schema.\n\t *\n\t * @privateRemarks\n\t * TODO: If A custom \"List\" API is added as a subtype of {@link FieldNode}, this would opt into that.\n\t */\n\tprivate namedList<Name extends TName | string, const T extends ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tallowedTypes: T,\n\t): FieldNodeSchema<\n\t\t`${TScope}.${Name}`,\n\t\tTreeFieldSchema<typeof FieldKinds.sequence, NormalizeAllowedTypes<T>>\n\t> {\n\t\tconst schema = FieldNodeSchema.create(\n\t\t\tthis,\n\t\t\tthis.scoped(name as TName & Name),\n\t\t\tthis.sequence(allowedTypes),\n\t\t);\n\t\tthis.addNodeSchema(schema);\n\t\treturn schema;\n\t}\n\n\t/**\n\t * Define (and add to this library if not already present) a structurally typed {@link MapNodeSchema} for a {@link TreeMapNode}.\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 * @privateRemarks\n\t * See note on list.\n\t */\n\tpublic override map<const T extends TreeNodeSchema | Any | readonly TreeNodeSchema[]>(\n\t\tallowedTypes: T,\n\t): MapNodeSchema<`${TScope}.Map<${string}>`, NormalizeField<T, typeof FieldKinds.optional>>;\n\n\t/**\n\t * Define (and add to this library) a {@link MapNodeSchema} for a {@link TreeMapNode}.\n\t */\n\tpublic override map<Name extends TName, const T extends MapFieldSchema | ImplicitAllowedTypes>(\n\t\tname: Name,\n\t\tfieldSchema: T,\n\t): MapNodeSchema<`${TScope}.${Name}`, NormalizeField<T, typeof FieldKinds.optional>>;\n\n\tpublic override map<const T extends MapFieldSchema | ImplicitAllowedTypes>(\n\t\tnameOrAllowedTypes: TName | ((T & TreeNodeSchema) | Any | readonly TreeNodeSchema[]),\n\t\tallowedTypes?: T,\n\t): MapNodeSchema<`${TScope}.${string}`, NormalizeField<T, typeof FieldKinds.optional>> {\n\t\tif (allowedTypes === undefined) {\n\t\t\tconst types = nameOrAllowedTypes as\n\t\t\t\t| (T & TreeNodeSchema)\n\t\t\t\t| Any\n\t\t\t\t| 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\tsuper.map(\n\t\t\t\t\t\tfullName as TName,\n\t\t\t\t\t\tnormalizeField(nameOrAllowedTypes as T, FieldKinds.optional),\n\t\t\t\t\t) as TreeNodeSchema,\n\t\t\t) as MapNodeSchema<\n\t\t\t\t`${TScope}.${string}`,\n\t\t\t\tNormalizeField<T, typeof FieldKinds.optional>\n\t\t\t>;\n\t\t}\n\t\treturn super.map(\n\t\t\tnameOrAllowedTypes as TName,\n\t\t\tnormalizeField(allowedTypes, FieldKinds.optional),\n\t\t);\n\t}\n\n\t/**\n\t * Define a schema for an {@link FieldKinds.optional|optional field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.\n\t *\n\t * This method is also available as an instance method on {@link SchemaBuilder}.\n\t */\n\tpublic static optional = fieldHelper(FieldKinds.optional);\n\n\t/**\n\t * Define a schema for an {@link FieldKinds.optional|optional field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.optional` to {@link TreeFieldSchema.create}.\n\t *\n\t * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:\n\t * therefore this method is the same as the static version.\n\t */\n\tpublic readonly optional = SchemaBuilder.optional;\n\n\t/**\n\t * Define a schema for a {@link FieldKinds.required|required field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.\n\t *\n\t * This method is also available as an instance method on {@link SchemaBuilder}.\n\t */\n\tpublic static required = fieldHelper(FieldKinds.required);\n\n\t/**\n\t * Define a schema for a {@link FieldKinds.required|required field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.required` to {@link TreeFieldSchema.create}.\n\t * Note that `FieldKinds.required` is the current default field kind, so APIs accepting {@link ImplicitFieldSchema}\n\t * can be passed the `allowedTypes` and will implicitly wrap it up in a {@link FieldKinds.required|required field}.\n\t *\n\t * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:\n\t * therefore this method is the same as the static version.\n\t */\n\tpublic readonly required = SchemaBuilder.required;\n\n\t/**\n\t * Define a schema for a {@link FieldKinds.sequence|sequence field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.\n\t *\n\t * This method is also available as an instance method on {@link SchemaBuilder}\n\t */\n\tpublic static sequence = fieldHelper(FieldKinds.sequence);\n\n\t/**\n\t * Define a schema for a {@link FieldKinds.sequence|sequence field}.\n\t * @remarks\n\t * Shorthand or passing `FieldKinds.sequence` to {@link TreeFieldSchema.create}.\n\t *\n\t * Since this creates a {@link TreeFieldSchema} (and not a {@link TreeNodeSchema}), the resulting schema is structurally typed, and not impacted by the {@link SchemaBuilderBase.scope}:\n\t * therefore this method is the same as the static version.\n\t */\n\tpublic readonly sequence = SchemaBuilder.sequence;\n\n\t/**\n\t * {@link leaf.number}\n\t */\n\tpublic readonly number = leaf.number;\n\n\t/**\n\t * {@link leaf.boolean}\n\t */\n\tpublic readonly boolean = leaf.boolean;\n\n\t/**\n\t * {@link leaf.string}\n\t */\n\tpublic readonly string = leaf.string;\n\n\t/**\n\t * {@link leaf.handle}\n\t */\n\tpublic readonly handle = leaf.handle;\n\n\t/**\n\t * {@link leaf.null}\n\t */\n\tpublic readonly null = leaf.null;\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 (or the \"recursive\" SchemaBuilder methods tends to break VSCode's IntelliSense every time anything related to that code (even comments) is edited.\n\t * The command `TypeScript: Restart TS Server` should fix it.\n\t * Sometimes this does not work: the exact cause has not been confirmed but if you have the file open multiple times (for example in both sides of a window split into two columns): closing the extra copy may help.\n\t * Focusing the file with the errors before running `TypeScript: Restart TS Server` can also 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\tpublic fixRecursiveReference<T extends AllowedTypes>(...types: T): void {}\n}\n\n/**\n * Returns a wrapper around SchemaBuilder.field for a specific FieldKind.\n */\nfunction fieldHelper<Kind extends FieldKind>(kind: Kind) {\n\treturn <const T extends ImplicitAllowedTypes>(\n\t\tallowedTypes: T,\n\t): TreeFieldSchema<Kind, NormalizeAllowedTypes<T>> => SchemaBuilder.field(kind, allowedTypes);\n}\n\nexport function structuralName<const T extends string>(\n\tcollectionName: T,\n\tallowedTypes: TreeNodeSchema | Any | readonly TreeNodeSchema[],\n): `${T}<${string}>` {\n\tlet inner: string;\n\tif (allowedTypes === Any) {\n\t\tinner = \"Any\";\n\t} else if (allowedTypes instanceof TreeNodeSchemaBase) {\n\t\treturn structuralName(collectionName, [allowedTypes]);\n\t} else {\n\t\tassert(Array.isArray(allowedTypes), 0x7c7 /* Types should be an array */);\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(t instanceof TreeNodeSchemaBase, 0x7c8 /* invalid type provided */);\n\t\t\t// TypeScript should know `t.name` is a string (from the extends constraint on TreeNodeSchema's name), but the linter objects.\n\t\t\t// @ts-expect-error: Apparently TypeScript also fails to apply this constraint for some reason and is giving any:\n\t\t\ttype _check = requireFalse<isAny<typeof t.name>>;\n\t\t\t// Adding `as string` here would silence the linter, but make this code less type safe (since if this became not a string, it would still build).\n\t\t\t// Thus we explicitly check that this satisfies string.\n\t\t\t// This would best be done by appending `satisfies string`, but the linter also rejects this.\n\t\t\t// Therefor introducing a variable to do the same thing as `satisfies string` but such that the linter can understand:\n\t\t\tconst name: string = t.name;\n\t\t\t// Just incase the compiler and linter really are onto something and this might sometimes not be a string, validate it:\n\t\t\tassert(typeof name === \"string\", 0x7c9 /* Name should be a string */);\n\t\t\treturn name;\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"]}

package/dist/domains/testRecursiveDomain.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * This file exists and is package exported to aid in testing of exporting recursive types across package boundaries.
+ * Sometimes when TypeScript generates d.ts files, they type check significantly differently than the original source (One example of this: https://github.com/microsoft/TypeScript/issues/20979).
+ * Unfortunately our recursive schema types are an example of types that have this kind of issue: the d.ts files tend to get "any" instead of the recursive type reference.
+ * Currently we do not have tooling in place to test this in our test suite, and exporting these types here is a temporary crutch to aid in diagnosing this issue.
+ */
+import { TreeFieldSchema } from "../feature-libraries";
+export declare const recursiveObject: import("../feature-libraries").ObjectNodeSchema<"Test Recursive Domain.object", {
+    readonly recursive: TreeFieldSchema<import("../feature-libraries").Optional, readonly [() => import("../feature-libraries").ObjectNodeSchema<"Test Recursive Domain.object", any>]>;
+    readonly number: import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", import("..").ValueSchema.Number>;
+}>;
+export declare const recursiveObject2: import("../feature-libraries").ObjectNodeSchema<"Test Recursive Domain.object2", {
+    readonly recursive: TreeFieldSchema<import("../feature-libraries").Optional, readonly [() => import("../feature-libraries").ObjectNodeSchema<"Test Recursive Domain.object2", any>]>;
+    readonly number: TreeFieldSchema<import("../feature-libraries").Optional, readonly [import("../feature-libraries").LeafNodeSchema<"com.fluidframework.leaf.number", import("..").ValueSchema.Number>]>;
+}>;
+export declare const library: import("../feature-libraries").SchemaLibrary;
+//# sourceMappingURL=testRecursiveDomain.d.ts.map

package/dist/domains/testRecursiveDomain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testRecursiveDomain.d.ts","sourceRoot":"","sources":["../../src/domains/testRecursiveDomain.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAA+C,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAMpG,eAAO,MAAM,eAAe;;;EAG1B,CAAC;AAOH,eAAO,MAAM,gBAAgB;;;EAG3B,CAAC;AAUH,eAAO,MAAM,OAAO,8CAAwB,CAAC"}

package/dist/domains/testRecursiveDomain.js

@@ -0,0 +1,42 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.library = exports.recursiveObject2 = exports.recursiveObject = void 0;
+/**
+ * This file exists and is package exported to aid in testing of exporting recursive types across package boundaries.
+ * Sometimes when TypeScript generates d.ts files, they type check significantly differently than the original source (One example of this: https://github.com/microsoft/TypeScript/issues/20979).
+ * Unfortunately our recursive schema types are an example of types that have this kind of issue: the d.ts files tend to get "any" instead of the recursive type reference.
+ * Currently we do not have tooling in place to test this in our test suite, and exporting these types here is a temporary crutch to aid in diagnosing this issue.
+ */
+const feature_libraries_1 = require("../feature-libraries");
+const leafDomain_1 = require("./leafDomain");
+const builder = new feature_libraries_1.SchemaBuilderBase(feature_libraries_1.FieldKinds.optional, { scope: "Test Recursive Domain" });
+exports.recursiveObject = builder.objectRecursive("object", {
+    recursive: feature_libraries_1.TreeFieldSchema.createUnsafe(feature_libraries_1.FieldKinds.optional, [() => exports.recursiveObject]),
+    number: leafDomain_1.leaf.number,
+});
+function fixRecursiveReference(...types) { }
+const recursiveReference = () => exports.recursiveObject2;
+fixRecursiveReference(recursiveReference);
+exports.recursiveObject2 = builder.object("object2", {
+    recursive: feature_libraries_1.TreeFieldSchema.create(feature_libraries_1.FieldKinds.optional, [recursiveReference]),
+    number: leafDomain_1.leaf.number,
+});
+exports.library = builder.intoLibrary();
+{
+    const b = new feature_libraries_1.SchemaBuilderBase(feature_libraries_1.FieldKinds.optional, { scope: "Test Recursive Domain" });
+    const node = b.objectRecursive("object", {
+        child: feature_libraries_1.TreeFieldSchema.createUnsafe(feature_libraries_1.FieldKinds.optional, [() => node]),
+    });
+    const _field = feature_libraries_1.TreeFieldSchema.createUnsafe(feature_libraries_1.FieldKinds.optional, [node]);
+    // All these cause TSC to "RangeError: Maximum call stack size exceeded"
+    // const _field4 = TreeFieldSchema.create(FieldKinds.optional, [node]);
+    // const _field2 = b.optional(node);
+    // const _field3 = SchemaBuilder.optional(node);
+    // const schema = b.intoSchema(field);
+    // const schema = b.intoSchema(_field);
+}
+//# sourceMappingURL=testRecursiveDomain.js.map

package/dist/domains/testRecursiveDomain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testRecursiveDomain.js","sourceRoot":"","sources":["../../src/domains/testRecursiveDomain.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH;;;;;GAKG;AAEH,4DAAoG;AAEpG,6CAAoC;AAEpC,MAAM,OAAO,GAAG,IAAI,qCAAiB,CAAC,8BAAU,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAC;AAElF,QAAA,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE;IAChE,SAAS,EAAE,mCAAe,CAAC,YAAY,CAAC,8BAAU,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,uBAAe,CAAC,CAAC;IACrF,MAAM,EAAE,iBAAI,CAAC,MAAM;CACnB,CAAC,CAAC;AAEH,SAAS,qBAAqB,CAAyB,GAAG,KAAQ,IAAS,CAAC;AAE5E,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,wBAAgB,CAAC;AAClD,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;AAE7B,QAAA,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE;IACzD,SAAS,EAAE,mCAAe,CAAC,MAAM,CAAC,8BAAU,CAAC,QAAQ,EAAE,CAAC,kBAAkB,CAAC,CAAC;IAC5E,MAAM,EAAE,iBAAI,CAAC,MAAM;CACnB,CAAC,CAAC;AAUU,QAAA,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;AAE7C;IACC,MAAM,CAAC,GAAG,IAAI,qCAAiB,CAAC,8BAAU,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAC;IACzF,MAAM,IAAI,GAAG,CAAC,CAAC,eAAe,CAAC,QAAQ,EAAE;QACxC,KAAK,EAAE,mCAAe,CAAC,YAAY,CAAC,8BAAU,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;KACtE,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,mCAAe,CAAC,YAAY,CAAC,8BAAU,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,wEAAwE;IACxE,uEAAuE;IACvE,oCAAoC;IACpC,gDAAgD;IAChD,sCAAsC;IACtC,uCAAuC;CACvC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * This file exists and is package exported to aid in testing of exporting recursive types across package boundaries.\n * Sometimes when TypeScript generates d.ts files, they type check significantly differently than the original source (One example of this: https://github.com/microsoft/TypeScript/issues/20979).\n * Unfortunately our recursive schema types are an example of types that have this kind of issue: the d.ts files tend to get \"any\" instead of the recursive type reference.\n * Currently we do not have tooling in place to test this in our test suite, and exporting these types here is a temporary crutch to aid in diagnosing this issue.\n */\n\nimport { AllowedTypes, FieldKinds, SchemaBuilderBase, TreeFieldSchema } from \"../feature-libraries\";\nimport { areSafelyAssignable, isAny, requireFalse, requireTrue } from \"../util\";\nimport { leaf } from \"./leafDomain\";\n\nconst builder = new SchemaBuilderBase(FieldKinds.optional, { scope: \"Test Recursive Domain\" });\n\nexport const recursiveObject = builder.objectRecursive(\"object\", {\n\trecursive: TreeFieldSchema.createUnsafe(FieldKinds.optional, [() => recursiveObject]),\n\tnumber: leaf.number,\n});\n\nfunction fixRecursiveReference<T extends AllowedTypes>(...types: T): void {}\n\nconst recursiveReference = () => recursiveObject2;\nfixRecursiveReference(recursiveReference);\n\nexport const recursiveObject2 = builder.object(\"object2\", {\n\trecursive: TreeFieldSchema.create(FieldKinds.optional, [recursiveReference]),\n\tnumber: leaf.number,\n});\n\ntype _0 = requireFalse<isAny<typeof recursiveObject2>>;\ntype _1 = requireTrue<\n\tareSafelyAssignable<\n\t\ttypeof recursiveObject2,\n\t\tReturnType<(typeof recursiveObject2.objectNodeFieldsObject.recursive.allowedTypes)[0]>\n\t>\n>;\n\nexport const library = builder.intoLibrary();\n\n{\n\tconst b = new SchemaBuilderBase(FieldKinds.optional, { scope: \"Test Recursive Domain\" });\n\tconst node = b.objectRecursive(\"object\", {\n\t\tchild: TreeFieldSchema.createUnsafe(FieldKinds.optional, [() => node]),\n\t});\n\tconst _field = TreeFieldSchema.createUnsafe(FieldKinds.optional, [node]);\n\t// All these cause TSC to \"RangeError: Maximum call stack size exceeded\"\n\t// const _field4 = TreeFieldSchema.create(FieldKinds.optional, [node]);\n\t// const _field2 = b.optional(node);\n\t// const _field3 = SchemaBuilder.optional(node);\n\t// const schema = b.intoSchema(field);\n\t// const schema = b.intoSchema(_field);\n}\n"]}