@fluidframework/tree 2.1.0 → 2.3.0-288113

package/{dist/simple-tree → lib/simple-tree/core}/types.d.ts

@@ -3,8 +3,9 @@
  * Licensed under the MIT License.
  */
 import type { ErasedType } from "@fluidframework/core-interfaces";
-import { type TreeNodeSchema, type WithType, typeNameSymbol } from "./schemaTypes.js";
-import { type FlexTreeNode, type MapTreeNode } from "../feature-libraries/index.js";
+import { NodeKind, type TreeNodeSchemaClass } from "./treeNodeSchema.js";
+import { type WithType, typeNameSymbol, type typeSchemaSymbol } from "./withType.js";
+import { type FlexTreeNode } from "../../feature-libraries/index.js";
 /**
  * Type alias to document which values are un-hydrated.
  *
@@ -15,9 +16,26 @@ import { type FlexTreeNode, type MapTreeNode } from "../feature-libraries/index.
  * @public
  */
 export type Unhydrated<T> = T;
+/**
+ * Data included for {@link TreeChangeEvents.nodeChanged}.
+ * @public
+ */
+export interface NodeChangedData {
+    /**
+     * When the node changed is an object or Map node, this lists all the properties which changed.
+     * @remarks
+     * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).
+     */
+    readonly changedProperties?: ReadonlySet<string>;
+}
 /**
  * A collection of events that can be emitted by a {@link TreeNode}.
  *
+ * @remarks
+ * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.
+ * This is considered a known issue, and should be fixed in future versions.
+ * Do not rely on the fact that editing unhydrated nodes does not trigger their events.
+ *
  * @privateRemarks
  * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).
  * Probably have object node and map node specific APIs for this.
@@ -36,17 +54,15 @@ export type Unhydrated<T> = T;
  *
  * @sealed @public
  */
-export interface TreeChangeEvents {
+export interface TreeChangeEvents<TNode = TreeNode> {
     /**
-     * Emitted by a node after a batch of changes has been applied to the tree, if a change affected the node, where a
-     * change is:
+     * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.
      *
-     * - For an object node, when the value of one of its properties changes (i.e., the property's value is set
-     * to something else, including `undefined`).
+     * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).
      *
-     * - For an array node, when an element is added, removed, or moved.
+     * - Array node define a change as when an element is added, removed, moved or replaced.
      *
-     * - For a map node, when an entry is added, updated, or removed.
+     * - Map nodes define a change as when an entry is added, updated, or removed.
      *
      * @remarks
      * This event is not emitted when:
@@ -61,15 +77,17 @@ export interface TreeChangeEvents {
      * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in
      * the client that made the original edit.
      *
-     * When it is emitted, the tree is guaranteed to be in-schema.
+     * When the event is emitted, the tree is guaranteed to be in-schema.
      *
      * @privateRemarks
      * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.
      * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the
      * node, or when the node has to be updated due to resolution of a merge conflict
      * (for example a previously applied local change might be undone, then reapplied differently or not at all).
+     *
+     * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).
      */
-    nodeChanged(): void;
+    nodeChanged(data: NodeChangedData & (TNode extends WithType<string, NodeKind.Map | NodeKind.Object> ? Required<Pick<NodeChangedData, "changedProperties">> : unknown)): void;
     /**
      * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the
      * subtree rooted at it.
@@ -88,6 +106,7 @@ export interface TreeChangeEvents {
      */
     treeChanged(): void;
 }
+export type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;
 /**
  * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
  *
@@ -117,8 +136,15 @@ export declare abstract class TreeNode implements WithType {
      * Adds a type symbol for stronger typing.
      * @privateRemarks
      * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+     * @deprecated Use {@link typeSchemaSymbol} instead.
      */
     abstract get [typeNameSymbol](): string;
+    /**
+     * Adds a type symbol for stronger typing.
+     * @privateRemarks
+     * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.
+     */
+    abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;
     /**
      * Provides `instanceof` support for testing if a value is a `TreeNode`.
      * @remarks
@@ -135,8 +161,20 @@ export declare abstract class TreeNode implements WithType {
      * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.
      */
     static [Symbol.hasInstance]<TSchema extends abstract new (...args: any[]) => TreeNode>(this: TSchema, value: unknown): value is InstanceType<TSchema>;
-    protected constructor();
+    /**
+     * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
+     * @privateRemarks
+     * `token` must be the {@link privateToken} value, which is not package exported.
+     * This is used to detect invalid subclasses.
+     *
+     * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
+     */
+    protected constructor(token: unknown);
 }
+/**
+ * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
+ */
+export declare const privateToken: {};
 /**
  * Check if the prototype derived's prototype chain contains `base`.
  * @param derived - prototype to check
@@ -144,73 +182,6 @@ export declare abstract class TreeNode implements WithType {
  * @returns true iff `base` is in the prototype chain starting at `derived`.
  */
 export declare function inPrototypeChain(derived: object | null, base: object): boolean;
-/**
- * Class which all {@link TreeNode}s must extend.
- * Since this is not exported, it allows robust detection of attempts to create TreeNodes which do not go through SchemaFactory which is the only place which exposes classes that extend this.
- *
- * This has static members which schema classes can override to provide schema specific functionality.
- * These static members are only intended to be used / overridden by code within this package, and are used by the various node kinds.
- * Access to these static members has to be done via `this.constructor.staticMember` to support the overrides, and thus can only be used in the constructor, after the base constructor has been invoked.
- */
-export declare abstract class TreeNodeValid<TInput> extends TreeNode {
-    /**
-     * Schema classes can override this to control what happens at the end of the constructor.
-     * The return value from this is returned from the constructor, allowing substituting a proxy if desired.
-     *
-     * This is not simply done in the derived constructor to enable:
-     * - this class to access the value which is being returned before it's returned from the constructor.
-     * - the derived class to be provided the input `FlexTreeNode` without relying on a field on the node to hold it.
-     */
-    protected static prepareInstance<T>(this: typeof TreeNodeValid<T>, instance: TreeNodeValid<T>, input: FlexTreeNode): TreeNodeValid<T>;
-    /**
-     * Schema classes must override to provide an implementation of RawTreeNode construction.
-     */
-    protected static buildRawNode<T>(this: typeof TreeNodeValid<T>, instance: TreeNodeValid<T>, input: T): MapTreeNode;
-    /**
-     * Schema classes can override to provide a callback that is called once when the first node is constructed.
-     * This is a good place to perform extra validation and cache schema derived data needed for the implementation of the node.
-     */
-    protected static oneTimeSetup<T>(this: typeof TreeNodeValid<T>): void;
-    /**
-     * The most derived constructor (the one invoked with the `new` operator, not a parent class constructor invoked with as `super`) used to construct an instance of this type.
-     * @remarks
-     * Captured when an instance is constructed.
-     *
-     * Used to ensure that some derived class (which must override this member, defaulting it to `undefined`) is only instantiated with a single "most derived" class (the constructor actually invoked the the user with `new`).
-     *
-     * Typically this is override in the class that statically implements {@link TreeNodeSchema} to enforce that all nodes using that schema use the same class and not different subclasses of it.
-     *
-     * Also used to detect if oneTimeSetup has run.
-     *
-     * @privateRemarks
-     * This defaults to "default", which is used to trigger an error if not overridden in the derived class.
-     *
-     * The value of this on TreeNodeValid must only be overridden by base classes and never modified.
-     * Ways to enforce this immutability prevent it from being overridden,
-     * so code modifying constructorCached should be extra careful to avoid accidentally modifying the base/inherited value.
-     */
-    protected static constructorCached: MostDerivedData | "default" | undefined;
-    /**
-     * Indicate that `this` is the most derived version of a schema, and thus the only one allowed to be used (other than by being subclassed a single time).
-     */
-    static markMostDerived(this: typeof TreeNodeValid & TreeNodeSchema): MostDerivedData;
-    constructor(input: TInput | InternalTreeNode);
-}
-/**
- * Data cached about the most derived type in a schema's class hierarchy.
- * @remarks
- * The most derived type is the only one allowed to be referenced by other schema or constructed as a node.
- * It has to be discovered lazily (when a node is constructed or when a {@link TreeViewConfiguration} is made),
- * since JavaScript provides no way to find derived classes, or inject static class initialization time logic into base classes.
- * Additionally since schema can reference other schema through lazy references which might be forward or recursive references,
- * this can not be evaluated for one schema when referenced by another schema.
- *
- * See {@link TreeNodeValid.constructorCached} and {@link TreeNodeValid.markMostDerived}.
- */
-export interface MostDerivedData {
-    readonly constructor: typeof TreeNodeValid & TreeNodeSchema;
-    oneTimeInitialized: boolean;
-}
 /**
  * A node type internal to `@fluidframework/tree`.
  * @remarks

package/lib/simple-tree/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,EAAE,QAAQ,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE,OAAO,EAAE,KAAK,QAAQ,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAErF,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9B;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,QAAQ;IACjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,WAAW,CACV,IAAI,EAAE,eAAe,GAEpB,CAAC,KAAK,SAAS,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,GAC5D,QAAQ,CAAC,IAAI,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC,GACpD,OAAO,CAAC,GACV,IAAI,CAAC;IAER;;;;;;;;;;;;;;;OAeG;IACH,WAAW,IAAI,IAAI,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,SAAS,IAAI,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,QAAS,YAAW,QAAQ;;IA6BjD;;;;;OAKG;IAEH,aAAoB,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC;IAE/C;;;;OAIG;IACH,aAAoB,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC;IAE9D;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;IAErE;;;;;;OAMG;WACW,CAAC,MAAM,CAAC,WAAW,CAAC,CACjC,OAAO,SAAS,QAAQ,MACvB,GAAG,IAAI,EAAE,GAAG,EAAE,KACV,QAAQ,EACZ,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,OAAO,CAAC;IAahE;;;;;;;OAOG;IACH,SAAS,aAAa,KAAK,EAAE,OAAO;CAKpC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,IAAK,CAAC;AAE/B;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAS9E;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAChB,SAAQ,UAAU,CAAC,uCAAuC,CAAC;CAAG;AAE/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAGnE"}

package/lib/simple-tree/core/types.js

@@ -0,0 +1,111 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var _TreeNode_brand;
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { NodeKind } from "./treeNodeSchema.js";
+// eslint-disable-next-line import/no-deprecated
+import { typeNameSymbol } from "./withType.js";
+import { tryGetTreeNodeSchema } from "./treeNodeKernel.js";
+import { isFlexTreeNode } from "../../feature-libraries/index.js";
+/**
+ * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.
+ *
+ * @remarks
+ * Base type which all nodes implement.
+ *
+ * This can be used as a type to indicate/document values which should be tree nodes.
+ * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.
+ *
+ * Instances of tree nodes must be created by opening an existing document, inserting values into the document,
+ * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.
+ * @privateRemarks
+ * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})
+ * and some runtime enforcement of schema class policy (see the the validation in the constructor).
+ * This class is however only `type` exported not value exported, preventing the class object from being used,
+ * similar to how interfaces work.
+ *
+ * Not all node implementations include this in their prototype chain (some hide it with a proxy),
+ * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.
+ * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.
+ * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).
+ * @sealed @public
+ */
+export class TreeNode {
+    static [(_TreeNode_brand = new WeakMap(), Symbol.hasInstance)](value) {
+        const schema = tryGetTreeNodeSchema(value);
+        if (schema === undefined || schema.kind === NodeKind.Leaf) {
+            return false;
+        }
+        assert("prototype" in schema, 0x98a /* expected class based schema */);
+        return inPrototypeChain(schema.prototype, this.prototype);
+    }
+    /**
+     * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.
+     * @privateRemarks
+     * `token` must be the {@link privateToken} value, which is not package exported.
+     * This is used to detect invalid subclasses.
+     *
+     * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.
+     */
+    constructor(token) {
+        /**
+         * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.
+         * @remarks
+         * This field forces TypeScript to use nominal instead of structural typing,
+         * preventing compiler error messages and tools like "add missing properties"
+         * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.
+         * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.
+         *
+         * @privateRemarks
+         * This is a JavaScript private field, so is not accessible from outside this class.
+         * This prevents it from having name collisions with object fields.
+         * Since this is private, the type of this field is stripped in the d.ts file.
+         * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.
+         * To avoid this having any runtime impact, the field is uninitialized.
+         *
+         * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.
+         * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.
+         * To avoid all this mess, this field is required, not optional.
+         *
+         * Another option would be to use a symbol (possibly as a private field).
+         * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.
+         *
+         * The [type] symbol provides a lot of the value this private brand does, but is not all of it:
+         * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)
+         * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.
+         */
+        _TreeNode_brand.set(this, void 0);
+        if (token !== privateToken) {
+            throw new UsageError("TreeNodes must extend schema classes created by SchemaFactory");
+        }
+    }
+}
+/**
+ * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.
+ */
+export const privateToken = {};
+/**
+ * Check if the prototype derived's prototype chain contains `base`.
+ * @param derived - prototype to check
+ * @param base - prototype to search for
+ * @returns true iff `base` is in the prototype chain starting at `derived`.
+ */
+// eslint-disable-next-line @rushstack/no-new-null
+export function inPrototypeChain(derived, base) {
+    let checking = derived;
+    while (checking !== null) {
+        if (base === checking) {
+            return true;
+        }
+        checking = Reflect.getPrototypeOf(checking);
+    }
+    return false;
+}
+export function toFlexTreeNode(node) {
+    assert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);
+    return node;
+}
+//# sourceMappingURL=types.js.map

package/lib/simple-tree/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/simple-tree/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAGtE,OAAO,EAAE,QAAQ,EAA4B,MAAM,qBAAqB,CAAC;AACzE,gDAAgD;AAChD,OAAO,EAAiB,cAAc,EAAyB,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAqB,MAAM,kCAAkC,CAAC;AAkHrF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAgB,QAAQ;IAmEtB,MAAM,CAAC,mCAAC,MAAM,CAAC,WAAW,EAAC,CAA8B,KAAc;QAC7E,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAE3C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC3D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,WAAW,IAAI,MAAM,EAAE,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACvE,OAAO,gBAAgB,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;;OAOG;IACH,YAAsB,KAAc;QArFpC;;;;;;;;;;;;;;;;;;;;;;;;;WAyBG;QACM,kCAAiB;QA4DzB,IAAI,KAAK,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,IAAI,UAAU,CAAC,+DAA+D,CAAC,CAAC;QACvF,CAAC;IACF,CAAC;CACD;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAAC,OAAsB,EAAE,IAAY;IACpE,IAAI,QAAQ,GAAG,OAAO,CAAC;IACvB,OAAO,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACb,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAaD,MAAM,UAAU,cAAc,CAAC,IAAsB;IACpD,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACnE,OAAO,IAAI,CAAC;AACb,CAAC","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/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\nimport type { ErasedType } from \"@fluidframework/core-interfaces\";\n\nimport { NodeKind, type TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n// eslint-disable-next-line import/no-deprecated\nimport { type WithType, typeNameSymbol, type typeSchemaSymbol } from \"./withType.js\";\nimport { tryGetTreeNodeSchema } from \"./treeNodeKernel.js\";\nimport { isFlexTreeNode, type FlexTreeNode } from \"../../feature-libraries/index.js\";\n\n/**\n * Type alias to document which values are un-hydrated.\n *\n * Un-hydrated values are nodes produced from schema's create functions that haven't been inserted into a tree yet.\n *\n * Since un-hydrated nodes become hydrated when inserted, strong typing can't be used to distinguish them.\n * This no-op wrapper is used instead.\n * @public\n */\nexport type Unhydrated<T> = T;\n\n/**\n * Data included for {@link TreeChangeEvents.nodeChanged}.\n * @public\n */\nexport interface NodeChangedData {\n\t/**\n\t * When the node changed is an object or Map node, this lists all the properties which changed.\n\t * @remarks\n\t * This only includes changes to the node itself (which would trigger {@link TreeChangeEvents.nodeChanged}).\n\t */\n\treadonly changedProperties?: ReadonlySet<string>;\n}\n\n/**\n * A collection of events that can be emitted by a {@link TreeNode}.\n *\n * @remarks\n * Currently events can be subscribed to for {@link Unhydrated} nodes, however no events will be triggered for the nodes until after they are hydrated.\n * This is considered a known issue, and should be fixed in future versions.\n * Do not rely on the fact that editing unhydrated nodes does not trigger their events.\n *\n * @privateRemarks\n * TODO: add a way to subscribe to a specific field (for nodeChanged and treeChanged).\n * Probably have object node and map node specific APIs for this.\n *\n * TODO: ensure that subscription API for fields aligns with API for subscribing to the root.\n *\n * TODO: add more wider area (avoid needing tons of nodeChanged registration) events for use-cases other than treeChanged.\n * Some ideas:\n *\n * - treeChanged, but with some subtrees/fields/paths excluded\n * - helper to batch several nodeChanged calls to a treeChanged scope\n * - parent change (ex: registration on the parent field for a specific index: maybe allow it for a range. Ex: node event takes optional field and optional index range?)\n * - new content inserted into subtree. Either provide event for this and/or enough info to treeChanged to find and search the new sub-trees.\n * Add separate (non event related) API to efficiently scan tree for given set of types (using low level cursor and schema based filtering)\n * to allow efficiently searching for new content (and initial content) of a given type.\n *\n * @sealed @public\n */\nexport interface TreeChangeEvents<TNode = TreeNode> {\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, if any of the changes affected the node.\n\t *\n\t * - Object nodes define a change as the value of one of its properties changing (i.e., the property's value is set, including when set to undefined).\n\t *\n\t * - Array node define a change as when an element is added, removed, moved or replaced.\n\t *\n\t * - Map nodes define a change as when an entry is added, updated, or removed.\n\t *\n\t * @remarks\n\t * This event is not emitted when:\n\t *\n\t * - Properties of a child node change. Notably, updates to an array node or a map node (like adding or removing\n\t * elements/entries) will emit this event on the array/map node itself, but not on the node that contains the\n\t * array/map node as one of its properties.\n\t *\n\t * - The node is moved to a different location in the tree or removed from the tree.\n\t * In this case the event is emitted on the _parent_ node, not the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When the event is emitted, the tree is guaranteed to be in-schema.\n\t *\n\t * @privateRemarks\n\t * This event occurs whenever the apparent contents of the node instance change, regardless of what caused the change.\n\t * For example, it will fire when the local client reassigns a child, when part of a remote edit is applied to the\n\t * node, or when the node has to be updated due to resolution of a merge conflict\n\t * (for example a previously applied local change might be undone, then reapplied differently or not at all).\n\t *\n\t * TODO: defined and document event ordering (ex: bottom up, with nodeChanged before treeCHange on each level).\n\t */\n\tnodeChanged(\n\t\tdata: NodeChangedData &\n\t\t\t// For object and Map nodes, make properties specific to them required instead of optional:\n\t\t\t(TNode extends WithType<string, NodeKind.Map | NodeKind.Object>\n\t\t\t\t? Required<Pick<NodeChangedData, \"changedProperties\">>\n\t\t\t\t: unknown),\n\t): void;\n\n\t/**\n\t * Emitted by a node after a batch of changes has been applied to the tree, when something changed anywhere in the\n\t * subtree rooted at it.\n\t *\n\t * @remarks\n\t * This event is not emitted when the node itself is moved to a different location in the tree or removed from the tree.\n\t * In that case it is emitted on the _parent_ node, not the node itself.\n\t *\n\t * The node itself is part of the subtree, so this event will be emitted even if the only changes are to the properties\n\t * of the node itself.\n\t *\n\t * For remote edits, this event is not guaranteed to occur in the same order or quantity that it did in\n\t * the client that made the original edit.\n\t *\n\t * When it is emitted, the tree is guaranteed to be in-schema.\n\t */\n\ttreeChanged(): void;\n}\n\nexport type IsListener2<TListener> = TListener extends (...args: any[]) => void ? true : false;\n\n/**\n * A non-{@link NodeKind.Leaf|leaf} SharedTree node. Includes objects, arrays, and maps.\n *\n * @remarks\n * Base type which all nodes implement.\n *\n * This can be used as a type to indicate/document values which should be tree nodes.\n * Runtime use of this class object (for example when used with `instanceof` or extending it), is not currently supported.\n *\n * Instances of tree nodes must be created by opening an existing document, inserting values into the document,\n * or by using the constructors and create functions of {@link TreeNodeSchema} produced by {@link SchemaFactory}.\n * @privateRemarks\n * This is a class not an interface to enable stricter type checking (see {@link TreeNode.#brand})\n * and some runtime enforcement of schema class policy (see the the validation in the constructor).\n * This class is however only `type` exported not value exported, preventing the class object from being used,\n * similar to how interfaces work.\n *\n * Not all node implementations include this in their prototype chain (some hide it with a proxy),\n * and thus cause the default/built in `instanceof` to return false despite our type checking and all other APIs treating them as TreeNodes.\n * This class provides a custom `Symbol.hasInstance` to fix `instanceof` for this class and all classes extending it.\n * For now the type-only export prevents use of `instanceof` on this class (but allows it in subclasses like schema classes).\n * @sealed @public\n */\nexport abstract class TreeNode implements WithType {\n\t/**\n\t * This is added to prevent TypeScript from implicitly allowing non-TreeNode types to be used as TreeNodes.\n\t * @remarks\n\t * This field forces TypeScript to use nominal instead of structural typing,\n\t * preventing compiler error messages and tools like \"add missing properties\"\n\t * from adding the [type] field as a solution when using a non-TreeNode object where a TreeNode is required.\n\t * Instead TreeNodes must be created through the appropriate APIs, see the documentation on {@link TreeNode} for details.\n\t *\n\t * @privateRemarks\n\t * This is a JavaScript private field, so is not accessible from outside this class.\n\t * This prevents it from having name collisions with object fields.\n\t * Since this is private, the type of this field is stripped in the d.ts file.\n\t * To get matching type checking within and from outside the package, the least informative type (`unknown`) is used.\n\t * To avoid this having any runtime impact, the field is uninitialized.\n\t *\n\t * Making this field optional results in different type checking within this project than outside of it, since the d.ts file drops the optional aspect of the field.\n\t * This is extra confusing since since the tests get in-project typing for intellisense and separate project checking at build time.\n\t * To avoid all this mess, this field is required, not optional.\n\t *\n\t * Another option would be to use a symbol (possibly as a private field).\n\t * That approach ran into some strange difficulties causing SchemaFactory to fail to compile, and was not investigated further.\n\t *\n\t * The [type] symbol provides a lot of the value this private brand does, but is not all of it:\n\t * someone could manually (or via Intellisense auto-implement completion, or in response to a type error)\n\t * make an object literal with the [type] field and pass it off as a node: this private brand prevents that.\n\t */\n\treadonly #brand!: unknown;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\t// eslint-disable-next-line import/no-deprecated\n\tpublic abstract get [typeNameSymbol](): string;\n\n\t/**\n\t * Adds a type symbol for stronger typing.\n\t * @privateRemarks\n\t * Subclasses provide more specific strings for this to get strong typing of otherwise type compatible nodes.\n\t */\n\tpublic abstract get [typeSchemaSymbol](): TreeNodeSchemaClass;\n\n\t/**\n\t * Provides `instanceof` support for testing if a value is a `TreeNode`.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Due to type-only export, this functionality is not available outside the package.\n\t */\n\tpublic static [Symbol.hasInstance](value: unknown): value is TreeNode;\n\n\t/**\n\t * Provides `instanceof` support for all schema classes with public constructors.\n\t * @remarks\n\t * For more options, like including leaf values or narrowing to collections of schema, use `is` or `schema` from {@link TreeNodeApi}.\n\t * @privateRemarks\n\t * Despite type-only export, this functionality is available outside the package since it is inherited by subclasses.\n\t */\n\tpublic static [Symbol.hasInstance]<\n\t\tTSchema extends abstract new (\n\t\t\t...args: any[]\n\t\t) => TreeNode,\n\t>(this: TSchema, value: unknown): value is InstanceType<TSchema>;\n\n\tpublic static [Symbol.hasInstance](this: { prototype: object }, value: unknown): boolean {\n\t\tconst schema = tryGetTreeNodeSchema(value);\n\n\t\tif (schema === undefined || schema.kind === NodeKind.Leaf) {\n\t\t\treturn false;\n\t\t}\n\n\t\tassert(\"prototype\" in schema, 0x98a /* expected class based schema */);\n\t\treturn inPrototypeChain(schema.prototype, this.prototype);\n\t}\n\n\t/**\n\t * TreeNodes must extend schema classes created by SchemaFactory, and therefore this constructor should not be invoked directly by code outside this package.\n\t * @privateRemarks\n\t * `token` must be the {@link privateToken} value, which is not package exported.\n\t * This is used to detect invalid subclasses.\n\t *\n\t * All valid subclass should use {@link TreeNodeValid}, but this code doesn't directly reference it to avoid cyclic dependencies.\n\t */\n\tprotected constructor(token: unknown) {\n\t\tif (token !== privateToken) {\n\t\t\tthrow new UsageError(\"TreeNodes must extend schema classes created by SchemaFactory\");\n\t\t}\n\t}\n}\n\n/**\n * `token` to pass to {@link TreeNode}'s constructor used to detect invalid subclasses.\n */\nexport const privateToken = {};\n\n/**\n * Check if the prototype derived's prototype chain contains `base`.\n * @param derived - prototype to check\n * @param base - prototype to search for\n * @returns true iff `base` is in the prototype chain starting at `derived`.\n */\n// eslint-disable-next-line @rushstack/no-new-null\nexport function inPrototypeChain(derived: object | null, base: object): boolean {\n\tlet checking = derived;\n\twhile (checking !== null) {\n\t\tif (base === checking) {\n\t\t\treturn true;\n\t\t}\n\t\tchecking = Reflect.getPrototypeOf(checking);\n\t}\n\treturn false;\n}\n\n/**\n * A node type internal to `@fluidframework/tree`.\n * @remarks\n * This type is used in the construction of {@link TreeNode} as an implementation detail, but leaks into the public API due to how schema are implemented.\n * @privateRemarks\n * A {@link FlexTreeNode}. Includes {@link RawTreeNode}s.\n * @sealed @public\n */\nexport interface InternalTreeNode\n\textends ErasedType<\"@fluidframework/tree.InternalTreeNode\"> {}\n\nexport function toFlexTreeNode(node: InternalTreeNode): FlexTreeNode {\n\tassert(isFlexTreeNode(node), 0x963 /* Invalid InternalTreeNode */);\n\treturn node;\n}\n"]}

package/lib/simple-tree/core/withType.d.ts

@@ -0,0 +1,82 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { NodeKind, TreeNodeSchemaClass } from "./treeNodeSchema.js";
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
+ * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.
+ * @system @public
+ */
+export declare const typeNameSymbol: unique symbol;
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ *
+ * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.
+ * @system @public
+ */
+export declare const typeSchemaSymbol: unique symbol;
+/**
+ * Adds a type symbol to a type for stronger typing.
+ *
+ * @typeParam TName - Same as {@link TreeNodeSchema}'s "Name" parameter.
+ * @typeParam TKind - Same as {@link TreeNodeSchema}'s "Kind" parameter.
+ * @remarks
+ * Powers {@link TreeNode}'s strong typing setup.
+ * @example Narrow types for overloading based on NodeKind
+ * ```typescript
+ * function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];
+ * function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];
+ * function getKeys(node: TreeNode): string[] | number[];
+ * function getKeys(node: TreeNode): string[] | number[] {
+ * 	const schema = Tree.schema(node);
+ * 	switch (schema.kind) {
+ * 		case NodeKind.Array: {
+ * 			const arrayNode = node as TreeArrayNode;
+ * 			const keys: number[] = [];
+ * 			for (let index = 0; index < arrayNode.length; index++) {
+ * 				keys.push(index);
+ * 			}
+ * 			return keys;
+ * 		}
+ * 		case NodeKind.Map:
+ * 			return [...(node as TreeMapNode).keys()];
+ * 		case NodeKind.Object:
+ * 			return Object.keys(node);
+ * 		default:
+ * 			throw new Error("Unsupported Kind");
+ * 	}
+ * }
+ * ```
+ * @sealed @public
+ */
+export interface WithType<out TName extends string = string, out TKind extends NodeKind = NodeKind> {
+    /**
+     * Type symbol, marking a type in a way to increase type safety via strong type checking.
+     * @deprecated Use {@link typeSchemaSymbol} instead.
+     */
+    get [typeNameSymbol](): TName;
+    /**
+     * Type symbol, marking a type in a way to increase type safety via strong type checking.
+     */
+    get [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind>;
+}
+//# sourceMappingURL=withType.d.ts.map

package/lib/simple-tree/core/withType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"withType.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAAgC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAkC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,QAAQ,CACxB,GAAG,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,EACjC,GAAG,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ;IAErC;;;OAGG;IACH,IAAI,CAAC,cAAc,CAAC,IAAI,KAAK,CAAC;IAE9B;;OAEG;IACH,IAAI,CAAC,gBAAgB,CAAC,IAAI,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;CAC5D"}

package/lib/simple-tree/core/withType.js

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.
+ * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.
+ * @system @public
+ */
+export const typeNameSymbol = Symbol("TreeNode Type");
+/**
+ * The type of a {@link TreeNode}.
+ * For more information about the type, use `Tree.schema(theNode)` instead.
+ * @remarks
+ * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.
+ * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.
+ *
+ * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.
+ * Instead construct a real node of the desired type using its constructor.
+ *
+ * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.
+ * @privateRemarks
+ * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.
+ * @system @public
+ */
+export const typeSchemaSymbol = Symbol("TreeNode Schema");
+//# sourceMappingURL=withType.js.map

package/lib/simple-tree/core/withType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withType.js","sourceRoot":"","sources":["../../../src/simple-tree/core/withType.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,eAAe,CAAC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { NodeKind, TreeNodeSchemaClass } from \"./treeNodeSchema.js\";\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes, as well as allows the type checker to distinguish different node types.\n * @deprecated External code should use `Tree.schema(theNode)` for schema related runtime data access. For type narrowing, use `WithType` instead of the symbols directly.\n * @system @public\n */\nexport const typeNameSymbol: unique symbol = Symbol(\"TreeNode Type\");\n\n/**\n * The type of a {@link TreeNode}.\n * For more information about the type, use `Tree.schema(theNode)` instead.\n * @remarks\n * This symbol mainly exists on nodes to allow TypeScript to provide more accurate type checking.\n * `Tree.is` and `Tree.schema` provide a superset of this information in more friendly ways.\n *\n * This symbol should not manually be added to objects as doing so allows the object to be invalidly used where specific nodes are expected.\n * Instead construct a real node of the desired type using its constructor.\n *\n * This symbol should not be used directly for type narrowing. Instead use {@link WithType}.\n * @privateRemarks\n * This prevents non-nodes from being accidentally used as nodes and allows the type-checker to distinguish different node types.\n * @system @public\n */\nexport const typeSchemaSymbol: unique symbol = Symbol(\"TreeNode Schema\");\n\n/**\n * Adds a type symbol to a type for stronger typing.\n *\n * @typeParam TName - Same as {@link TreeNodeSchema}'s \"Name\" parameter.\n * @typeParam TKind - Same as {@link TreeNodeSchema}'s \"Kind\" parameter.\n * @remarks\n * Powers {@link TreeNode}'s strong typing setup.\n * @example Narrow types for overloading based on NodeKind\n * ```typescript\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Array>): number[];\n * function getKeys(node: TreeNode & WithType<string, NodeKind.Map | NodeKind.Object>): string[];\n * function getKeys(node: TreeNode): string[] | number[];\n * function getKeys(node: TreeNode): string[] | number[] {\n * \tconst schema = Tree.schema(node);\n * \tswitch (schema.kind) {\n * \t\tcase NodeKind.Array: {\n * \t\t\tconst arrayNode = node as TreeArrayNode;\n * \t\t\tconst keys: number[] = [];\n * \t\t\tfor (let index = 0; index < arrayNode.length; index++) {\n * \t\t\t\tkeys.push(index);\n * \t\t\t}\n * \t\t\treturn keys;\n * \t\t}\n * \t\tcase NodeKind.Map:\n * \t\t\treturn [...(node as TreeMapNode).keys()];\n * \t\tcase NodeKind.Object:\n * \t\t\treturn Object.keys(node);\n * \t\tdefault:\n * \t\t\tthrow new Error(\"Unsupported Kind\");\n * \t}\n * }\n * ```\n * @sealed @public\n */\nexport interface WithType<\n\tout TName extends string = string,\n\tout TKind extends NodeKind = NodeKind,\n> {\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t * @deprecated Use {@link typeSchemaSymbol} instead.\n\t */\n\tget [typeNameSymbol](): TName;\n\n\t/**\n\t * Type symbol, marking a type in a way to increase type safety via strong type checking.\n\t */\n\tget [typeSchemaSymbol](): TreeNodeSchemaClass<TName, TKind>;\n}\n"]}

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

@@ -0,0 +1,55 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { JsonTreeSchema } from "./jsonSchema.js";
+import type { ImplicitAllowedTypes } from "./schemaTypes.js";
+/**
+ * Creates a {@link https://json-schema.org/ | JSON Schema} representation of the provided {@link TreeNodeSchema}.
+ *
+ * @remarks
+ * Useful when communicating the schema to external libraries or services.
+ * Caches the result for future calls.
+ *
+ * @example
+ *
+ * A Shared Tree schema like the following:
+ *
+ * ```typescript
+ * class MyObject extends schemaFactory.object("MyObject", {
+ * 	foo: schemaFactory.number,
+ * 	bar: schemaFactory.optional(schemaFactory.string),
+ * });
+ * ```
+ *
+ * Will yield JSON Schema like the following:
+ *
+ * ```json
+ * {
+ * 	"$defs": {
+ * 		"com.fluidframework.leaf.string": {
+ * 			"type": "string",
+ * 		},
+ * 		"com.fluidframework.leaf.number": {
+ * 			"type": "number",
+ * 		},
+ * 		"com.myapp.MyObject": {
+ * 			"type": "object",
+ * 			"properties": {
+ * 				"foo": { "$ref": "com.fluidframework.leaf.number" },
+ * 				"bar": { "$ref": "com.fluidframework.leaf.string" },
+ * 			},
+ * 			"required": ["foo"],
+ * 		},
+ * 	},
+ * 	"anyOf": [ { "$ref": "#/$defs/com.myapp.MyObject" } ],
+ * }
+ * ```
+ *
+ * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
+ * For now, while still an experimental API, it is surfaced as a free function.
+ *
+ * @alpha
+ */
+export declare function getJsonSchema(schema: ImplicitAllowedTypes): JsonTreeSchema;
+//# sourceMappingURL=getJsonSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getJsonSchema.d.ts","sourceRoot":"","sources":["../../src/simple-tree/getJsonSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAW7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAK1E"}

package/lib/simple-tree/getJsonSchema.js

@@ -0,0 +1,65 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { toJsonSchema } from "./simpleSchemaToJsonSchema.js";
+import { getSimpleSchema } from "./getSimpleSchema.js";
+import { getOrCreate } from "../util/index.js";
+/**
+ * Cache in which the results of {@link getJsonSchema} are saved.
+ */
+const jsonSchemaCache = new WeakMap();
+/**
+ * Creates a {@link https://json-schema.org/ | JSON Schema} representation of the provided {@link TreeNodeSchema}.
+ *
+ * @remarks
+ * Useful when communicating the schema to external libraries or services.
+ * Caches the result for future calls.
+ *
+ * @example
+ *
+ * A Shared Tree schema like the following:
+ *
+ * ```typescript
+ * class MyObject extends schemaFactory.object("MyObject", {
+ * 	foo: schemaFactory.number,
+ * 	bar: schemaFactory.optional(schemaFactory.string),
+ * });
+ * ```
+ *
+ * Will yield JSON Schema like the following:
+ *
+ * ```json
+ * {
+ * 	"$defs": {
+ * 		"com.fluidframework.leaf.string": {
+ * 			"type": "string",
+ * 		},
+ * 		"com.fluidframework.leaf.number": {
+ * 			"type": "number",
+ * 		},
+ * 		"com.myapp.MyObject": {
+ * 			"type": "object",
+ * 			"properties": {
+ * 				"foo": { "$ref": "com.fluidframework.leaf.number" },
+ * 				"bar": { "$ref": "com.fluidframework.leaf.string" },
+ * 			},
+ * 			"required": ["foo"],
+ * 		},
+ * 	},
+ * 	"anyOf": [ { "$ref": "#/$defs/com.myapp.MyObject" } ],
+ * }
+ * ```
+ *
+ * @privateRemarks In the future, we may wish to move this to a more discoverable API location.
+ * For now, while still an experimental API, it is surfaced as a free function.
+ *
+ * @alpha
+ */
+export function getJsonSchema(schema) {
+    return getOrCreate(jsonSchemaCache, schema, () => {
+        const simpleSchema = getSimpleSchema(schema);
+        return toJsonSchema(simpleSchema);
+    });
+}
+//# sourceMappingURL=getJsonSchema.js.map

package/lib/simple-tree/getJsonSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getJsonSchema.js","sourceRoot":"","sources":["../../src/simple-tree/getJsonSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;GAEG;AACH,MAAM,eAAe,GAAG,IAAI,OAAO,EAAkC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,aAAa,CAAC,MAA4B;IACzD,OAAO,WAAW,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE;QAChD,MAAM,YAAY,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,YAAY,CAAC,YAAY,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { JsonTreeSchema } from \"./jsonSchema.js\";\nimport type { ImplicitAllowedTypes } from \"./schemaTypes.js\";\nimport { toJsonSchema } from \"./simpleSchemaToJsonSchema.js\";\nimport { getSimpleSchema } from \"./getSimpleSchema.js\";\nimport { getOrCreate } from \"../util/index.js\";\nimport type { TreeNodeSchema } from \"./core/index.js\";\n\n/**\n * Cache in which the results of {@link getJsonSchema} are saved.\n */\nconst jsonSchemaCache = new WeakMap<TreeNodeSchema, JsonTreeSchema>();\n\n/**\n * Creates a {@link https://json-schema.org/ | JSON Schema} representation of the provided {@link TreeNodeSchema}.\n *\n * @remarks\n * Useful when communicating the schema to external libraries or services.\n * Caches the result for future calls.\n *\n * @example\n *\n * A Shared Tree schema like the following:\n *\n * ```typescript\n * class MyObject extends schemaFactory.object(\"MyObject\", {\n * \tfoo: schemaFactory.number,\n * \tbar: schemaFactory.optional(schemaFactory.string),\n * });\n * ```\n *\n * Will yield JSON Schema like the following:\n *\n * ```json\n * {\n * \t\"$defs\": {\n * \t\t\"com.fluidframework.leaf.string\": {\n * \t\t\t\"type\": \"string\",\n * \t\t},\n * \t\t\"com.fluidframework.leaf.number\": {\n * \t\t\t\"type\": \"number\",\n * \t\t},\n * \t\t\"com.myapp.MyObject\": {\n * \t\t\t\"type\": \"object\",\n * \t\t\t\"properties\": {\n * \t\t\t\t\"foo\": { \"$ref\": \"com.fluidframework.leaf.number\" },\n * \t\t\t\t\"bar\": { \"$ref\": \"com.fluidframework.leaf.string\" },\n * \t\t\t},\n * \t\t\t\"required\": [\"foo\"],\n * \t\t},\n * \t},\n * \t\"anyOf\": [ { \"$ref\": \"#/$defs/com.myapp.MyObject\" } ],\n * }\n * ```\n *\n * @privateRemarks In the future, we may wish to move this to a more discoverable API location.\n * For now, while still an experimental API, it is surfaced as a free function.\n *\n * @alpha\n */\nexport function getJsonSchema(schema: ImplicitAllowedTypes): JsonTreeSchema {\n\treturn getOrCreate(jsonSchemaCache, schema, () => {\n\t\tconst simpleSchema = getSimpleSchema(schema);\n\t\treturn toJsonSchema(simpleSchema);\n\t});\n}\n"]}

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

@@ -0,0 +1,14 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import type { FlexFieldSchema } from "../feature-libraries/index.js";
+import { type ImplicitFieldSchema, type FieldSchema } from "./schemaTypes.js";
+/**
+ * Gets the {@link FieldSchema} which corresponds with the provided {@link FlexFieldSchema | flexSchema}.
+ * Caches the result on the provided `flexSchema` for future access.
+ * @param flexSchema - The flex schema on which the result will be cached.
+ * @param implicitSimpleSchema - The allowed types from which the `FieldSchema` will be derived.
+ */
+export declare function getSimpleFieldSchema(flexSchema: FlexFieldSchema, implicitSimpleSchema: ImplicitFieldSchema): FieldSchema;
+//# sourceMappingURL=getSimpleFieldSchema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getSimpleFieldSchema.d.ts","sourceRoot":"","sources":["../../src/simple-tree/getSimpleFieldSchema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAEhB,MAAM,kBAAkB,CAAC;AAO1B;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,eAAe,EAC3B,oBAAoB,EAAE,mBAAmB,GACvC,WAAW,CASb"}