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

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

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { FlexObjectNodeSchema, FlexTreeField, FlexTreeObjectNode, LocalNodeKey } from "../feature-libraries/index.js";
+import { InsertableContent } from "./proxies.js";
+import { NodeKind, ImplicitFieldSchema, TreeNodeSchemaClass, WithType, TreeFieldFromImplicitField, InsertableTreeFieldFromImplicitField, FieldSchema } from "./schemaTypes.js";
+import { TreeNode } from "./types.js";
+import { RestrictiveReadonlyRecord } from "../util/index.js";
+import { RawTreeNode } from "./rawNode.js";
+/**
+ * Helper used to produce types for object nodes.
+ * @public
+ */
+export type ObjectFromSchemaRecord<T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>> = {
+    -readonly [Property in keyof T]: TreeFieldFromImplicitField<T[Property]>;
+};
+/**
+ * A {@link TreeNode} which modules a JavaScript object.
+ * @remarks
+ * Object nodes consist of a type which specifies which {@link TreeNodeSchema} they use (see {@link TreeNodeApi.schema}), and a collections of fields, each with a distinct `key` and its own {@link FieldSchema} defining what can be placed under that key.
+ *
+ * All fields on an object node are exposed as own properties with string keys.
+ * Non-empty fields are enumerable and empty optional fields are non-enumerable own properties with the value `undefined`.
+ * No other own `own` or `enumerable` properties are included on object nodes unless the user of the node manually adds custom session only state.
+ * This allows a majority of general purpose JavaScript object processing operations (like `for...in`, `Reflect.ownKeys()` and `Object.entries()`) to enumerate all the children.
+ * @public
+ */
+export type TreeObjectNode<T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>, TypeName extends string = string> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName>;
+/**
+ * Helper used to produce types for:
+ *
+ * 1. Insertable content which can be used to construct an object node.
+ *
+ * 2. Insertable content which is an unhydrated object node.
+ *
+ * 3. Union of 1 and 2.
+ *
+ * @privateRemarks TODO: consider separating these cases into different types.
+ *
+ * @public
+ */
+export type InsertableObjectFromSchemaRecord<T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>> = {
+    readonly [Property in keyof T]: InsertableTreeFieldFromImplicitField<T[Property]>;
+};
+export declare function setField(field: FlexTreeField, simpleFieldSchema: FieldSchema, value: InsertableContent): void;
+type ObjectNodeSchema<TName extends string = string, T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema> = RestrictiveReadonlyRecord<string, ImplicitFieldSchema>, ImplicitlyConstructable extends boolean = boolean> = TreeNodeSchemaClass<TName, NodeKind.Object, TreeNode & WithType<TName>, InsertableObjectFromSchemaRecord<T>, ImplicitlyConstructable, T>;
+/**
+ * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
+ *
+ * @param name - Unique identifier for this schema within this factory's scope.
+ * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
+ */
+export declare function objectSchema<TName extends string, const T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>, const ImplicitlyConstructable extends boolean>(base: ObjectNodeSchema<TName, T, ImplicitlyConstructable>): TreeNodeSchemaClass<TName, NodeKind.Object, TreeObjectNode<T, TName>, object & InsertableObjectFromSchemaRecord<T>, true, T>;
+/**
+ * The implementation of an object node created by {@link createRawNode}.
+ */
+export declare class RawObjectNode<TSchema extends FlexObjectNodeSchema, TContent extends object> extends RawTreeNode<TSchema, TContent> implements FlexTreeObjectNode {
+    get localNodeKey(): LocalNodeKey | undefined;
+}
+export {};
+//# sourceMappingURL=objectNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objectNode.d.ts","sourceRoot":"","sources":["../../src/simple-tree/objectNode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAGN,oBAAoB,EACpB,aAAa,EAEb,kBAAkB,EAGlB,YAAY,EAEZ,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACN,iBAAiB,EAIjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,QAAQ,EACR,mBAAmB,EACnB,mBAAmB,EACnB,QAAQ,EAIR,0BAA0B,EAC1B,oCAAoC,EACpC,WAAW,EAEX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,yBAAyB,EAAQ,MAAM,kBAAkB,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAY,MAAM,cAAc,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CACjC,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAC7D;IACH,CAAC,UAAU,QAAQ,IAAI,MAAM,CAAC,GAAG,0BAA0B,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CACxE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CACzB,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,EAChE,QAAQ,SAAS,MAAM,GAAG,MAAM,IAC7B,QAAQ,GAAG,sBAAsB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gCAAgC,CAC3C,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,IAC7D;IACH,QAAQ,EAAE,QAAQ,IAAI,MAAM,CAAC,GAAG,oCAAoC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;CACjF,CAAC;AAgHF,wBAAgB,QAAQ,CACvB,KAAK,EAAE,aAAa,EACpB,iBAAiB,EAAE,WAAW,EAC9B,KAAK,EAAE,iBAAiB,GACtB,IAAI,CAiBN;AAED,KAAK,gBAAgB,CACpB,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,yBAAyB,CAC3F,MAAM,EACN,mBAAmB,CACnB,EACD,uBAAuB,SAAS,OAAO,GAAG,OAAO,IAC9C,mBAAmB,CACtB,KAAK,EACL,QAAQ,CAAC,MAAM,EACf,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,EAC1B,gCAAgC,CAAC,CAAC,CAAC,EACnC,uBAAuB,EACvB,CAAC,CACD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAC3B,KAAK,SAAS,MAAM,EACpB,KAAK,CAAC,CAAC,SAAS,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,CAAC,EACtE,KAAK,CAAC,uBAAuB,SAAS,OAAO,EAC5C,IAAI,EAAE,gBAAgB,CAAC,KAAK,EAAE,CAAC,EAAE,uBAAuB,CAAC,gIAqG1D;AAID;;GAEG;AACH,qBAAa,aAAa,CAAC,OAAO,SAAS,oBAAoB,EAAE,QAAQ,SAAS,MAAM,CACvF,SAAQ,WAAW,CAAC,OAAO,EAAE,QAAQ,CACrC,YAAW,kBAAkB;IAE7B,IAAW,YAAY,IAAI,YAAY,GAAG,SAAS,CAElD;CACD"}

package/lib/simple-tree/objectNode.js

@@ -0,0 +1,236 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { assert } from "@fluidframework/core-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { FieldKinds, FlexObjectNodeSchema, isFlexTreeNode, } from "../feature-libraries/index.js";
+import { getProxyForField, markContentType, prepareContentForInsert, } from "./proxies.js";
+import { getFlexNode, setFlexNode } from "./proxyBinding.js";
+import { getStoredKey, getExplicitStoredKey, normalizeFieldSchema, } from "./schemaTypes.js";
+import { cursorFromNodeData } from "./toMapTree.js";
+import { fail } from "../util/index.js";
+import { getFlexSchema } from "./toFlexSchema.js";
+import { RawTreeNode, rawError } from "./rawNode.js";
+/**
+ * Caches the mappings from view keys to stored keys for the provided object field schemas in {@link simpleKeyToFlexKeyCache}.
+ */
+function createFlexKeyMapping(fields) {
+    const keyMap = new Map();
+    for (const [viewKey, fieldSchema] of Object.entries(fields)) {
+        const storedKey = getStoredKey(viewKey, fieldSchema);
+        keyMap.set(viewKey, { storedKey, schema: normalizeFieldSchema(fieldSchema) });
+    }
+    return keyMap;
+}
+/**
+ * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
+ * Otherwise setting of unexpected properties will error.
+ * TODO: consider implementing this using `Object.preventExtension` instead.
+ * @param customTargetObject - Target object of the proxy.
+ * If not provided `{}` is used for the target.
+ */
+function createProxyHandler(flexKeyMap, allowAdditionalProperties) {
+    // To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an object with the same
+    // prototype as an object literal '{}'.  This is because 'deepEquals' uses 'Object.getPrototypeOf'
+    // as a way to quickly reject objects with different prototype chains.
+    //
+    // (Note that the prototype of an object literal appears as '[Object: null prototype] {}', not because
+    // the prototype is null, but because the prototype object itself has a null prototype.)
+    // TODO: Although the target is an object literal, it's still worthwhile to try experimenting with
+    // a dispatch object to see if it improves performance.
+    const handler = {
+        get(target, viewKey, proxy) {
+            const fieldInfo = flexKeyMap.get(viewKey);
+            if (fieldInfo !== undefined) {
+                const field = getFlexNode(proxy).tryGetField(fieldInfo.storedKey);
+                return field === undefined ? undefined : getProxyForField(field);
+            }
+            // Pass the proxy as the receiver here, so that any methods on the prototype receive `proxy` as `this`.
+            return Reflect.get(target, viewKey, proxy);
+        },
+        set(target, viewKey, value, proxy) {
+            const fieldInfo = flexKeyMap.get(viewKey);
+            if (fieldInfo === undefined) {
+                return allowAdditionalProperties ? Reflect.set(target, viewKey, value) : false;
+            }
+            const flexNode = getFlexNode(proxy);
+            const field = flexNode.getBoxed(fieldInfo.storedKey);
+            setField(field, fieldInfo.schema, value);
+            return true;
+        },
+        has: (target, viewKey) => {
+            return (flexKeyMap.has(viewKey) ||
+                (allowAdditionalProperties ? Reflect.has(target, viewKey) : false));
+        },
+        ownKeys: (target) => {
+            return [
+                ...flexKeyMap.keys(),
+                ...(allowAdditionalProperties ? Reflect.ownKeys(target) : []),
+            ];
+        },
+        getOwnPropertyDescriptor: (target, viewKey) => {
+            const fieldInfo = flexKeyMap.get(viewKey);
+            if (fieldInfo === undefined) {
+                return allowAdditionalProperties
+                    ? Reflect.getOwnPropertyDescriptor(target, viewKey)
+                    : undefined;
+            }
+            // For some reason, the getOwnPropertyDescriptor is not passed in the receiver, so use a weak map.
+            // If a refactoring is done to associated flex tree data with the target not the proxy, this extra map could be removed,
+            // and the design would be more compatible with proxyless nodes.
+            const proxy = targetToProxy.get(target) ?? fail("missing proxy");
+            const field = getFlexNode(proxy).tryGetField(fieldInfo.storedKey);
+            const p = {
+                value: field === undefined ? undefined : getProxyForField(field),
+                writable: true,
+                // Report empty fields as own properties so they shadow inherited properties (even when empty) to match TypeScript typing.
+                // Make empty fields not enumerable so they get skipped when iterating over an object to better align with
+                // JSON and deep equals with JSON compatible object (which can't have undefined fields).
+                enumerable: field !== undefined,
+                configurable: true, // Must be 'configurable' if property is absent from proxy target.
+            };
+            return p;
+        },
+    };
+    return handler;
+}
+export function setField(field, simpleFieldSchema, value) {
+    switch (field.schema.kind) {
+        case FieldKinds.required:
+        case FieldKinds.optional: {
+            const typedField = field;
+            const content = prepareContentForInsert(value, field.context.forest);
+            const cursor = cursorFromNodeData(content, simpleFieldSchema.allowedTypes);
+            typedField.content = cursor;
+            break;
+        }
+        default:
+            fail("invalid FieldKind");
+    }
+}
+/**
+ * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.
+ *
+ * @param name - Unique identifier for this schema within this factory's scope.
+ * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.
+ */
+export function objectSchema(base) {
+    // Ensure no collisions between final set of view keys, and final set of stored keys (including those
+    // implicitly derived from view keys)
+    assertUniqueKeys(base.identifier, base.info);
+    // Performance optimization: cache view key => stored key and schema.
+    const flexKeyMap = createFlexKeyMapping(base.info);
+    // Used to ensure we only use one most derived schema type.
+    // The type "Function" is used by "Object.constructor" and this matches it.
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    let constructorCached;
+    let handler;
+    let customizable;
+    class CustomObjectNode extends base {
+        constructor(input) {
+            super(input);
+            // Differentiate between the following cases:
+            //
+            // Case 1: Direct construction (POJO emulation)
+            //
+            //     const Foo = schemaFactory.object("Foo", {bar: schemaFactory.number});
+            //
+            //     assert.deepEqual(new Foo({ bar: 42 }), { bar: 42 },
+            //		   "Prototype chain equivalent to POJO.");
+            //
+            // Case 2: Subclass construction (Customizable Object)
+            //
+            // 	   class Foo extends schemaFactory.object("Foo", {bar: schemaFactory.number}) {}
+            //
+            // 	   assert.notDeepEqual(new Foo({ bar: 42 }), { bar: 42 },
+            // 	       "Subclass prototype chain differs from POJO.");
+            //
+            // In Case 1 (POJO emulation), the prototype chain match '{}' (proxyTarget = undefined)
+            // In Case 2 (Customizable Object), the prototype chain include the user's subclass (proxyTarget = this)
+            if (constructorCached === undefined) {
+                // One time initialization that required knowing the most derived type (from this.constructor) and thus has to be lazy.
+                constructorCached = this.constructor;
+                customizable = this.constructor !== CustomObjectNode;
+                handler ?? (handler = createProxyHandler(flexKeyMap, customizable));
+                // First run, do extra validation.
+                // TODO: provide a way for TreeConfiguration to trigger this same validation to ensure it gets run early.
+                // Scan for shadowing inherited members which won't work, but stop scan early to allow shadowing built in (which seems to work ok).
+                {
+                    let prototype = this.constructor.prototype;
+                    // There isn't a clear cleaner way to author this loop.
+                    while (prototype !== CustomObjectNode.prototype) {
+                        for (const [key] of flexKeyMap) {
+                            if (
+                            // constructor is a special case, since one is built in on the derived type, and shadowing it works fine since we only use it before fields are applied.
+                            key !== "constructor" &&
+                                Reflect.getOwnPropertyDescriptor(prototype, key) !== undefined) {
+                                throw new UsageError(`Schema ${base.identifier} defines an inherited property ${key.toString()} which shadows a field. Since fields are exposed as own properties, this shadowing will not work, and is an error.`);
+                            }
+                        }
+                        // Since this stops at CustomObjectNode, it should never see a null prototype, so this case is safe.
+                        // Additionally, if the prototype chain is ever messed up such that CustomObjectNode is not in it,
+                        // the null that would show up here does at least ensure this code throws instead of hanging.
+                        prototype = Reflect.getPrototypeOf(prototype);
+                    }
+                }
+            }
+            assert(constructorCached === this.constructor, 0x918 /* Node instantiated from multiple bases. */);
+            const proxyTarget = customizable ? this : {};
+            const flexSchema = getFlexSchema(this.constructor);
+            assert(flexSchema instanceof FlexObjectNodeSchema, 0x919 /* invalid flex schema */);
+            const flexNode = isFlexTreeNode(input)
+                ? input
+                : new RawObjectNode(flexSchema, copyContent(flexSchema.name, input));
+            const proxy = new Proxy(proxyTarget, handler);
+            targetToProxy.set(proxyTarget, proxy);
+            setFlexNode(proxy, flexNode);
+            return proxy;
+        }
+    }
+    return CustomObjectNode;
+}
+const targetToProxy = new WeakMap();
+/**
+ * The implementation of an object node created by {@link createRawNode}.
+ */
+export class RawObjectNode extends RawTreeNode {
+    get localNodeKey() {
+        throw rawError("Reading local node keys");
+    }
+}
+/**
+ * Ensures that the set of view keys in the schema is unique.
+ * Also ensure that the final set of stored keys (including those implicitly derived from view keys) is unique.
+ * @throws Throws a `UsageError` if either of the key uniqueness invariants is violated.
+ */
+function assertUniqueKeys(schemaName, fields) {
+    // Verify that there are no duplicates among the explicitly specified stored keys.
+    const explicitStoredKeys = new Set();
+    for (const schema of Object.values(fields)) {
+        const storedKey = getExplicitStoredKey(schema);
+        if (storedKey === undefined) {
+            continue;
+        }
+        if (explicitStoredKeys.has(storedKey)) {
+            throw new UsageError(`Duplicate stored key "${storedKey}" in schema "${schemaName}". Stored keys must be unique within an object schema.`);
+        }
+        explicitStoredKeys.add(storedKey);
+    }
+    // Verify that there are no duplicates among the derived
+    // (including those implicitly derived from view keys) stored keys.
+    const derivedStoredKeys = new Set();
+    for (const [viewKey, schema] of Object.entries(fields)) {
+        const storedKey = getStoredKey(viewKey, schema);
+        if (derivedStoredKeys.has(storedKey)) {
+            throw new UsageError(`Stored key "${storedKey}" in schema "${schemaName}" conflicts with a property key of the same name, which is not overridden by a stored key. The final set of stored keys in an object schema must be unique.`);
+        }
+        derivedStoredKeys.add(storedKey);
+    }
+}
+function copyContent(typeName, content) {
+    const copy = { ...content };
+    markContentType(typeName, copy);
+    return copy;
+}
+//# sourceMappingURL=objectNode.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objectNode.js","sourceRoot":"","sources":["../../src/simple-tree/objectNode.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/internal\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport { FieldKey, TreeNodeSchemaIdentifier } from \"../core/index.js\";\nimport {\n\tFieldKinds,\n\tFlexAllowedTypes,\n\tFlexObjectNodeSchema,\n\tFlexTreeField,\n\tFlexTreeNode,\n\tFlexTreeObjectNode,\n\tFlexTreeOptionalField,\n\tFlexTreeRequiredField,\n\tLocalNodeKey,\n\tisFlexTreeNode,\n} from \"../feature-libraries/index.js\";\nimport {\n\tInsertableContent,\n\tgetProxyForField,\n\tmarkContentType,\n\tprepareContentForInsert,\n} from \"./proxies.js\";\nimport { getFlexNode, setFlexNode } from \"./proxyBinding.js\";\nimport {\n\tNodeKind,\n\tImplicitFieldSchema,\n\tTreeNodeSchemaClass,\n\tWithType,\n\tTreeNodeSchema,\n\tgetStoredKey,\n\tgetExplicitStoredKey,\n\tTreeFieldFromImplicitField,\n\tInsertableTreeFieldFromImplicitField,\n\tFieldSchema,\n\tnormalizeFieldSchema,\n} from \"./schemaTypes.js\";\nimport { cursorFromNodeData } from \"./toMapTree.js\";\nimport { TreeNode } from \"./types.js\";\nimport { RestrictiveReadonlyRecord, fail } from \"../util/index.js\";\nimport { getFlexSchema } from \"./toFlexSchema.js\";\nimport { RawTreeNode, rawError } from \"./rawNode.js\";\n\n/**\n * Helper used to produce types for object nodes.\n * @public\n */\nexport type ObjectFromSchemaRecord<\n\tT extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n> = {\n\t-readonly [Property in keyof T]: TreeFieldFromImplicitField<T[Property]>;\n};\n\n/**\n * A {@link TreeNode} which modules a JavaScript object.\n * @remarks\n * Object nodes consist of a type which specifies which {@link TreeNodeSchema} they use (see {@link TreeNodeApi.schema}), and a collections of fields, each with a distinct `key` and its own {@link FieldSchema} defining what can be placed under that key.\n *\n * All fields on an object node are exposed as own properties with string keys.\n * Non-empty fields are enumerable and empty optional fields are non-enumerable own properties with the value `undefined`.\n * No other own `own` or `enumerable` properties are included on object nodes unless the user of the node manually adds custom session only state.\n * This allows a majority of general purpose JavaScript object processing operations (like `for...in`, `Reflect.ownKeys()` and `Object.entries()`) to enumerate all the children.\n * @public\n */\nexport type TreeObjectNode<\n\tT extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n\tTypeName extends string = string,\n> = TreeNode & ObjectFromSchemaRecord<T> & WithType<TypeName>;\n\n/**\n * Helper used to produce types for:\n *\n * 1. Insertable content which can be used to construct an object node.\n *\n * 2. Insertable content which is an unhydrated object node.\n *\n * 3. Union of 1 and 2.\n *\n * @privateRemarks TODO: consider separating these cases into different types.\n *\n * @public\n */\nexport type InsertableObjectFromSchemaRecord<\n\tT extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n> = {\n\treadonly [Property in keyof T]: InsertableTreeFieldFromImplicitField<T[Property]>;\n};\n\n/**\n * Maps from simple field keys (\"view\" keys) to information about the field.\n *\n * @remarks\n * A missing entry for a given view key indicates that no such field exists.\n * Keys with symbols are currently never used, but allowed to make lookups on non-field things\n * (returning undefined) easier.\n */\ntype SimpleKeyMap = Map<string | symbol, { storedKey: FieldKey; schema: FieldSchema }>;\n\n/**\n * Caches the mappings from view keys to stored keys for the provided object field schemas in {@link simpleKeyToFlexKeyCache}.\n */\nfunction createFlexKeyMapping(fields: Record<string, ImplicitFieldSchema>): SimpleKeyMap {\n\tconst keyMap: SimpleKeyMap = new Map();\n\tfor (const [viewKey, fieldSchema] of Object.entries(fields)) {\n\t\tconst storedKey = getStoredKey(viewKey, fieldSchema);\n\t\tkeyMap.set(viewKey, { storedKey, schema: normalizeFieldSchema(fieldSchema) });\n\t}\n\n\treturn keyMap;\n}\n\n/**\n * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.\n * Otherwise setting of unexpected properties will error.\n * TODO: consider implementing this using `Object.preventExtension` instead.\n * @param customTargetObject - Target object of the proxy.\n * If not provided `{}` is used for the target.\n */\nfunction createProxyHandler(\n\tflexKeyMap: SimpleKeyMap,\n\tallowAdditionalProperties: boolean,\n): ProxyHandler<TreeNode> {\n\t// To satisfy 'deepEquals' level scrutiny, the target of the proxy must be an object with the same\n\t// prototype as an object literal '{}'.  This is because 'deepEquals' uses 'Object.getPrototypeOf'\n\t// as a way to quickly reject objects with different prototype chains.\n\t//\n\t// (Note that the prototype of an object literal appears as '[Object: null prototype] {}', not because\n\t// the prototype is null, but because the prototype object itself has a null prototype.)\n\n\t// TODO: Although the target is an object literal, it's still worthwhile to try experimenting with\n\t// a dispatch object to see if it improves performance.\n\tconst handler: ProxyHandler<TreeNode> = {\n\t\tget(target, viewKey, proxy): unknown {\n\t\t\tconst fieldInfo = flexKeyMap.get(viewKey);\n\n\t\t\tif (fieldInfo !== undefined) {\n\t\t\t\tconst field = getFlexNode(proxy).tryGetField(fieldInfo.storedKey);\n\t\t\t\treturn field === undefined ? undefined : getProxyForField(field);\n\t\t\t}\n\n\t\t\t// Pass the proxy as the receiver here, so that any methods on the prototype receive `proxy` as `this`.\n\t\t\treturn Reflect.get(target, viewKey, proxy);\n\t\t},\n\t\tset(target, viewKey, value: InsertableContent, proxy) {\n\t\t\tconst fieldInfo = flexKeyMap.get(viewKey);\n\t\t\tif (fieldInfo === undefined) {\n\t\t\t\treturn allowAdditionalProperties ? Reflect.set(target, viewKey, value) : false;\n\t\t\t}\n\n\t\t\tconst flexNode = getFlexNode(proxy);\n\t\t\tconst field = flexNode.getBoxed(fieldInfo.storedKey);\n\t\t\tsetField(field, fieldInfo.schema, value);\n\n\t\t\treturn true;\n\t\t},\n\t\thas: (target, viewKey) => {\n\t\t\treturn (\n\t\t\t\tflexKeyMap.has(viewKey) ||\n\t\t\t\t(allowAdditionalProperties ? Reflect.has(target, viewKey) : false)\n\t\t\t);\n\t\t},\n\t\townKeys: (target) => {\n\t\t\treturn [\n\t\t\t\t...flexKeyMap.keys(),\n\t\t\t\t...(allowAdditionalProperties ? Reflect.ownKeys(target) : []),\n\t\t\t];\n\t\t},\n\t\tgetOwnPropertyDescriptor: (target, viewKey) => {\n\t\t\tconst fieldInfo = flexKeyMap.get(viewKey);\n\n\t\t\tif (fieldInfo === undefined) {\n\t\t\t\treturn allowAdditionalProperties\n\t\t\t\t\t? Reflect.getOwnPropertyDescriptor(target, viewKey)\n\t\t\t\t\t: undefined;\n\t\t\t}\n\n\t\t\t// For some reason, the getOwnPropertyDescriptor is not passed in the receiver, so use a weak map.\n\t\t\t// If a refactoring is done to associated flex tree data with the target not the proxy, this extra map could be removed,\n\t\t\t// and the design would be more compatible with proxyless nodes.\n\t\t\tconst proxy = targetToProxy.get(target) ?? fail(\"missing proxy\");\n\t\t\tconst field = getFlexNode(proxy).tryGetField(fieldInfo.storedKey);\n\n\t\t\tconst p: PropertyDescriptor = {\n\t\t\t\tvalue: field === undefined ? undefined : getProxyForField(field),\n\t\t\t\twritable: true,\n\t\t\t\t// Report empty fields as own properties so they shadow inherited properties (even when empty) to match TypeScript typing.\n\t\t\t\t// Make empty fields not enumerable so they get skipped when iterating over an object to better align with\n\t\t\t\t// JSON and deep equals with JSON compatible object (which can't have undefined fields).\n\t\t\t\tenumerable: field !== undefined,\n\t\t\t\tconfigurable: true, // Must be 'configurable' if property is absent from proxy target.\n\t\t\t};\n\n\t\t\treturn p;\n\t\t},\n\t};\n\treturn handler;\n}\n\nexport function setField(\n\tfield: FlexTreeField,\n\tsimpleFieldSchema: FieldSchema,\n\tvalue: InsertableContent,\n): void {\n\tswitch (field.schema.kind) {\n\t\tcase FieldKinds.required:\n\t\tcase FieldKinds.optional: {\n\t\t\tconst typedField = field as\n\t\t\t\t| FlexTreeRequiredField<FlexAllowedTypes>\n\t\t\t\t| FlexTreeOptionalField<FlexAllowedTypes>;\n\n\t\t\tconst content = prepareContentForInsert(value, field.context.forest);\n\t\t\tconst cursor = cursorFromNodeData(content, simpleFieldSchema.allowedTypes);\n\t\t\ttypedField.content = cursor;\n\t\t\tbreak;\n\t\t}\n\n\t\tdefault:\n\t\t\tfail(\"invalid FieldKind\");\n\t}\n}\n\ntype ObjectNodeSchema<\n\tTName extends string = string,\n\tT extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema> = RestrictiveReadonlyRecord<\n\t\tstring,\n\t\tImplicitFieldSchema\n\t>,\n\tImplicitlyConstructable extends boolean = boolean,\n> = TreeNodeSchemaClass<\n\tTName,\n\tNodeKind.Object,\n\tTreeNode & WithType<TName>,\n\tInsertableObjectFromSchemaRecord<T>,\n\tImplicitlyConstructable,\n\tT\n>;\n\n/**\n * Define a {@link TreeNodeSchema} for a {@link TreeObjectNode}.\n *\n * @param name - Unique identifier for this schema within this factory's scope.\n * @param fields - Schema for fields of the object node's schema. Defines what children can be placed under each key.\n */\nexport function objectSchema<\n\tTName extends string,\n\tconst T extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n\tconst ImplicitlyConstructable extends boolean,\n>(base: ObjectNodeSchema<TName, T, ImplicitlyConstructable>) {\n\t// Ensure no collisions between final set of view keys, and final set of stored keys (including those\n\t// implicitly derived from view keys)\n\tassertUniqueKeys(base.identifier, base.info);\n\n\t// Performance optimization: cache view key => stored key and schema.\n\tconst flexKeyMap: SimpleKeyMap = createFlexKeyMapping(base.info);\n\n\t// Used to ensure we only use one most derived schema type.\n\t// The type \"Function\" is used by \"Object.constructor\" and this matches it.\n\t// eslint-disable-next-line @typescript-eslint/ban-types\n\tlet constructorCached: Function;\n\n\tlet handler: ProxyHandler<object>;\n\tlet customizable: boolean;\n\n\tclass CustomObjectNode extends base {\n\t\tpublic constructor(input: InsertableObjectFromSchemaRecord<T>) {\n\t\t\tsuper(input);\n\n\t\t\t// Differentiate between the following cases:\n\t\t\t//\n\t\t\t// Case 1: Direct construction (POJO emulation)\n\t\t\t//\n\t\t\t//     const Foo = schemaFactory.object(\"Foo\", {bar: schemaFactory.number});\n\t\t\t//\n\t\t\t//     assert.deepEqual(new Foo({ bar: 42 }), { bar: 42 },\n\t\t\t//\t\t   \"Prototype chain equivalent to POJO.\");\n\t\t\t//\n\t\t\t// Case 2: Subclass construction (Customizable Object)\n\t\t\t//\n\t\t\t// \t   class Foo extends schemaFactory.object(\"Foo\", {bar: schemaFactory.number}) {}\n\t\t\t//\n\t\t\t// \t   assert.notDeepEqual(new Foo({ bar: 42 }), { bar: 42 },\n\t\t\t// \t       \"Subclass prototype chain differs from POJO.\");\n\t\t\t//\n\t\t\t// In Case 1 (POJO emulation), the prototype chain match '{}' (proxyTarget = undefined)\n\t\t\t// In Case 2 (Customizable Object), the prototype chain include the user's subclass (proxyTarget = this)\n\n\t\t\tif (constructorCached === undefined) {\n\t\t\t\t// One time initialization that required knowing the most derived type (from this.constructor) and thus has to be lazy.\n\t\t\t\tconstructorCached = this.constructor;\n\t\t\t\tcustomizable = this.constructor !== CustomObjectNode;\n\t\t\t\thandler ??= createProxyHandler(flexKeyMap, customizable);\n\n\t\t\t\t// First run, do extra validation.\n\t\t\t\t// TODO: provide a way for TreeConfiguration to trigger this same validation to ensure it gets run early.\n\t\t\t\t// Scan for shadowing inherited members which won't work, but stop scan early to allow shadowing built in (which seems to work ok).\n\t\t\t\t{\n\t\t\t\t\tlet prototype: object = this.constructor.prototype;\n\t\t\t\t\t// There isn't a clear cleaner way to author this loop.\n\t\t\t\t\twhile (prototype !== CustomObjectNode.prototype) {\n\t\t\t\t\t\tfor (const [key] of flexKeyMap) {\n\t\t\t\t\t\t\tif (\n\t\t\t\t\t\t\t\t// constructor is a special case, since one is built in on the derived type, and shadowing it works fine since we only use it before fields are applied.\n\t\t\t\t\t\t\t\tkey !== \"constructor\" &&\n\t\t\t\t\t\t\t\tReflect.getOwnPropertyDescriptor(prototype, key) !== undefined\n\t\t\t\t\t\t\t) {\n\t\t\t\t\t\t\t\tthrow new UsageError(\n\t\t\t\t\t\t\t\t\t`Schema ${\n\t\t\t\t\t\t\t\t\t\tbase.identifier\n\t\t\t\t\t\t\t\t\t} defines an inherited property ${key.toString()} which shadows a field. Since fields are exposed as own properties, this shadowing will not work, and is an error.`,\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\t// Since this stops at CustomObjectNode, it should never see a null prototype, so this case is safe.\n\t\t\t\t\t\t// Additionally, if the prototype chain is ever messed up such that CustomObjectNode is not in it,\n\t\t\t\t\t\t// the null that would show up here does at least ensure this code throws instead of hanging.\n\t\t\t\t\t\tprototype = Reflect.getPrototypeOf(prototype) as object;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tassert(\n\t\t\t\tconstructorCached === this.constructor,\n\t\t\t\t0x918 /* Node instantiated from multiple bases. */,\n\t\t\t);\n\n\t\t\tconst proxyTarget = customizable ? this : {};\n\n\t\t\tconst flexSchema = getFlexSchema(this.constructor as TreeNodeSchema);\n\t\t\tassert(flexSchema instanceof FlexObjectNodeSchema, 0x919 /* invalid flex schema */);\n\t\t\tconst flexNode: FlexTreeNode = isFlexTreeNode(input)\n\t\t\t\t? input\n\t\t\t\t: new RawObjectNode(flexSchema, copyContent(flexSchema.name, input) as object);\n\n\t\t\tconst proxy = new Proxy(proxyTarget, handler) as CustomObjectNode;\n\t\t\ttargetToProxy.set(proxyTarget, proxy);\n\t\t\tsetFlexNode(proxy, flexNode);\n\t\t\treturn proxy;\n\t\t}\n\t}\n\n\treturn CustomObjectNode as TreeNodeSchemaClass<\n\t\tTName,\n\t\tNodeKind.Object,\n\t\tTreeObjectNode<T, TName>,\n\t\tobject & InsertableObjectFromSchemaRecord<T>,\n\t\ttrue,\n\t\tT\n\t>;\n}\n\nconst targetToProxy: WeakMap<object, TreeNode> = new WeakMap();\n\n/**\n * The implementation of an object node created by {@link createRawNode}.\n */\nexport class RawObjectNode<TSchema extends FlexObjectNodeSchema, TContent extends object>\n\textends RawTreeNode<TSchema, TContent>\n\timplements FlexTreeObjectNode\n{\n\tpublic get localNodeKey(): LocalNodeKey | undefined {\n\t\tthrow rawError(\"Reading local node keys\");\n\t}\n}\n\n/**\n * Ensures that the set of view keys in the schema is unique.\n * Also ensure that the final set of stored keys (including those implicitly derived from view keys) is unique.\n * @throws Throws a `UsageError` if either of the key uniqueness invariants is violated.\n */\nfunction assertUniqueKeys<\n\tconst Name extends number | string,\n\tconst Fields extends RestrictiveReadonlyRecord<string, ImplicitFieldSchema>,\n>(schemaName: Name, fields: Fields): void {\n\t// Verify that there are no duplicates among the explicitly specified stored keys.\n\tconst explicitStoredKeys = new Set<string>();\n\tfor (const schema of Object.values(fields)) {\n\t\tconst storedKey = getExplicitStoredKey(schema);\n\t\tif (storedKey === undefined) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (explicitStoredKeys.has(storedKey)) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Duplicate stored key \"${storedKey}\" in schema \"${schemaName}\". Stored keys must be unique within an object schema.`,\n\t\t\t);\n\t\t}\n\t\texplicitStoredKeys.add(storedKey);\n\t}\n\n\t// Verify that there are no duplicates among the derived\n\t// (including those implicitly derived from view keys) stored keys.\n\tconst derivedStoredKeys = new Set<string>();\n\tfor (const [viewKey, schema] of Object.entries(fields)) {\n\t\tconst storedKey = getStoredKey(viewKey, schema);\n\t\tif (derivedStoredKeys.has(storedKey)) {\n\t\t\tthrow new UsageError(\n\t\t\t\t`Stored key \"${storedKey}\" in schema \"${schemaName}\" conflicts with a property key of the same name, which is not overridden by a stored key. The final set of stored keys in an object schema must be unique.`,\n\t\t\t);\n\t\t}\n\t\tderivedStoredKeys.add(storedKey);\n\t}\n}\n\nfunction copyContent<T extends object>(typeName: TreeNodeSchemaIdentifier, content: T): T {\n\tconst copy = { ...content };\n\tmarkContentType(typeName, copy);\n\treturn copy;\n}\n"]}

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

@@ -3,11 +3,9 @@
  * Licensed under the MIT License.
  */
 import { IFluidHandle } from "@fluidframework/core-interfaces";
-import { FlexAllowedTypes, FlexObjectNodeSchema, FlexTreeNodeSchema, FlexTreeSequenceField, FlexTreeNode, FlexTreeField } from "../feature-libraries/index.js";
-import { TreeValue } from "../core/index.js";
-import { type TreeNodeSchema as TreeNodeSchemaClass, type InsertableTypedNode } from "./schemaTypes.js";
-import { TreeArrayNode } from "./treeArrayNode.js";
-import { Unhydrated, TreeNode } from "./types.js";
+import { IForestSubscription, TreeNodeSchemaIdentifier, TreeValue, UpPath } from "../core/index.js";
+import { FlexTreeField, FlexTreeNode } from "../feature-libraries/index.js";
+import { TreeNode, Unhydrated } from "./types.js";
 /**
  * Detects if the given 'candidate' is a TreeNode.
  *
@@ -27,68 +25,23 @@ export declare function isTreeNode(candidate: unknown): candidate is TreeNode |
  * Retrieve the associated proxy for the given field.
  * */
 export declare function getProxyForField(field: FlexTreeField): TreeNode | TreeValue | undefined;
-/**
- * A symbol for storing TreeNodeSchemaClass on FlexTreeNode's schema.
- */
-export declare const simpleSchemaSymbol: unique symbol;
-export declare function getClassSchema(schema: FlexTreeNodeSchema): TreeNodeSchemaClass | undefined;
 export declare function getOrCreateNodeProxy(flexNode: FlexTreeNode): TreeNode | TreeValue;
 /**
- * @param flexNode - underlying tree node which this proxy should wrap.
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided an empty collection of the relevant type is used for the target and a separate object created to dispatch methods.
- * If provided, the customTargetObject will be used as both the dispatch object and the proxy target, and therefor must provide needed functionality depending on the schema kind.
- */
-export declare function createNodeProxy(flexNode: FlexTreeNode, allowAdditionalProperties: boolean, targetObject?: object): TreeNode | TreeValue;
-/**
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `{}` is used for the target.
+ * Records any proxies in the given content tree and does the necessary bookkeeping to ensure they are synchronized with subsequent reads of the tree.
+ * @remarks If the content tree contains any proxies, this function must be called just prior to inserting the content into the tree.
+ * Specifically, no other content may be inserted into the tree between the invocation of this function and the insertion of `content`.
+ * The insertion of `content` must occur or else this function will cause memory leaks.
+ * @param content - the tree of content to be inserted, of which any of its object/map/array nodes might be a proxy
+ * @param anchors - the {@link AnchorSet} for the tree
+ * @returns The content after having all proxies replaced inline with plain javascript objects.
+ * See {@link extractFactoryContent} for more details.
  */
-export declare function createObjectProxy<TSchema extends FlexObjectNodeSchema>(schema: TSchema, allowAdditionalProperties: boolean, targetObject?: object): TreeNode;
-/**
- * Given a array node proxy, returns its underlying LazySequence field.
- */
-export declare const getSequenceField: <TTypes extends FlexAllowedTypes>(arrayNode: TreeArrayNode) => FlexTreeSequenceField<TTypes>;
-/**
- * PropertyDescriptorMap used to build the prototype for our array node dispatch object.
- */
-export declare const arrayNodePrototypeProperties: PropertyDescriptorMap;
-export declare const mapStaticDispatchMap: PropertyDescriptorMap;
-/**
- * Create a proxy to a {@link TreeObjectNode} that is backed by a raw object node (see {@link createRawNode}).
- * @param schema - the schema of the object node
- * @param content - the content to be stored in the raw node.
- * A copy of content is stored, the input `content` is not modified and can be safely reused in another call to {@link createRawObjectProxy}.
- * @param allowAdditionalProperties - If true, setting of unexpected properties will be forwarded to the target object.
- * Otherwise setting of unexpected properties will error.
- * @param customTargetObject - Target object of the proxy.
- * If not provided `{}` is used for the target.
- * @remarks
- * Because this proxy is backed by a raw node, it has the same limitations as the node created by {@link createRawNode}.
- * Most of its properties and methods will error if read/called.
- */
-export declare function createRawNodeProxy(schema: FlexTreeNodeSchema, content: InsertableTypedNode<TreeNodeSchemaClass> & object, allowAdditionalProperties: boolean, target?: object): Unhydrated<TreeNode>;
-type ProxyHydrator = (flexNode: FlexTreeNode | undefined) => void;
-/** The result returned by {@link extractFactoryContent} and its related helpers. */
-interface ExtractedFactoryContent<out T = FactoryContent> {
-    /** The content with the factory subtrees replaced. */
-    readonly content: T;
-    /**
-     * A function which walks all factory-created object that underwent replacement/extraction.
-     * Before hydration, those objects are unusable (see {@link createRawObjectProxy}).
-     * However, after the content is fully inserted into the tree the `hydrateProxies` function may be invoked in order to update the contents of these objects such that they become a mirror of the content in the tree.
-     * This must be done before any calls to {@link getOrCreateNodeProxy} so that the "edit node to proxy" mapping is correctly updated (see {@link setFlexNode}).
-     */
-    readonly hydrateProxies: ProxyHydrator;
-}
+export declare function prepareContentForInsert(content: InsertableContent, forest: IForestSubscription): FactoryContent;
 /**
  * Given a content tree that is to be inserted into the shared tree, replace all subtrees that were created by factories
  * (via {@link SharedTreeObjectFactory.create}) with the content that was passed to those factories.
  * @param content - the content being inserted which may be, and/or may contain, factory-created content
+ * @param onVisitProxy - an optional callback that will run for each proxy (i.e. object created by a factory) found in the inserted content
  * @param insertedAtIndex - if the content being inserted is array node content, this must be the index in the array node at which the content is being inserted
  * @returns the result of the content replacement and a {@link ExtractedFactoryContent.hydrateProxies} function which must be invoked if present.
  * @remarks
@@ -110,7 +63,10 @@ interface ExtractedFactoryContent<out T = FactoryContent> {
  * }
  * ```
  */
-export declare function extractFactoryContent(input: InsertableContent, insertedAtIndex?: number): ExtractedFactoryContent;
+export declare function extractFactoryContent(input: InsertableContent, visitProxies?: {
+    path: UpPath;
+    onVisitProxy: (path: UpPath, proxy: TreeNode) => void;
+}): FactoryContent;
 /**
  * Content which can be used to build a node.
  * @remarks
@@ -123,5 +79,8 @@ export type FactoryContent = IFluidHandle | string | number | boolean | null | R
  * Content which can be inserted into a tree.
  */
 export type InsertableContent = Unhydrated<TreeNode> | FactoryContent;
-export {};
+/**
+ * Brand `copy` with the type (under {@link typeNameSymbol}) to avoid ambiguity when inferring types from this data.
+ */
+export declare function markContentType(typeName: TreeNodeSchemaIdentifier, copy: object): void;
 //# sourceMappingURL=proxies.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"proxies.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxies.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"proxies.d.ts","sourceRoot":"","sources":["../../src/simple-tree/proxies.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAG/D,OAAO,EAEN,mBAAmB,EACnB,wBAAwB,EACxB,SAAS,EACT,MAAM,EACN,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAGN,aAAa,EACb,YAAY,EAIZ,MAAM,+BAA+B,CAAC;AAOvC,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,IAAI,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,CAE3F;AAED;;KAEK;AACL,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CA0CvF;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAejF;AAgBD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,mBAAmB,GACzB,cAAc,CAkBhB;AAgDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,iBAAiB,EACxB,YAAY,CAAC,EAAE;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACtD,GACC,cAAc,CA6ChB;AA0GD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACvB,YAAY,GACZ,MAAM,GACN,MAAM,GACN,OAAO,GAEP,IAAI,GACJ,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACtC,SAAS,iBAAiB,EAAE,GAC5B;IACA,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,iBAAiB;CACzC,CAAC;AAEL;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,cAAc,CAAC;AAEtE;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,wBAAwB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEtF"}