npm - @fluidframework/tree - Versions diffs - 2.11.0 → 2.12.0 - Mend

@fluidframework/tree 2.11.0 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (537) hide show

package/lib/simple-tree/api/tree.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.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 type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport type {\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\n\nimport {\n\ttype ImplicitFieldSchema,\n\ttype InsertableField,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype ReadableField,\n\ttype ReadSchema,\n\ttype TreeFieldFromImplicitField,\n\ttype UnsafeUnknownSchema,\n\tFieldKind,\n} from \"../schemaTypes.js\";\nimport { NodeKind, type TreeNodeSchema } from \"../core/index.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\nimport { LeafNodeSchema } from \"../leafNodeSchema.js\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { isObjectNodeSchema, type ObjectNodeSchema } from \"../objectNodeTypes.js\";\nimport { markSchemaMostDerived } from \"./schemaFactory.js\";\nimport { fail, getOrCreate } from \"../../util/index.js\";\nimport type { MakeNominal } from \"../../util/index.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\n/\n A tree from which a {@link TreeView} can be created.\n \n @privateRemarks\n * TODO:\n * Add stored key versions of {@link TreeAlpha.(exportVerbose:2)}, {@link TreeAlpha.(exportConcise:2)} and {@link TreeAlpha.exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * @system @sealed @public\n /\nexport interface ViewableTree {\n\t/\n\t Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t \n\t @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t \n\t Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t \n\t Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t \n\t \n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t \n\t Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t /\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n /\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/\n Options when constructing a tree view.\n * @public\n /\nexport interface ITreeConfigurationOptions {\n\t/\n\t If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t \n\t @defaultValue `false`.\n\t \n\t @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t /\n\tenableSchemaValidation?: boolean;\n\n\t/\n\t A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.\n\t * @defaultValue `false`.\n\t \n\t @remarks\n\t * When this is true, it ensures that the compile time type safety for data when constructing nodes is sufficient to ensure that the runtime behavior will not give node data ambiguity errors.\n\t \n\t This ensures that the canonical JSON-like representation of all unions in the tree are lossless and unambiguous.\n\t * This canonical JSON-like representation consists of arrays, plain old JavaScript objects with string keys, booleans, numbers (excluding NaN, -0 and infinities), strings, null and {@link @fluidframework/core-interfaces#IFluidHandle}s.\n\t * It is compatible with the node creation APIs (such as schema class constructors) and is also compatible with JSON assuming any IFluidHandles get special handling (since they are not JSON compatible).\n\t * Currently these cases can cause ambiguity in a union:\n\t \n\t - More than one ArrayNode type: it's impossible to tell which array type is intended in the case of empty arrays (`[]`).\n\t \n\t - More than one MapNode type: it's impossible to tell which map type is intended in the case of an empty map (`{}`).\n\t \n\t - Both a MapNode and an ArrayNode: this case is not a problem for the canonical JSON representation, but is an issue when constructing from an Iterable, which is supported for both MapNode and ArrayNode.\n\t \n\t - Both a MapNode and an ObjectNode: when the input is valid for the ObjectNode, the current parser always considers it ambiguous with being a MapNode.\n\t \n\t - ObjectNodes which have fields (required or optional) which include all required fields of another ObjectNode: currently each ObjectNode is differentiated by the presence of its required fields.\n\t \n\t This check is conservative: some complex cases may error if the current simple algorithm cannot show no ambiguity is possible.\n\t * This check may become more permissive over time.\n\t \n\t @example Ambiguous schema (with `preventAmbiguity: false`), and how to disambiguate it using {@link Unhydrated} nodes:\n\t * ```typescript\n\t * const schemaFactory = new SchemaFactory(\"com.example\");\n\t * class Feet extends schemaFactory.object(\"Feet\", { length: schemaFactory.number }) {}\n\t * class Meters extends schemaFactory.object(\"Meters\", { length: schemaFactory.number }) {}\n\t * const config = new TreeViewConfiguration({\n\t * \t// This combination of schema can lead to ambiguous cases and will error if `preventAmbiguity` is true.\n\t * \tschema: [Feet, Meters],\n\t * \tpreventAmbiguity: false,\n\t * });\n\t * const view = tree.viewWith(config);\n\t * // This is invalid since it is ambiguous which type of node is being constructed:\n\t * // view.initialize({ length: 5 });\n\t * // To work, an explicit type can be provided by using an {@link Unhydrated} Node:\n\t * view.initialize(new Meters({ length: 5 }));\n\t * ```\n\t \n\t @example Schema disambiguated by adjusting field names, validated with `preventAmbiguity: true:`\n\t * ```typescript\n\t * const schemaFactory = new SchemaFactory(\"com.example\");\n\t * class Feet extends schemaFactory.object(\"Feet\", { length: schemaFactory.number }) {}\n\t * class Meters extends schemaFactory.object(\"Meters\", {\n\t * \t// To avoid ambiguity when parsing unions of Feet and Meters, this renames the length field to \"meters\".\n\t * \t// To preserve compatibility with existing data from the ambiguous case,\n\t * \t// `{ key: \"length\" }` is set, so when persisted in the tree \"length\" is used as the field name.\n\t * \tmeters: schemaFactory.required(schemaFactory.number, { key: \"length\" }),\n\t * }) {}\n\t * const config = new TreeViewConfiguration({\n\t * \t// This combination of schema is not ambiguous because `Feet` and `Meters` have different required keys.\n\t * \tschema: [Feet, Meters],\n\t * \tpreventAmbiguity: true,\n\t * });\n\t * const view = tree.viewWith(config);\n\t * // This now works, since the field is sufficient to determine this is a `Meters` node.\n\t * view.initialize({ meters: 5 });\n\t * ```\n\t \n\t @privateRemarks\n\t * In the future, we can support lossless round tripping via the canonical JSON-like representation above when unambiguous.\n\t * This could be done via methods added to `Tree` to export and import such objects, which would give us a place to explicitly define the type of this representation.\n\t \n\t To make this more permissive in the future we can:\n\t \n\t - Make toMapTree more permissive (ex: allow disambiguation based on leaf type)\n\t * - Update this check to more tightly match toMapTree\n\t * - Add options to help schema authors disambiguate their types, such as \"constant fields\" which are not persisted, and always have a constant value.\n\t \n\t The above examples exist in executable form in this files tests, and should be updated there then copied back here.\n\t /\n\treadonly preventAmbiguity?: boolean;\n}\n\nconst defaultTreeConfigurationOptions: Required<ITreeConfigurationOptions> = {\n\tenableSchemaValidation: false,\n\tpreventAmbiguity: false,\n};\n\n/\n Property-bag configuration for {@link TreeViewConfiguration} construction.\n * @public\n /\nexport interface ITreeViewConfiguration<\n\tTSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> extends ITreeConfigurationOptions {\n\t/\n\t The schema which the application wants to view the tree with.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n Configuration for {@link ViewableTree.viewWith}.\n * @sealed @public\n /\nexport class TreeViewConfiguration<\n\tconst TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> implements Required<ITreeViewConfiguration<TSchema>>\n{\n\tprotected _typeCheck!: MakeNominal;\n\n\t/\n\t {@inheritDoc ITreeViewConfiguration.schema}\n\t /\n\tpublic readonly schema: TSchema;\n\n\t/\n\t {@inheritDoc ITreeConfigurationOptions.enableSchemaValidation}\n\t /\n\tpublic readonly enableSchemaValidation: boolean;\n\n\t/\n\t {@inheritDoc ITreeConfigurationOptions.preventAmbiguity}\n\t /\n\tpublic readonly preventAmbiguity: boolean;\n\n\t/\n\t @param props - Property bag of configuration options.\n\t /\n\tpublic constructor(props: ITreeViewConfiguration<TSchema>) {\n\t\tconst config = { ...defaultTreeConfigurationOptions, ...props };\n\t\tthis.schema = config.schema;\n\t\tthis.enableSchemaValidation = config.enableSchemaValidation;\n\t\tthis.preventAmbiguity = config.preventAmbiguity;\n\n\t\t// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.\n\t\tconst ambiguityErrors: string[] = [];\n\n\t\twalkFieldSchema(config.schema, {\n\t\t\t// Ensure all reachable schema are marked as most derived.\n\t\t\t// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),\n\t\t\t// an error is reported.\n\n\t\t\tnode: markSchemaMostDerived,\n\t\t\tallowedTypes(types): void {\n\t\t\t\tif (config.preventAmbiguity) {\n\t\t\t\t\tcheckUnion(types, ambiguityErrors);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\n\t\tif (ambiguityErrors.length !== 0) {\n\t\t\t// Duplicate errors are common since when two types conflict, both orders error:\n\t\t\tconst deduplicated = new Set(ambiguityErrors);\n\t\t\tthrow new UsageError(`Ambiguous schema found:\\n${[...deduplicated].join(\"\\n\")}`);\n\t\t}\n\n\t\t// Eagerly perform this conversion to surface errors sooner.\n\t\ttoStoredSchema(config.schema);\n\t}\n}\n\n/\n Pretty print a set of types for use in error messages.\n /\nfunction formatTypes(allowed: Iterable<TreeNodeSchema>): string {\n\t// Use JSON.stringify to quote and escape identifiers.\n\t// Don't just use a single array JSON.stringify since that omits spaces between items\n\treturn `[${Array.from(allowed, (s) => JSON.stringify(s.identifier)).join(\", \")}]`;\n}\n\n/\n Detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}.\n /\nexport function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): void {\n\tconst checked: Set<TreeNodeSchema> = new Set();\n\tconst maps: TreeNodeSchema[] = [];\n\tconst arrays: TreeNodeSchema[] = [];\n\n\tconst objects: ObjectNodeSchema[] = [];\n\t// Map from key to schema using that key\n\tconst allObjectKeys: Map<string, Set<TreeNodeSchema>> = new Map();\n\n\tfor (const schema of union) {\n\t\tif (checked.has(schema)) {\n\t\t\tthrow new UsageError(`Duplicate schema in allowed types: ${schema.identifier}`);\n\t\t}\n\t\tchecked.add(schema);\n\n\t\tif (schema instanceof LeafNodeSchema) {\n\t\t\t// nothing to do\n\t\t} else if (isObjectNodeSchema(schema)) {\n\t\t\tobjects.push(schema);\n\t\t\tfor (const key of schema.fields.keys()) {\n\t\t\t\tgetOrCreate(allObjectKeys, key, () => new Set()).add(schema);\n\t\t\t}\n\t\t} else if (schema.kind === NodeKind.Array) {\n\t\t\tarrays.push(schema);\n\t\t} else {\n\t\t\tassert(schema.kind === NodeKind.Map, 0x9e7 / invalid schema /);\n\t\t\tmaps.push(schema);\n\t\t}\n\t}\n\n\tif (arrays.length > 1) {\n\t\terrors.push(\n\t\t\t`More than one kind of array allowed within union (${formatTypes(arrays)}). This would require type disambiguation which is not supported by arrays during import or export.`,\n\t\t);\n\t}\n\n\tif (maps.length > 1) {\n\t\terrors.push(\n\t\t\t`More than one kind of map allowed within union (${formatTypes(maps)}). This would require type disambiguation which is not supported by maps during import or export.`,\n\t\t);\n\t}\n\n\tif (maps.length > 0 && arrays.length > 0) {\n\t\terrors.push(\n\t\t\t`Both a map and an array allowed within union (${formatTypes([...arrays, ...maps])}). Both can be implicitly constructed from iterables like arrays, which are ambiguous when the array is empty.`,\n\t\t);\n\t}\n\n\tif (objects.length > 0 && maps.length > 0) {\n\t\terrors.push(\n\t\t\t`Both a object and a map allowed within union (${formatTypes([...objects, ...maps])}). Both can be constructed from objects and can be ambiguous.`,\n\t\t);\n\t}\n\n\t// Check for objects which fully overlap:\n\tfor (const schema of objects) {\n\t\t// All objects which might be ambiguous relative to `schema`.\n\t\tconst possiblyAmbiguous = new Set(objects);\n\n\t\t// A schema can't be ambiguous with itself\n\t\tpossiblyAmbiguous.delete(schema);\n\n\t\t// For each field of schema, remove schema from possiblyAmbiguous that do not have that field\n\t\tfor (const [key, field] of schema.fields) {\n\t\t\tif (field.kind === FieldKind.Required) {\n\t\t\t\tconst withKey = allObjectKeys.get(key) ?? fail(\"missing schema\");\n\t\t\t\tfor (const candidate of possiblyAmbiguous) {\n\t\t\t\t\tif (!withKey.has(candidate)) {\n\t\t\t\t\t\tpossiblyAmbiguous.delete(candidate);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (possiblyAmbiguous.size > 0) {\n\t\t\t// TODO: make this check more permissive.\n\t\t\t// Allow using the type of the field to disambiguate, at least for leaf types.\n\t\t\t// Add \"constant\" fields which can be used to disambiguate even more cases without adding persisted data: maybe make them optional in constructor?\n\t\t\t// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).\n\t\t\t// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/toMapTree.ts.\n\n\t\t\terrors.push(\n\t\t\t\t`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,\n\t\t\t);\n\t\t}\n\t}\n}\n\n/\n A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork \| creation of branches} and for those branches to later be {@link TreeBranch.merge \| merged}.\n \n The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n \n A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha \| view with a schema}, use {@link TreeBranch.hasRootSchema \| hasRootSchema()}.\n \n The branch associated directly with the {@link ITree \| SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @alpha\n /\nexport interface TreeBranch extends IDisposable {\n\t/\n\t Events for the branch\n\t /\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/\n\t Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha \| view} of the given schema.\n\t \n\t To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo \| Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo \| Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t * const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t * // ...\n\t * }\n\t * ```\n\t /\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t/\n\t Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge \| merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose \| explicitly} or {@link TreeBranch.merge \| implicitly when merging} into another branch.\n\t /\n\tfork(): TreeBranch;\n\n\t/\n\t Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t /\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/\n\t Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork \| branch} - attempting to rebase the main branch will throw.\n\t \n\t Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t \n\t The {@link TreeBranch \| main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t /\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/\n\t Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge \| they are merged} into another branch.\n\t \n\t Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto \| rebased}.\n\t \n\t The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t /\n\tdispose(error?: Error): void;\n}\n\n/\n An editable view of a (version control style) branch of a shared tree based on some schema.\n \n This schema--known as the view schema--may or may not align the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility \| compatibility}.\n \n Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and\n * choose a schema compatibility policy that aligns with their application's needs.\n \n @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * @sealed @public\n /\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/\n\t The current root of the tree.\n\t \n\t If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility \| compatibility}'s {@link SchemaCompatibilityStatus.canView \| canView} before using.\n\t \n\t To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t \n\t To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t /\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/\n\t Description of the current compatibility status between the view schema and stored schema.\n\t \n\t {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t /\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/\n\t When the schemas are not an exact match and {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will update the compatibility state, and allow access to `root`.\n\t * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!\n\t * @remarks\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t /\n\tupgradeSchema(): void;\n\n\t/\n\t Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t \n\t Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t \n\t Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t /\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/\n\t Events for the tree.\n\t /\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/\n\t The view schema used by this TreeView.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n /\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema,\n> extends Omit<TreeView<ReadSchema<TSchema>>, \"root\" \| \"initialize\">,\n\t\tTreeBranch {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/\n Information about a view schema's compatibility with the document's stored schema.\n \n See SharedTree's README for more information about choosing a compatibility policy.\n * @sealed @public\n /\nexport interface SchemaCompatibilityStatus {\n\t/\n\t Whether the view schema allows exactly the same set of documents as the stored schema.\n\t \n\t @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t \n\t Examples which are expressible where this may occur include:\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)\n\t \n\t These cases are typically not interesting to applications.\n\t /\n\treadonly isEquivalent: boolean;\n\n\t/\n\t Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t \n\t Currently, this field is true iff `isEquivalent` is true.\n\t * Do not rely on this:\n\t * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.\n\t * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,\n\t * likely through out-of-schema content adapters that the application can provide alongside their view schema.\n\t \n\t Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!\n\t * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that\n\t * aligns with their application's needs.\n\t \n\t @remarks\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * this is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t \n\t Future version of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t \n\t @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t /\n\treadonly canView: boolean;\n\n\t/\n\t True iff the view schema supports all possible documents permitted by the stored schema.\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t /\n\treadonly canUpgrade: boolean;\n\n\t/\n\t True iff the document is uninitialized (i.e. it has no schema and no content).\n\t \n\t To initialize the document, call {@link TreeView.initialize}.\n\t \n\t @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t /\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/\n Events for {@link TreeBranch}.\n * @sealed @alpha\n /\nexport interface TreeBranchEvents {\n\t/\n\t The stored schema for the document has changed.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t \n\t @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t /\n\tchanged(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/\n\t Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t \n\t The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n}\n\n/\n Events for {@link TreeView}.\n * @sealed @public\n /\nexport interface TreeViewEvents {\n\t/\n\t Raised whenever {@link TreeView.root} is invalidated.\n\t \n\t This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t /\n\trootChanged(): void;\n\n\t/\n\t The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t \n\t @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t \n\t The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n\n/\n Retrieve the {@link TreeViewAlpha \| alpha API} for a {@link TreeView}.\n * @alpha\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}
1	+ {"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/tree.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 type { IFluidLoadable, IDisposable, Listenable } from \"@fluidframework/core-interfaces\";\nimport { UsageError } from \"@fluidframework/telemetry-utils/internal\";\n\nimport type {\n\tCommitMetadata,\n\tRevertibleAlphaFactory,\n\tRevertibleFactory,\n} from \"../../core/index.js\";\n\n// This is referenced by doc comments.\n// eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports\nimport type { TreeAlpha } from \"../../shared-tree/index.js\";\n\nimport {\n\ttype ImplicitFieldSchema,\n\ttype InsertableField,\n\ttype InsertableTreeFieldFromImplicitField,\n\ttype ReadableField,\n\ttype ReadSchema,\n\ttype TreeFieldFromImplicitField,\n\ttype UnsafeUnknownSchema,\n\tFieldKind,\n} from \"../schemaTypes.js\";\nimport { NodeKind, type TreeNodeSchema } from \"../core/index.js\";\nimport { toStoredSchema } from \"../toStoredSchema.js\";\nimport { LeafNodeSchema } from \"../leafNodeSchema.js\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport { isObjectNodeSchema, type ObjectNodeSchema } from \"../objectNodeTypes.js\";\nimport { markSchemaMostDerived } from \"./schemaFactory.js\";\nimport { fail, getOrCreate } from \"../../util/index.js\";\nimport type { MakeNominal } from \"../../util/index.js\";\nimport { walkFieldSchema } from \"../walkFieldSchema.js\";\n\n/\n A tree from which a {@link TreeView} can be created.\n \n @privateRemarks\n * TODO:\n * Add stored key versions of {@link TreeAlpha.(exportVerbose:2)}, {@link TreeAlpha.(exportConcise:2)} and {@link TreeAlpha.exportCompressed} here so tree content can be accessed without a view schema.\n * Add exportSimpleSchema and exportJsonSchema methods (which should exactly match the concise format, and match the free functions for exporting view schema).\n * Maybe rename \"exportJsonSchema\" to align on \"concise\" terminology.\n * Ensure schema exporting APIs here align and reference APIs for exporting view schema to the same formats (which should include stored vs property key choice).\n * Make sure users of independentView can use these export APIs (maybe provide a reference back to the ViewableTree from the TreeView to accomplish that).\n * Some of these APIs are on ISharedTree and can get moved here.\n * @system @sealed @public\n /\nexport interface ViewableTree {\n\t/\n\t Returns a {@link TreeView} using the provided schema.\n\t * If the stored schema is compatible with the view schema specified by `config`,\n\t * the returned {@link TreeView} will expose the root with a schema-aware API based on the provided view schema.\n\t * If the provided schema is incompatible with the stored schema, the view will instead expose a status indicating the incompatibility.\n\t \n\t @remarks\n\t * If the tree is uninitialized (has no schema and no content), use {@link TreeView.initialize} on the returned view to set the schema and content together.\n\t * Using `viewWith` followed by {@link TreeView.upgradeSchema} to initialize only the schema for a document is technically valid when the schema\n\t * permits trees with no content.\n\t \n\t Note that other clients can modify the document at any time, causing the view to change its compatibility status: see {@link TreeView.events} for how to handle invalidation in these cases.\n\t \n\t Only one schematized view may exist for a given ITree at a time.\n\t * If creating a second, the first must be disposed before calling `viewWith` again.\n\t \n\t \n\t * TODO: Provide a way to make a generic view schema for any document.\n\t * TODO: Support adapters for handling out-of-schema data.\n\t \n\t Doing initialization here allows a small API that is hard to use incorrectly.\n\t * Other approaches tend to have easy-to-make mistakes.\n\t * For example, having a separate initialization function means apps can forget to call it, making an app that can only open existing documents,\n\t * or call it unconditionally leaving an app that can only create new documents.\n\t * It also would require the schema to be passed into separate places and could cause issues if they didn't match.\n\t * Since the initialization function couldn't return a typed tree, the type checking wouldn't help catch that.\n\t * Also, if an app manages to create a document, but the initialization fails to get persisted, an app that only calls the initialization function\n\t * on the create code-path (for example how a schematized factory might do it),\n\t * would leave the document in an unusable state which could not be repaired when it is reopened (by the same or other clients).\n\t * Additionally, once out of schema content adapters are properly supported (with lazy document updates),\n\t * this initialization could become just another out of schema content adapter and this initialization is no longer a special case.\n\t /\n\tviewWith<TRoot extends ImplicitFieldSchema>(\n\t\tconfig: TreeViewConfiguration<TRoot>,\n\t): TreeView<TRoot>;\n}\n\n/\n Channel for a Fluid Tree DDS.\n * @remarks\n * Allows storing and collaboratively editing schema-aware hierarchial data.\n * @sealed @public\n /\nexport interface ITree extends ViewableTree, IFluidLoadable {}\n\n/\n Options when constructing a tree view.\n * @public\n /\nexport interface ITreeConfigurationOptions {\n\t/\n\t If `true`, the tree will validate new content against its stored schema at insertion time\n\t * and throw an error if the new content doesn't match the expected schema.\n\t \n\t @defaultValue `false`.\n\t \n\t @remarks Enabling schema validation has a performance penalty when inserting new content into the tree because\n\t * additional checks are done. Enable this option only in scenarios where you are ok with that operation being a\n\t * bit slower.\n\t /\n\tenableSchemaValidation?: boolean;\n\n\t/\n\t A flag used to opt into strict rules ensuring that the schema avoids cases which can make the type of nodes ambiguous when importing or exporting data.\n\t * @defaultValue `false`.\n\t \n\t @remarks\n\t * When this is true, it ensures that the compile time type safety for data when constructing nodes is sufficient to ensure that the runtime behavior will not give node data ambiguity errors.\n\t \n\t This ensures that the canonical JSON-like representation of all unions in the tree are lossless and unambiguous.\n\t * This canonical JSON-like representation consists of arrays, plain old JavaScript objects with string keys, booleans, numbers (excluding NaN, -0 and infinities), strings, null and {@link @fluidframework/core-interfaces#IFluidHandle}s.\n\t * It is compatible with the node creation APIs (such as schema class constructors) and is also compatible with JSON assuming any IFluidHandles get special handling (since they are not JSON compatible).\n\t * Currently these cases can cause ambiguity in a union:\n\t \n\t - More than one ArrayNode type: it's impossible to tell which array type is intended in the case of empty arrays (`[]`).\n\t \n\t - More than one MapNode type: it's impossible to tell which map type is intended in the case of an empty map (`{}`).\n\t \n\t - Both a MapNode and an ArrayNode: this case is not a problem for the canonical JSON representation, but is an issue when constructing from an Iterable, which is supported for both MapNode and ArrayNode.\n\t \n\t - Both a MapNode and an ObjectNode: when the input is valid for the ObjectNode, the current parser always considers it ambiguous with being a MapNode.\n\t \n\t - ObjectNodes which have fields (required or optional) which include all required fields of another ObjectNode: currently each ObjectNode is differentiated by the presence of its required fields.\n\t \n\t This check is conservative: some complex cases may error if the current simple algorithm cannot show no ambiguity is possible.\n\t * This check may become more permissive over time.\n\t \n\t @example Ambiguous schema (with `preventAmbiguity: false`), and how to disambiguate it using {@link Unhydrated} nodes:\n\t * ```typescript\n\t * const schemaFactory = new SchemaFactory(\"com.example\");\n\t * class Feet extends schemaFactory.object(\"Feet\", { length: schemaFactory.number }) {}\n\t * class Meters extends schemaFactory.object(\"Meters\", { length: schemaFactory.number }) {}\n\t * const config = new TreeViewConfiguration({\n\t * \t// This combination of schema can lead to ambiguous cases and will error if `preventAmbiguity` is true.\n\t * \tschema: [Feet, Meters],\n\t * \tpreventAmbiguity: false,\n\t * });\n\t * const view = tree.viewWith(config);\n\t * // This is invalid since it is ambiguous which type of node is being constructed:\n\t * // view.initialize({ length: 5 });\n\t * // To work, an explicit type can be provided by using an {@link Unhydrated} Node:\n\t * view.initialize(new Meters({ length: 5 }));\n\t * ```\n\t \n\t @example Schema disambiguated by adjusting field names, validated with `preventAmbiguity: true:`\n\t * ```typescript\n\t * const schemaFactory = new SchemaFactory(\"com.example\");\n\t * class Feet extends schemaFactory.object(\"Feet\", { length: schemaFactory.number }) {}\n\t * class Meters extends schemaFactory.object(\"Meters\", {\n\t * \t// To avoid ambiguity when parsing unions of Feet and Meters, this renames the length field to \"meters\".\n\t * \t// To preserve compatibility with existing data from the ambiguous case,\n\t * \t// `{ key: \"length\" }` is set, so when persisted in the tree \"length\" is used as the field name.\n\t * \tmeters: schemaFactory.required(schemaFactory.number, { key: \"length\" }),\n\t * }) {}\n\t * const config = new TreeViewConfiguration({\n\t * \t// This combination of schema is not ambiguous because `Feet` and `Meters` have different required keys.\n\t * \tschema: [Feet, Meters],\n\t * \tpreventAmbiguity: true,\n\t * });\n\t * const view = tree.viewWith(config);\n\t * // This now works, since the field is sufficient to determine this is a `Meters` node.\n\t * view.initialize({ meters: 5 });\n\t * ```\n\t \n\t @privateRemarks\n\t * In the future, we can support lossless round tripping via the canonical JSON-like representation above when unambiguous.\n\t * This could be done via methods added to `Tree` to export and import such objects, which would give us a place to explicitly define the type of this representation.\n\t \n\t To make this more permissive in the future we can:\n\t \n\t - Make toMapTree more permissive (ex: allow disambiguation based on leaf type)\n\t * - Update this check to more tightly match toMapTree\n\t * - Add options to help schema authors disambiguate their types, such as \"constant fields\" which are not persisted, and always have a constant value.\n\t \n\t The above examples exist in executable form in this files tests, and should be updated there then copied back here.\n\t /\n\treadonly preventAmbiguity?: boolean;\n}\n\nconst defaultTreeConfigurationOptions: Required<ITreeConfigurationOptions> = {\n\tenableSchemaValidation: false,\n\tpreventAmbiguity: false,\n};\n\n/\n Property-bag configuration for {@link TreeViewConfiguration} construction.\n * @public\n /\nexport interface ITreeViewConfiguration<\n\tTSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> extends ITreeConfigurationOptions {\n\t/\n\t The schema which the application wants to view the tree with.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n Configuration for {@link ViewableTree.viewWith}.\n * @sealed @public\n /\nexport class TreeViewConfiguration<\n\tconst TSchema extends ImplicitFieldSchema = ImplicitFieldSchema,\n> implements Required<ITreeViewConfiguration<TSchema>>\n{\n\tprotected _typeCheck!: MakeNominal;\n\n\t/\n\t {@inheritDoc ITreeViewConfiguration.schema}\n\t /\n\tpublic readonly schema: TSchema;\n\n\t/\n\t {@inheritDoc ITreeConfigurationOptions.enableSchemaValidation}\n\t /\n\tpublic readonly enableSchemaValidation: boolean;\n\n\t/\n\t {@inheritDoc ITreeConfigurationOptions.preventAmbiguity}\n\t /\n\tpublic readonly preventAmbiguity: boolean;\n\n\t/\n\t @param props - Property bag of configuration options.\n\t /\n\tpublic constructor(props: ITreeViewConfiguration<TSchema>) {\n\t\tconst config = { ...defaultTreeConfigurationOptions, ...props };\n\t\tthis.schema = config.schema;\n\t\tthis.enableSchemaValidation = config.enableSchemaValidation;\n\t\tthis.preventAmbiguity = config.preventAmbiguity;\n\n\t\t// Ambiguity errors are lower priority to report than invalid schema errors, so collect these in an array and report them all at once.\n\t\tconst ambiguityErrors: string[] = [];\n\n\t\twalkFieldSchema(config.schema, {\n\t\t\t// Ensure all reachable schema are marked as most derived.\n\t\t\t// This ensures if multiple schema extending the same schema factory generated class are present (or have been constructed, or get constructed in the future),\n\t\t\t// an error is reported.\n\n\t\t\tnode: markSchemaMostDerived,\n\t\t\tallowedTypes(types): void {\n\t\t\t\tif (config.preventAmbiguity) {\n\t\t\t\t\tcheckUnion(types, ambiguityErrors);\n\t\t\t\t}\n\t\t\t},\n\t\t});\n\n\t\tif (ambiguityErrors.length !== 0) {\n\t\t\t// Duplicate errors are common since when two types conflict, both orders error:\n\t\t\tconst deduplicated = new Set(ambiguityErrors);\n\t\t\tthrow new UsageError(`Ambiguous schema found:\\n${[...deduplicated].join(\"\\n\")}`);\n\t\t}\n\n\t\t// Eagerly perform this conversion to surface errors sooner.\n\t\ttoStoredSchema(config.schema);\n\t}\n}\n\n/\n Pretty print a set of types for use in error messages.\n /\nfunction formatTypes(allowed: Iterable<TreeNodeSchema>): string {\n\t// Use JSON.stringify to quote and escape identifiers.\n\t// Don't just use a single array JSON.stringify since that omits spaces between items\n\treturn `[${Array.from(allowed, (s) => JSON.stringify(s.identifier)).join(\", \")}]`;\n}\n\n/\n Detect cases documented in {@link ITreeConfigurationOptions.preventAmbiguity}.\n /\nexport function checkUnion(union: Iterable<TreeNodeSchema>, errors: string[]): void {\n\tconst checked: Set<TreeNodeSchema> = new Set();\n\tconst maps: TreeNodeSchema[] = [];\n\tconst arrays: TreeNodeSchema[] = [];\n\n\tconst objects: ObjectNodeSchema[] = [];\n\t// Map from key to schema using that key\n\tconst allObjectKeys: Map<string, Set<TreeNodeSchema>> = new Map();\n\n\tfor (const schema of union) {\n\t\tif (checked.has(schema)) {\n\t\t\tthrow new UsageError(`Duplicate schema in allowed types: ${schema.identifier}`);\n\t\t}\n\t\tchecked.add(schema);\n\n\t\tif (schema instanceof LeafNodeSchema) {\n\t\t\t// nothing to do\n\t\t} else if (isObjectNodeSchema(schema)) {\n\t\t\tobjects.push(schema);\n\t\t\tfor (const key of schema.fields.keys()) {\n\t\t\t\tgetOrCreate(allObjectKeys, key, () => new Set()).add(schema);\n\t\t\t}\n\t\t} else if (schema.kind === NodeKind.Array) {\n\t\t\tarrays.push(schema);\n\t\t} else {\n\t\t\tassert(schema.kind === NodeKind.Map, 0x9e7 / invalid schema /);\n\t\t\tmaps.push(schema);\n\t\t}\n\t}\n\n\tif (arrays.length > 1) {\n\t\terrors.push(\n\t\t\t`More than one kind of array allowed within union (${formatTypes(arrays)}). This would require type disambiguation which is not supported by arrays during import or export.`,\n\t\t);\n\t}\n\n\tif (maps.length > 1) {\n\t\terrors.push(\n\t\t\t`More than one kind of map allowed within union (${formatTypes(maps)}). This would require type disambiguation which is not supported by maps during import or export.`,\n\t\t);\n\t}\n\n\tif (maps.length > 0 && arrays.length > 0) {\n\t\terrors.push(\n\t\t\t`Both a map and an array allowed within union (${formatTypes([...arrays, ...maps])}). Both can be implicitly constructed from iterables like arrays, which are ambiguous when the array is empty.`,\n\t\t);\n\t}\n\n\tif (objects.length > 0 && maps.length > 0) {\n\t\terrors.push(\n\t\t\t`Both a object and a map allowed within union (${formatTypes([...objects, ...maps])}). Both can be constructed from objects and can be ambiguous.`,\n\t\t);\n\t}\n\n\t// Check for objects which fully overlap:\n\tfor (const schema of objects) {\n\t\t// All objects which might be ambiguous relative to `schema`.\n\t\tconst possiblyAmbiguous = new Set(objects);\n\n\t\t// A schema can't be ambiguous with itself\n\t\tpossiblyAmbiguous.delete(schema);\n\n\t\t// For each field of schema, remove schema from possiblyAmbiguous that do not have that field\n\t\tfor (const [key, field] of schema.fields) {\n\t\t\tif (field.kind === FieldKind.Required) {\n\t\t\t\tconst withKey = allObjectKeys.get(key) ?? fail(\"missing schema\");\n\t\t\t\tfor (const candidate of possiblyAmbiguous) {\n\t\t\t\t\tif (!withKey.has(candidate)) {\n\t\t\t\t\t\tpossiblyAmbiguous.delete(candidate);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (possiblyAmbiguous.size > 0) {\n\t\t\t// TODO: make this check more permissive.\n\t\t\t// Allow using the type of the field to disambiguate, at least for leaf types.\n\t\t\t// Add \"constant\" fields which can be used to disambiguate even more cases without adding persisted data: maybe make them optional in constructor?\n\t\t\t// Consider separating unambiguous implicit construction format from constructor arguments at type level, allowing constructor to superset the implicit construction options (ex: optional constant fields).\n\t\t\t// The policy here however must remain at least as conservative as shallowCompatibilityTest in src/simple-tree/toMapTree.ts.\n\n\t\t\terrors.push(\n\t\t\t\t`The required fields of ${JSON.stringify(schema.identifier)} are insufficient to differentiate it from the following types: ${formatTypes(possiblyAmbiguous)}. For objects to be considered unambiguous, each must have required fields that do not all occur on any other object in the union.`,\n\t\t\t);\n\t\t}\n\t}\n}\n\n/\n A collection of functionality associated with a (version-control-style) branch of a SharedTree.\n * @remarks A `TreeBranch` allows for the {@link TreeBranch.fork \| creation of branches} and for those branches to later be {@link TreeBranch.merge \| merged}.\n \n The `TreeBranch` for a specific {@link TreeNode} may be acquired by calling `TreeAlpha.branch`.\n \n A branch does not necessarily know the schema of its SharedTree - to convert a branch to a {@link TreeViewAlpha \| view with a schema}, use {@link TreeBranch.hasRootSchema \| hasRootSchema()}.\n \n The branch associated directly with the {@link ITree \| SharedTree} is the \"main\" branch, and all other branches fork (directly or transitively) from that main branch.\n * @sealed @alpha\n /\nexport interface TreeBranch extends IDisposable {\n\t/\n\t Events for the branch\n\t /\n\treadonly events: Listenable<TreeBranchEvents>;\n\n\t/\n\t Returns true if this branch has the given schema as its root schema.\n\t * @remarks This is a type guard which allows this branch to become strongly typed as a {@link TreeViewAlpha \| view} of the given schema.\n\t \n\t To succeed, the given schema must be invariant to the schema of the view - it must include exactly the same allowed types.\n\t * For example, a schema of `Foo \| Bar` will not match a view schema of `Foo`, and likewise a schema of `Foo` will not match a view schema of `Foo \| Bar`.\n\t * @example\n\t * ```typescript\n\t * if (branch.hasRootSchema(MySchema)) {\n\t * const { root } = branch; // `branch` is now a TreeViewAlpha<MySchema>\n\t * // ...\n\t * }\n\t * ```\n\t /\n\thasRootSchema<TSchema extends ImplicitFieldSchema>(\n\t\tschema: TSchema,\n\t): this is TreeViewAlpha<TSchema>;\n\n\t/\n\t Fork a new branch off of this branch which is based off of this branch's current state.\n\t * @remarks Any changes to the tree on the new branch will not apply to this branch until the new branch is e.g. {@link TreeBranch.merge \| merged} back into this branch.\n\t * The branch should be disposed when no longer needed, either {@link TreeBranch.dispose \| explicitly} or {@link TreeBranch.merge \| implicitly when merging} into another branch.\n\t /\n\tfork(): TreeBranch;\n\n\t/\n\t Apply all the new changes on the given branch to this branch.\n\t * @param branch - a branch which was created by a call to `branch()`.\n\t * @param disposeMerged - whether or not to dispose `branch` after the merge completes.\n\t * Defaults to true.\n\t * The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t * @remarks All ongoing transactions (if any) in `branch` will be committed before the merge.\n\t /\n\tmerge(branch: TreeBranch, disposeMerged?: boolean): void;\n\n\t/\n\t Advance this branch forward such that all new changes on the target branch become part of this branch.\n\t * @param branch - The branch to rebase onto.\n\t * @remarks After rebasing, this branch will be \"ahead\" of the target branch, that is, its unique changes will have been recreated as if they happened after all changes on the target branch.\n\t * This method may only be called on branches produced via {@link TreeBranch.fork \| branch} - attempting to rebase the main branch will throw.\n\t \n\t Rebasing long-lived branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last rebased.\n\t \n\t The {@link TreeBranch \| main branch} cannot be rebased onto another branch - attempting to do so will throw an error.\n\t /\n\trebaseOnto(branch: TreeBranch): void;\n\n\t/\n\t Dispose of this branch, cleaning up any resources associated with it.\n\t * @param error - Optional error indicating the reason for the disposal, if the object was disposed as the result of an error.\n\t * @remarks Branches can also be automatically disposed when {@link TreeBranch.merge \| they are merged} into another branch.\n\t \n\t Disposing branches is important to avoid consuming memory unnecessarily.\n\t * In particular, the SharedTree retains all sequenced changes made to the tree since the \"most-behind\" branch was created or last {@link TreeBranch.rebaseOnto \| rebased}.\n\t \n\t The {@link TreeBranch \| main branch} cannot be disposed - attempting to do so will have no effect.\n\t /\n\tdispose(error?: Error): void;\n}\n\n/\n An editable view of a (version control style) branch of a shared tree based on some schema.\n \n This schema--known as the view schema--may or may not align the stored schema of the document.\n * Information about discrepancies between the two schemas is available via {@link TreeView.compatibility \| compatibility}.\n \n Application authors are encouraged to read [schema-evolution.md](../../docs/user-facing/schema-evolution.md) and\n * choose a schema compatibility policy that aligns with their application's needs.\n \n @privateRemarks\n * From an API design perspective, `upgradeSchema` could be merged into `viewWith` and/or `viewWith` could return errors explicitly on incompatible documents.\n * Such approaches would make it discoverable that out of schema handling may need to be done.\n * Doing that would however complicate trivial \"hello world\" style example slightly, as well as be a breaking API change.\n * It also seems more complex to handle invalidation with that pattern.\n * Thus this design was chosen at the risk of apps blindly accessing `root` then breaking unexpectedly when the document is incompatible.\n * @sealed @public\n /\nexport interface TreeView<in out TSchema extends ImplicitFieldSchema> extends IDisposable {\n\t/\n\t The current root of the tree.\n\t \n\t If the view schema not sufficiently compatible with the stored schema, accessing this will throw.\n\t * To handle this case, check {@link TreeView.compatibility \| compatibility}'s {@link SchemaCompatibilityStatus.canView \| canView} before using.\n\t \n\t To get notified about changes to this field,\n\t * use {@link TreeViewEvents.rootChanged} via `view.events.on(\"rootChanged\", callback)`.\n\t \n\t To get notified about changes to stored schema (which may affect compatibility between this view's schema and\n\t * the stored schema), use {@link TreeViewEvents.schemaChanged} via `view.events.on(\"schemaChanged\", callback)`.\n\t /\n\tget root(): TreeFieldFromImplicitField<TSchema>;\n\n\tset root(newRoot: InsertableTreeFieldFromImplicitField<TSchema>);\n\n\t/\n\t Description of the current compatibility status between the view schema and stored schema.\n\t \n\t {@link TreeViewEvents.schemaChanged} is fired when the compatibility status changes.\n\t /\n\treadonly compatibility: SchemaCompatibilityStatus;\n\n\t/\n\t When the schemas are not an exact match and {@link SchemaCompatibilityStatus.canUpgrade} is true,\n\t * this can be used to modify the stored schema to make it match the view schema.\n\t * This will update the compatibility state, and allow access to `root`.\n\t * Beware that this may impact other clients' ability to view the document depending on the application's schema compatibility policy!\n\t * @remarks\n\t * It is an error to call this when {@link SchemaCompatibilityStatus.canUpgrade} is false, and a no-op when the stored and view schema are already an exact match.\n\t * @privateRemarks\n\t * In the future, more upgrade options could be provided here.\n\t * Some options that could be added:\n\t * - check the actual document contents (not just the schema) and attempt an atomic document update if the data is compatible.\n\t * - apply converters and upgrade the document.\n\t * - apply converters to lazily to adapt the document to the requested view schema (with optional lazy schema updates or transparent conversions on write).\n\t /\n\tupgradeSchema(): void;\n\n\t/\n\t Initialize the tree, setting the stored schema to match this view's schema and setting the tree content.\n\t \n\t Only valid to call when this view's {@link SchemaCompatibilityStatus.canInitialize} is true.\n\t \n\t Applications should typically call this function before attaching a `SharedTree`.\n\t * @param content - The content to initialize the tree with.\n\t /\n\tinitialize(content: InsertableTreeFieldFromImplicitField<TSchema>): void;\n\n\t/\n\t Events for the tree.\n\t /\n\treadonly events: Listenable<TreeViewEvents>;\n\n\t/\n\t The view schema used by this TreeView.\n\t /\n\treadonly schema: TSchema;\n}\n\n/\n {@link TreeView} with proposed changes to the schema aware typing to allow use with `UnsafeUnknownSchema`.\n * @sealed @alpha\n /\nexport interface TreeViewAlpha<\n\tin out TSchema extends ImplicitFieldSchema \| UnsafeUnknownSchema,\n> extends Omit<TreeView<ReadSchema<TSchema>>, \"root\" \| \"initialize\">,\n\t\tTreeBranch {\n\tget root(): ReadableField<TSchema>;\n\n\tset root(newRoot: InsertableField<TSchema>);\n\n\treadonly events: Listenable<TreeViewEvents & TreeBranchEvents>;\n\n\tinitialize(content: InsertableField<TSchema>): void;\n\n\t// Override the base branch method to return a typed view rather than merely a branch.\n\tfork(): ReturnType<TreeBranch[\"fork\"]> & TreeViewAlpha<TSchema>;\n}\n\n/\n Information about a view schema's compatibility with the document's stored schema.\n \n See SharedTree's README for more information about choosing a compatibility policy.\n * @sealed @public\n /\nexport interface SchemaCompatibilityStatus {\n\t/\n\t Whether the view schema allows exactly the same set of documents as the stored schema.\n\t \n\t @remarks\n\t * Equivalence here is defined in terms of allowed documents because there are some degenerate cases where schemas are not\n\t * exact matches in a strict (schema-based) sense but still allow the same documents, and the document notion is more useful to applications.\n\t \n\t Examples which are expressible where this may occur include:\n\t * - schema repository `A` has extra schema which schema `B` doesn't have, but they are unused (i.e. not reachable from the root schema)\n\t * - field in schema `A` has allowed field members which the corresponding field in schema `B` does not have, but those types are not constructible (ex: an object node type containing a required field with no allowed types)\n\t \n\t These cases are typically not interesting to applications.\n\t /\n\treadonly isEquivalent: boolean;\n\n\t/\n\t Whether the current view schema is sufficiently compatible with the stored schema to allow viewing tree data.\n\t * If false, {@link TreeView.root} will throw upon access.\n\t \n\t Currently, this field is true iff `isEquivalent` is true.\n\t * Do not rely on this:\n\t * there are near-term plans to extend support for viewing documents when the stored schema contains additional optional fields not present in the view schema.\n\t * The other two types of backward-compatible changes (field relaxations and addition of allowed field types) will eventually be supported as well,\n\t * likely through out-of-schema content adapters that the application can provide alongside their view schema.\n\t \n\t Be aware that even with these SharedTree limitations fixed, application logic may not correctly tolerate the documents allowable by the stored schema!\n\t * Application authors are encouraged to read docs/user-facing/schema-evolution.md and choose a schema compatibility policy that\n\t * aligns with their application's needs.\n\t \n\t @remarks\n\t * When the documents allowed by the view schema is a strict superset of those by the stored schema,\n\t * this is false because writes to the document using the view schema could make the document violate its stored schema.\n\t * In this case, the stored schema could be updated to match the provided view schema, allowing read-write access to the tree.\n\t * See {@link SchemaCompatibilityStatus.canUpgrade}.\n\t \n\t Future version of SharedTree may provide readonly access to the document in this case because that would be safe,\n\t * but this is not currently supported.\n\t \n\t @privateRemarks\n\t * A necessary condition for this to be true is that the documents allowed by the view schema are a subset of those allowed by the stored schema.\n\t * This is not sufficient: the simple-tree layer's read APIs do not tolerate out-of-schema data.\n\t * For example, if the view schema for a node has a required `Point` field but the stored schema has an optional `Point` field,\n\t * read APIs on the view schema do not work correctly when the document has a node with a missing `Point` field.\n\t * Similar issues happen when the view schema has a field with less allowed types than the stored schema and the document actually leverages those types.\n\t /\n\treadonly canView: boolean;\n\n\t/\n\t True iff the view schema supports all possible documents permitted by the stored schema.\n\t * When true, it is valid to call {@link TreeView.upgradeSchema} (though if the stored schema is already an exact match, this is a no-op).\n\t /\n\treadonly canUpgrade: boolean;\n\n\t/\n\t True iff the document is uninitialized (i.e. it has no schema and no content).\n\t \n\t To initialize the document, call {@link TreeView.initialize}.\n\t \n\t @remarks\n\t * It's not necessary to check this field before calling {@link TreeView.initialize} in most scenarios; application authors typically know from\n\t * branch that they're in a flow which creates a new `SharedTree` and would like to initialize it.\n\t /\n\treadonly canInitialize: boolean;\n\n\t// TODO: Consider extending this status to include:\n\t// - application-defined metadata about the stored schema\n\t// - details about the differences between the stored and view schema sufficient for implementing \"safe mismatch\" policies\n}\n\n/\n Events for {@link TreeBranch}.\n * @sealed @alpha\n /\nexport interface TreeBranchEvents {\n\t/\n\t The stored schema for the document has changed.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when a change is made to the branch. Includes data about the change that is made which listeners\n\t * can use to filter on changes they care about (e.g. local vs. remote changes).\n\t \n\t @param data - information about the change\n\t * @param getRevertible - a function that allows users to get a revertible for the change. If not provided,\n\t * this change is not revertible.\n\t /\n\tchanged(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n\n\t/\n\t Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t \n\t The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleAlphaFactory): void;\n}\n\n/\n Events for {@link TreeView}.\n * @sealed @public\n /\nexport interface TreeViewEvents {\n\t/\n\t Raised whenever {@link TreeView.root} is invalidated.\n\t \n\t This includes changes to the document schema.\n\t * It also includes changes to the field containing the root such as setting or clearing an optional root or changing which node is the root.\n\t * This does NOT include changes to the content (fields/children) of the root node: for that case subscribe to events on the root node.\n\t /\n\trootChanged(): void;\n\n\t/\n\t The stored schema for the document has changed.\n\t * This may affect the compatibility between the view schema and the stored schema, and thus the ability to use the view.\n\t \n\t @remarks\n\t * This event implies that the old {@link TreeView.root} is no longer valid, but applications need not handle that separately:\n\t * {@link TreeViewEvents.rootChanged} will be fired after this event.\n\t /\n\tschemaChanged(): void;\n\n\t/\n\t Fired when:\n\t * - a local commit is applied outside of a transaction\n\t * - a local transaction is committed\n\t \n\t The event is not fired when:\n\t * - a local commit is applied within a transaction\n\t * - a remote commit is applied\n\t \n\t @param data - information about the commit that was applied\n\t * @param getRevertible - a function provided that allows users to get a revertible for the commit that was applied. If not provided,\n\t * this commit is not revertible.\n\t /\n\tcommitApplied(data: CommitMetadata, getRevertible?: RevertibleFactory): void;\n}\n\n/\n Retrieve the {@link TreeViewAlpha \| alpha API} for a {@link TreeView}.\n * @alpha\n */\nexport function asTreeViewAlpha<TSchema extends ImplicitFieldSchema>(\n\tview: TreeView<TSchema>,\n): TreeViewAlpha<TSchema> {\n\treturn view as TreeViewAlpha<TSchema>;\n}\n"]}

package/lib/simple-tree/api/verboseTree.js CHANGED Viewed

@@ -10,7 +10,7 @@ import { NodeKind } from "../core/index.js";
 import { isTreeValue, stackTreeFieldCursor, stackTreeNodeCursor, } from "../../feature-libraries/index.js";
 import { booleanSchema, handleSchema, nullSchema, numberSchema, stringSchema, } from "../leafNodeSchema.js";
 import { isObjectNodeSchema } from "../objectNodeTypes.js";
-import { customFromCursorInner, } from "./customTree.js";
+import { customFromCursor, } from "./customTree.js";
 import { getUnhydratedContext } from "../createContext.js";
 /**
  * Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.
@@ -158,7 +158,7 @@ export function verboseFromCursor(reader, rootSchema, options) {
     return verboseFromCursorInner(reader, config, schemaMap);
 }
 function verboseFromCursorInner(reader, options, schema) {
-    const fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);
+    const fields = customFromCursor(reader, options, schema, verboseFromCursorInner);
     const nodeSchema = schema.get(reader.type) ?? fail("missing schema for type in cursor");
     if (nodeSchema.kind === NodeKind.Leaf) {
         return fields;

package/lib/simple-tree/api/verboseTree.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"verboseTree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/verboseTree.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 type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\taboveRootPlaceholder,\n\tEmptyKey,\n\tkeyAsDetachedField,\n\ttype FieldKey,\n\ttype ITreeCursor,\n\ttype ITreeCursorSynchronous,\n\ttype TreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport { brand, fail } from \"../../util/index.js\";\nimport type {\n\tTreeLeafValue,\n\tImplicitFieldSchema,\n\tImplicitAllowedTypes,\n} from \"../schemaTypes.js\";\nimport { NodeKind, type TreeNodeSchema } from \"../core/index.js\";\nimport {\n\tisTreeValue,\n\tstackTreeFieldCursor,\n\tstackTreeNodeCursor,\n\ttype CursorAdapter,\n} from \"../../feature-libraries/index.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport { isObjectNodeSchema } from \"../objectNodeTypes.js\";\nimport {\n\tcustomFromCursorInner,\n\ttype CustomTreeNode,\n\ttype CustomTreeValue,\n\ttype EncodeOptions,\n} from \"./customTree.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\n\n/\n Verbose encoding of a {@link TreeNode} or {@link TreeLeafValue}.\n * @remarks\n * This is verbose meaning that every {@link TreeNode} is a {@link VerboseTreeNode}.\n * Any IFluidHandle values have been replaced by `THandle`.\n * @privateRemarks\n * This can store all possible simple trees,\n * but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.\n * @alpha\n /\nexport type VerboseTree<THandle = IFluidHandle> =\n\t\| VerboseTreeNode<THandle>\n\t\| Exclude<TreeLeafValue, IFluidHandle>\n\t\| THandle;\n\n/\n Verbose encoding of a {@link TreeNode}.\n * @remarks\n * This is verbose meaning that every {@link TreeNode} has an explicit `type` property, and `fields`.\n * This allowed VerboseTreeNode to be unambiguous regarding which type each node is without relying on symbols or hidden state.\n \n Any IFluidHandle values have been replaced by `THandle`. If the `THandle` is JSON compatible, then this type is JSON compatible as well.\n \n @privateRemarks\n * This type is only used for data which is copied into and out of the tree.\n * When being copied out, its fine to have the data be mutable since its a copy.\n \n When being copied in, we don't need to mutate, so we could use a readonly variant of this type.\n * however the copy in case (createFromVerbose) probably isn't harmed much by just reusing this type as is,\n * since if the caller has immutable data, TypeScript doesn't prevent assigning immutable data to a mutable type anyway.\n * Also relaxing the input methods to take readonly data would be a non-breaking change so it can be done later if desired.\n \n This format is simple-tree specialized alternative to {@link JsonableTree}.\n * This format allows for all simple-tree compatible trees to be represented.\n \n Unlike `JsonableTree`, leaf nodes are not boxed into node objects, and instead have their schema inferred from the value.\n * Additionally, sequence fields can only occur on a node that has a single sequence field (with the empty key)\n * replicating the behavior of simple-tree ArrayNodes.\n * @alpha\n /\nexport interface VerboseTreeNode<THandle = IFluidHandle> {\n\t/\n\t The meaning of this node.\n\t * Provides contexts/semantics for this node and its content.\n\t * @remarks\n\t * Typically used to associate a node with metadata (including a schema) and source code (types, behaviors, etc).\n\t * When used with this package's schema system, it will be the {@link TreeNodeSchemaCore.identifier}.\n\t /\n\ttype: string;\n\n\t/\n\t Content of this node.\n\t * For array nodes, an array of children.\n\t * For map and object nodes, an object which children under keys.\n\t * @remarks\n\t * For object nodes, the keys could be either the stored keys, or the property keys depending on usage.\n\t /\n\tfields:\n\t\t\| VerboseTree<THandle>[]\n\t\t\| {\n\t\t\t\t[key: string]: VerboseTree<THandle>;\n\t\t };\n}\n\n/\n Options for how to interpret a `VerboseTree<TCustom>` when schema information is available.\n * @alpha\n /\nexport interface ParseOptions<TCustom> {\n\t/\n\t Fixup custom input formats.\n\t * @remarks\n\t * Main usage is to handle IFluidHandles.\n\t * When targeting JSON compatibility,\n\t * this may be by throwing an error or including a placeholder.\n\t * Since IFluidHandles are special references to FLuid data which is garbage collected when not referenced by the container for long enough,\n\t * any scheme for encoding handles for storage outside the container (or in formats the container does not understand) is unreliable.\n\t /\n\tvalueConverter(data: VerboseTree<TCustom>): TreeLeafValue \| VerboseTreeNode<TCustom>;\n\t/\n\t If true, interpret the input keys of object nodes as stored keys.\n\t * If false, interpret them as property keys.\n\t * @defaultValue false.\n\t /\n\treadonly useStoredKeys?: boolean;\n}\n\n/\n Options for how to interpret a `VerboseTree<TCustom>` without relying on schema.\n /\nexport interface SchemalessParseOptions<TCustom> {\n\t/\n\t Fixup custom input formats.\n\t * @remarks\n\t * See note on {@link ParseOptions.valueConverter}.\n\t /\n\tvalueConverter(data: VerboseTree<TCustom>): TreeLeafValue \| VerboseTreeNode<TCustom>;\n\t/\n\t Converts stored keys into whatever key the tree is using in its encoding.\n\t /\n\tkeyConverter?: {\n\t\tparse(type: string, inputKey: string): FieldKey;\n\t\tencode(type: string, key: FieldKey): string;\n\t};\n}\n\n/\n Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.\n /\nexport function applySchemaToParserOptions<TCustom>(\n\tschema: ImplicitFieldSchema,\n\toptions: ParseOptions<TCustom>,\n): SchemalessParseOptions<TCustom> {\n\tconst config: Required<ParseOptions<TCustom>> = {\n\t\tuseStoredKeys: false,\n\t\t...options,\n\t};\n\n\tconst context = getUnhydratedContext(schema);\n\n\treturn {\n\t\tvalueConverter: config.valueConverter,\n\t\tkeyConverter: config.useStoredKeys\n\t\t\t? undefined\n\t\t\t: {\n\t\t\t\t\tencode: (type, key: FieldKey): string => {\n\t\t\t\t\t\t// translate stored key into property key.\n\t\t\t\t\t\tconst simpleNodeSchema = context.schema.get(brand(type)) ?? fail(\"missing schema\");\n\t\t\t\t\t\tif (isObjectNodeSchema(simpleNodeSchema)) {\n\t\t\t\t\t\t\tconst propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);\n\t\t\t\t\t\t\tif (propertyKey !== undefined) {\n\t\t\t\t\t\t\t\treturn propertyKey;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t// Looking up an out of schema key.\n\t\t\t\t\t\t\t// This must point to a non-existent field.\n\t\t\t\t\t\t\t// It's possible that the key, if we returned it unmodified, could point to some data\n\t\t\t\t\t\t\t// (for example if looking up a key which is a stored key already when using property keys).\n\t\t\t\t\t\t\t// Thus return an arbitrary key that was selected randomly, so should not exist on non-adversarial data:\n\t\t\t\t\t\t\tconst arbitrary = \"arbitrary unused key: fe71614a-bf3e-43b3-b7b0-4cef39538e90\";\n\t\t\t\t\t\t\tassert(\n\t\t\t\t\t\t\t\t!simpleNodeSchema.storedKeyToPropertyKey.has(brand(arbitrary)),\n\t\t\t\t\t\t\t\t0xa13 / arbitrarily selected unused key was actually used /,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\treturn arbitrary;\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn key;\n\t\t\t\t\t},\n\t\t\t\t\tparse: (type, inputKey): FieldKey => {\n\t\t\t\t\t\tconst simpleNodeSchema = context.schema.get(brand(type)) ?? fail(\"missing schema\");\n\t\t\t\t\t\tif (isObjectNodeSchema(simpleNodeSchema)) {\n\t\t\t\t\t\t\tconst info =\n\t\t\t\t\t\t\t\tsimpleNodeSchema.flexKeyMap.get(inputKey) ?? fail(\"missing field info\");\n\t\t\t\t\t\t\treturn info.storedKey;\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn brand(inputKey);\n\t\t\t\t\t},\n\t\t\t\t},\n\t};\n}\n\n/\n Used to read a VerboseTree as a node cursor.\n \n @returns an {@link ITreeCursorSynchronous} for a single node in nodes mode.\n /\nexport function cursorFromVerbose<TCustom>(\n\tdata: VerboseTree<TCustom>,\n\toptions: SchemalessParseOptions<TCustom>,\n): ITreeCursorSynchronous {\n\treturn stackTreeNodeCursor(verboseTreeAdapter(options), data);\n}\n\n/\n Used to read a VerboseTree[] as a field cursor.\n \n @returns an {@link ITreeCursorSynchronous} for a single field in fields mode.\n /\nexport function fieldCursorFromVerbose<TCustom>(\n\tdata: VerboseTree<TCustom>[],\n\toptions: SchemalessParseOptions<TCustom>,\n): ITreeCursorSynchronous {\n\treturn stackTreeFieldCursor(\n\t\tverboseTreeAdapter(options),\n\t\t{ type: aboveRootPlaceholder, fields: data },\n\t\tkeyAsDetachedField(EmptyKey),\n\t);\n}\n\nfunction verboseTreeAdapter<TCustom>(\n\toptions: SchemalessParseOptions<TCustom>,\n): CursorAdapter<VerboseTree<TCustom>> {\n\treturn {\n\t\tvalue: (input: VerboseTree<TCustom>) => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\treturn isTreeValue(node) ? node : undefined;\n\t\t},\n\t\ttype: (input: VerboseTree<TCustom>) => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\tswitch (typeof node) {\n\t\t\t\tcase \"number\":\n\t\t\t\t\treturn numberSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tcase \"string\":\n\t\t\t\t\treturn stringSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tcase \"boolean\":\n\t\t\t\t\treturn booleanSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tdefault:\n\t\t\t\t\tif (node === null) {\n\t\t\t\t\t\treturn nullSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\t\t}\n\t\t\t\t\tif (isFluidHandle(node)) {\n\t\t\t\t\t\treturn handleSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\t\t}\n\t\t\t\t\treturn node.type as TreeNodeSchemaIdentifier;\n\t\t\t}\n\t\t},\n\t\tkeysFromNode: (input: VerboseTree<TCustom>): readonly FieldKey[] => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\tswitch (typeof node) {\n\t\t\t\tcase \"object\": {\n\t\t\t\t\tif (node === null) {\n\t\t\t\t\t\treturn [];\n\t\t\t\t\t}\n\t\t\t\t\tif (isFluidHandle(node)) {\n\t\t\t\t\t\treturn [];\n\t\t\t\t\t}\n\t\t\t\t\tif (Array.isArray(node.fields)) {\n\t\t\t\t\t\treturn node.fields.length === 0 ? [] : [EmptyKey];\n\t\t\t\t\t}\n\n\t\t\t\t\tconst inputKeys = Object.keys(node.fields);\n\t\t\t\t\tconst converter = options.keyConverter;\n\t\t\t\t\tif (converter === undefined) {\n\t\t\t\t\t\treturn inputKeys as FieldKey[];\n\t\t\t\t\t}\n\t\t\t\t\treturn inputKeys.map((k) => converter.parse(node.type, k));\n\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\treturn [];\n\t\t\t}\n\t\t},\n\t\tgetFieldFromNode: (\n\t\t\tinput: VerboseTree<TCustom>,\n\t\t\tkey: FieldKey,\n\t\t): readonly VerboseTree<TCustom>[] => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\t// Object.prototype.hasOwnProperty can return true for strings (ex: with key \"0\"), so we have to filter them out.\n\t\t\t// Rather than just special casing strings, we can handle them with an early return for all primitives.\n\t\t\tif (typeof node !== \"object\") {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (node === null) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (isFluidHandle(node)) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (Array.isArray(node.fields)) {\n\t\t\t\treturn key === EmptyKey ? node.fields : [];\n\t\t\t}\n\n\t\t\tconst convertedKey =\n\t\t\t\toptions.keyConverter === undefined ? key : options.keyConverter.encode(node.type, key);\n\n\t\t\tif (Object.prototype.hasOwnProperty.call(node.fields, convertedKey)) {\n\t\t\t\tconst field = node.fields[convertedKey];\n\t\t\t\treturn field === undefined ? [] : [field];\n\t\t\t}\n\n\t\t\treturn [];\n\t\t},\n\t};\n}\n\n/\n Used to read a node cursor as a VerboseTree.\n */\nexport function verboseFromCursor<TCustom>(\n\treader: ITreeCursor,\n\trootSchema: ImplicitAllowedTypes,\n\toptions: EncodeOptions<TCustom>,\n): VerboseTree<TCustom> {\n\tconst config: Required<EncodeOptions<TCustom>> = {\n\t\tuseStoredKeys: false,\n\t\t...options,\n\t};\n\n\tconst schemaMap = getUnhydratedContext(rootSchema).schema;\n\n\treturn verboseFromCursorInner(reader, config, schemaMap);\n}\n\nfunction verboseFromCursorInner<TCustom>(\n\treader: ITreeCursor,\n\toptions: Required<EncodeOptions<TCustom>>,\n\tschema: ReadonlyMap<string, TreeNodeSchema>,\n): VerboseTree<TCustom> {\n\tconst fields = customFromCursorInner(reader, options, schema, verboseFromCursorInner);\n\tconst nodeSchema = schema.get(reader.type) ?? fail(\"missing schema for type in cursor\");\n\tif (nodeSchema.kind === NodeKind.Leaf) {\n\t\treturn fields as CustomTreeValue<TCustom>;\n\t}\n\n\treturn {\n\t\ttype: reader.type,\n\t\tfields: fields as CustomTreeNode<TCustom>,\n\t};\n}\n"]}
1	+ {"version":3,"file":"verboseTree.js","sourceRoot":"","sources":["../../../src/simple-tree/api/verboseTree.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 type { IFluidHandle } from \"@fluidframework/core-interfaces\";\nimport { isFluidHandle } from \"@fluidframework/runtime-utils/internal\";\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\taboveRootPlaceholder,\n\tEmptyKey,\n\tkeyAsDetachedField,\n\ttype FieldKey,\n\ttype ITreeCursor,\n\ttype ITreeCursorSynchronous,\n\ttype TreeNodeSchemaIdentifier,\n} from \"../../core/index.js\";\nimport { brand, fail } from \"../../util/index.js\";\nimport type {\n\tTreeLeafValue,\n\tImplicitFieldSchema,\n\tImplicitAllowedTypes,\n} from \"../schemaTypes.js\";\nimport { NodeKind, type TreeNodeSchema } from \"../core/index.js\";\nimport {\n\tisTreeValue,\n\tstackTreeFieldCursor,\n\tstackTreeNodeCursor,\n\ttype CursorAdapter,\n} from \"../../feature-libraries/index.js\";\nimport {\n\tbooleanSchema,\n\thandleSchema,\n\tnullSchema,\n\tnumberSchema,\n\tstringSchema,\n} from \"../leafNodeSchema.js\";\nimport { isObjectNodeSchema } from \"../objectNodeTypes.js\";\nimport {\n\tcustomFromCursor,\n\ttype CustomTreeNode,\n\ttype CustomTreeValue,\n\ttype EncodeOptions,\n} from \"./customTree.js\";\nimport { getUnhydratedContext } from \"../createContext.js\";\n\n/\n Verbose encoding of a {@link TreeNode} or {@link TreeLeafValue}.\n * @remarks\n * This is verbose meaning that every {@link TreeNode} is a {@link VerboseTreeNode}.\n * Any IFluidHandle values have been replaced by `THandle`.\n * @privateRemarks\n * This can store all possible simple trees,\n * but it can not store all possible trees representable by our internal representations like FlexTree and JsonableTree.\n * @alpha\n /\nexport type VerboseTree<THandle = IFluidHandle> =\n\t\| VerboseTreeNode<THandle>\n\t\| Exclude<TreeLeafValue, IFluidHandle>\n\t\| THandle;\n\n/\n Verbose encoding of a {@link TreeNode}.\n * @remarks\n * This is verbose meaning that every {@link TreeNode} has an explicit `type` property, and `fields`.\n * This allowed VerboseTreeNode to be unambiguous regarding which type each node is without relying on symbols or hidden state.\n \n Any IFluidHandle values have been replaced by `THandle`. If the `THandle` is JSON compatible, then this type is JSON compatible as well.\n \n @privateRemarks\n * This type is only used for data which is copied into and out of the tree.\n * When being copied out, its fine to have the data be mutable since its a copy.\n \n When being copied in, we don't need to mutate, so we could use a readonly variant of this type.\n * however the copy in case (createFromVerbose) probably isn't harmed much by just reusing this type as is,\n * since if the caller has immutable data, TypeScript doesn't prevent assigning immutable data to a mutable type anyway.\n * Also relaxing the input methods to take readonly data would be a non-breaking change so it can be done later if desired.\n \n This format is simple-tree specialized alternative to {@link JsonableTree}.\n * This format allows for all simple-tree compatible trees to be represented.\n \n Unlike `JsonableTree`, leaf nodes are not boxed into node objects, and instead have their schema inferred from the value.\n * Additionally, sequence fields can only occur on a node that has a single sequence field (with the empty key)\n * replicating the behavior of simple-tree ArrayNodes.\n * @alpha\n /\nexport interface VerboseTreeNode<THandle = IFluidHandle> {\n\t/\n\t The meaning of this node.\n\t * Provides contexts/semantics for this node and its content.\n\t * @remarks\n\t * Typically used to associate a node with metadata (including a schema) and source code (types, behaviors, etc).\n\t * When used with this package's schema system, it will be the {@link TreeNodeSchemaCore.identifier}.\n\t /\n\ttype: string;\n\n\t/\n\t Content of this node.\n\t * For array nodes, an array of children.\n\t * For map and object nodes, an object which children under keys.\n\t * @remarks\n\t * For object nodes, the keys could be either the stored keys, or the property keys depending on usage.\n\t /\n\tfields:\n\t\t\| VerboseTree<THandle>[]\n\t\t\| {\n\t\t\t\t[key: string]: VerboseTree<THandle>;\n\t\t };\n}\n\n/\n Options for how to interpret a `VerboseTree<TCustom>` when schema information is available.\n * @alpha\n /\nexport interface ParseOptions<TCustom> {\n\t/\n\t Fixup custom input formats.\n\t * @remarks\n\t * Main usage is to handle IFluidHandles.\n\t * When targeting JSON compatibility,\n\t * this may be by throwing an error or including a placeholder.\n\t * Since IFluidHandles are special references to FLuid data which is garbage collected when not referenced by the container for long enough,\n\t * any scheme for encoding handles for storage outside the container (or in formats the container does not understand) is unreliable.\n\t /\n\tvalueConverter(data: VerboseTree<TCustom>): TreeLeafValue \| VerboseTreeNode<TCustom>;\n\t/\n\t If true, interpret the input keys of object nodes as stored keys.\n\t * If false, interpret them as property keys.\n\t * @defaultValue false.\n\t /\n\treadonly useStoredKeys?: boolean;\n}\n\n/\n Options for how to interpret a `VerboseTree<TCustom>` without relying on schema.\n /\nexport interface SchemalessParseOptions<TCustom> {\n\t/\n\t Fixup custom input formats.\n\t * @remarks\n\t * See note on {@link ParseOptions.valueConverter}.\n\t /\n\tvalueConverter(data: VerboseTree<TCustom>): TreeLeafValue \| VerboseTreeNode<TCustom>;\n\t/\n\t Converts stored keys into whatever key the tree is using in its encoding.\n\t /\n\tkeyConverter?: {\n\t\tparse(type: string, inputKey: string): FieldKey;\n\t\tencode(type: string, key: FieldKey): string;\n\t};\n}\n\n/\n Use info from `schema` to convert `options` to {@link SchemalessParseOptions}.\n /\nexport function applySchemaToParserOptions<TCustom>(\n\tschema: ImplicitFieldSchema,\n\toptions: ParseOptions<TCustom>,\n): SchemalessParseOptions<TCustom> {\n\tconst config: Required<ParseOptions<TCustom>> = {\n\t\tuseStoredKeys: false,\n\t\t...options,\n\t};\n\n\tconst context = getUnhydratedContext(schema);\n\n\treturn {\n\t\tvalueConverter: config.valueConverter,\n\t\tkeyConverter: config.useStoredKeys\n\t\t\t? undefined\n\t\t\t: {\n\t\t\t\t\tencode: (type, key: FieldKey): string => {\n\t\t\t\t\t\t// translate stored key into property key.\n\t\t\t\t\t\tconst simpleNodeSchema = context.schema.get(brand(type)) ?? fail(\"missing schema\");\n\t\t\t\t\t\tif (isObjectNodeSchema(simpleNodeSchema)) {\n\t\t\t\t\t\t\tconst propertyKey = simpleNodeSchema.storedKeyToPropertyKey.get(key);\n\t\t\t\t\t\t\tif (propertyKey !== undefined) {\n\t\t\t\t\t\t\t\treturn propertyKey;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t// Looking up an out of schema key.\n\t\t\t\t\t\t\t// This must point to a non-existent field.\n\t\t\t\t\t\t\t// It's possible that the key, if we returned it unmodified, could point to some data\n\t\t\t\t\t\t\t// (for example if looking up a key which is a stored key already when using property keys).\n\t\t\t\t\t\t\t// Thus return an arbitrary key that was selected randomly, so should not exist on non-adversarial data:\n\t\t\t\t\t\t\tconst arbitrary = \"arbitrary unused key: fe71614a-bf3e-43b3-b7b0-4cef39538e90\";\n\t\t\t\t\t\t\tassert(\n\t\t\t\t\t\t\t\t!simpleNodeSchema.storedKeyToPropertyKey.has(brand(arbitrary)),\n\t\t\t\t\t\t\t\t0xa13 / arbitrarily selected unused key was actually used /,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\treturn arbitrary;\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn key;\n\t\t\t\t\t},\n\t\t\t\t\tparse: (type, inputKey): FieldKey => {\n\t\t\t\t\t\tconst simpleNodeSchema = context.schema.get(brand(type)) ?? fail(\"missing schema\");\n\t\t\t\t\t\tif (isObjectNodeSchema(simpleNodeSchema)) {\n\t\t\t\t\t\t\tconst info =\n\t\t\t\t\t\t\t\tsimpleNodeSchema.flexKeyMap.get(inputKey) ?? fail(\"missing field info\");\n\t\t\t\t\t\t\treturn info.storedKey;\n\t\t\t\t\t\t}\n\t\t\t\t\t\treturn brand(inputKey);\n\t\t\t\t\t},\n\t\t\t\t},\n\t};\n}\n\n/\n Used to read a VerboseTree as a node cursor.\n \n @returns an {@link ITreeCursorSynchronous} for a single node in nodes mode.\n /\nexport function cursorFromVerbose<TCustom>(\n\tdata: VerboseTree<TCustom>,\n\toptions: SchemalessParseOptions<TCustom>,\n): ITreeCursorSynchronous {\n\treturn stackTreeNodeCursor(verboseTreeAdapter(options), data);\n}\n\n/\n Used to read a VerboseTree[] as a field cursor.\n \n @returns an {@link ITreeCursorSynchronous} for a single field in fields mode.\n /\nexport function fieldCursorFromVerbose<TCustom>(\n\tdata: VerboseTree<TCustom>[],\n\toptions: SchemalessParseOptions<TCustom>,\n): ITreeCursorSynchronous {\n\treturn stackTreeFieldCursor(\n\t\tverboseTreeAdapter(options),\n\t\t{ type: aboveRootPlaceholder, fields: data },\n\t\tkeyAsDetachedField(EmptyKey),\n\t);\n}\n\nfunction verboseTreeAdapter<TCustom>(\n\toptions: SchemalessParseOptions<TCustom>,\n): CursorAdapter<VerboseTree<TCustom>> {\n\treturn {\n\t\tvalue: (input: VerboseTree<TCustom>) => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\treturn isTreeValue(node) ? node : undefined;\n\t\t},\n\t\ttype: (input: VerboseTree<TCustom>) => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\tswitch (typeof node) {\n\t\t\t\tcase \"number\":\n\t\t\t\t\treturn numberSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tcase \"string\":\n\t\t\t\t\treturn stringSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tcase \"boolean\":\n\t\t\t\t\treturn booleanSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\tdefault:\n\t\t\t\t\tif (node === null) {\n\t\t\t\t\t\treturn nullSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\t\t}\n\t\t\t\t\tif (isFluidHandle(node)) {\n\t\t\t\t\t\treturn handleSchema.identifier as TreeNodeSchemaIdentifier;\n\t\t\t\t\t}\n\t\t\t\t\treturn node.type as TreeNodeSchemaIdentifier;\n\t\t\t}\n\t\t},\n\t\tkeysFromNode: (input: VerboseTree<TCustom>): readonly FieldKey[] => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\tswitch (typeof node) {\n\t\t\t\tcase \"object\": {\n\t\t\t\t\tif (node === null) {\n\t\t\t\t\t\treturn [];\n\t\t\t\t\t}\n\t\t\t\t\tif (isFluidHandle(node)) {\n\t\t\t\t\t\treturn [];\n\t\t\t\t\t}\n\t\t\t\t\tif (Array.isArray(node.fields)) {\n\t\t\t\t\t\treturn node.fields.length === 0 ? [] : [EmptyKey];\n\t\t\t\t\t}\n\n\t\t\t\t\tconst inputKeys = Object.keys(node.fields);\n\t\t\t\t\tconst converter = options.keyConverter;\n\t\t\t\t\tif (converter === undefined) {\n\t\t\t\t\t\treturn inputKeys as FieldKey[];\n\t\t\t\t\t}\n\t\t\t\t\treturn inputKeys.map((k) => converter.parse(node.type, k));\n\t\t\t\t}\n\t\t\t\tdefault:\n\t\t\t\t\treturn [];\n\t\t\t}\n\t\t},\n\t\tgetFieldFromNode: (\n\t\t\tinput: VerboseTree<TCustom>,\n\t\t\tkey: FieldKey,\n\t\t): readonly VerboseTree<TCustom>[] => {\n\t\t\tconst node = options.valueConverter(input);\n\t\t\t// Object.prototype.hasOwnProperty can return true for strings (ex: with key \"0\"), so we have to filter them out.\n\t\t\t// Rather than just special casing strings, we can handle them with an early return for all primitives.\n\t\t\tif (typeof node !== \"object\") {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (node === null) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (isFluidHandle(node)) {\n\t\t\t\treturn [];\n\t\t\t}\n\n\t\t\tif (Array.isArray(node.fields)) {\n\t\t\t\treturn key === EmptyKey ? node.fields : [];\n\t\t\t}\n\n\t\t\tconst convertedKey =\n\t\t\t\toptions.keyConverter === undefined ? key : options.keyConverter.encode(node.type, key);\n\n\t\t\tif (Object.prototype.hasOwnProperty.call(node.fields, convertedKey)) {\n\t\t\t\tconst field = node.fields[convertedKey];\n\t\t\t\treturn field === undefined ? [] : [field];\n\t\t\t}\n\n\t\t\treturn [];\n\t\t},\n\t};\n}\n\n/\n Used to read a node cursor as a VerboseTree.\n */\nexport function verboseFromCursor<TCustom>(\n\treader: ITreeCursor,\n\trootSchema: ImplicitAllowedTypes,\n\toptions: EncodeOptions<TCustom>,\n): VerboseTree<TCustom> {\n\tconst config: Required<EncodeOptions<TCustom>> = {\n\t\tuseStoredKeys: false,\n\t\t...options,\n\t};\n\n\tconst schemaMap = getUnhydratedContext(rootSchema).schema;\n\n\treturn verboseFromCursorInner(reader, config, schemaMap);\n}\n\nfunction verboseFromCursorInner<TCustom>(\n\treader: ITreeCursor,\n\toptions: Required<EncodeOptions<TCustom>>,\n\tschema: ReadonlyMap<string, TreeNodeSchema>,\n): VerboseTree<TCustom> {\n\tconst fields = customFromCursor(reader, options, schema, verboseFromCursorInner);\n\tconst nodeSchema = schema.get(reader.type) ?? fail(\"missing schema for type in cursor\");\n\tif (nodeSchema.kind === NodeKind.Leaf) {\n\t\treturn fields as CustomTreeValue<TCustom>;\n\t}\n\n\treturn {\n\t\ttype: reader.type,\n\t\tfields: fields as CustomTreeNode<TCustom>,\n\t};\n}\n"]}

package/lib/simple-tree/api/view.d.ts CHANGED Viewed

@@ -2,19 +2,28 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { AdaptedViewSchema, type Adapters, Compatibility, type TreeStoredSchema } from "../../core/index.js";
+import { AdaptedViewSchema, type Adapters, type TreeStoredSchema } from "../../core/index.js";
 import { type FullSchemaPolicy } from "../../feature-libraries/index.js";
+import { type FieldSchema, type ImplicitFieldSchema } from "../schemaTypes.js";
+import type { SchemaCompatibilityStatus } from "./tree.js";
 /**
  * A collection of View information for schema, including policy.
  */
 export declare class ViewSchema {
     readonly policy: FullSchemaPolicy;
     readonly adapters: Adapters;
-    readonly schema: TreeStoredSchema;
     /**
-     * @param schema - Cached conversion of view schema in the stored schema format.
+     * Cached conversion of the view schema in the stored schema format.
      */
-    constructor(policy: FullSchemaPolicy, adapters: Adapters, schema: TreeStoredSchema);
+    private readonly viewSchemaAsStored;
+    /**
+     * Normalized view schema (implicitly allowed view schema types are converted to their canonical form).
+     */
+    readonly schema: FieldSchema;
+    /**
+     * @param viewSchema - Schema for the root field of this view.
+     */
+    constructor(policy: FullSchemaPolicy, adapters: Adapters, viewSchema: ImplicitFieldSchema);
     /**
      * Determines the compatibility of a stored document
      * (based on its stored schema) with a viewer (based on its view schema).
@@ -25,11 +34,7 @@ export declare class ViewSchema {
      * TODO: this API violates the parse don't validate design philosophy.
      * It should be wrapped with (or replaced by) a parse style API.
      */
-    checkCompatibility(stored: TreeStoredSchema): {
-        read: Compatibility;
-        write: Compatibility;
-        writeAllowingStoredSchemaUpdates: Compatibility;
-    };
+    checkCompatibility(stored: TreeStoredSchema): Omit<SchemaCompatibilityStatus, "canInitialize">;
     /**
      * Compute a schema that `original` could be viewed as using adapters as needed.
      *

package/lib/simple-tree/api/view.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/view.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,iBAAiB,~~EACjB~~,KAAK,QAAQ,~~EACb~~,~~aAAa,EAIb,~~KAAK,gBAAgB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,~~EACN~~,KAAK,gBAAgB,~~EAGrB~~,MAAM,kCAAkC,CAAC;~~AAE1C~~;;GAEG;AACH,qBAAa,UAAU;~~aAKL~~,MAAM,EAAE,gBAAgB;aACxB,QAAQ,EAAE,QAAQ;~~aAClB~~,MAAM,EAAE,~~gBAAgB~~;~~IANzC~~;;OAEG;gBAEc,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,QAAQ,~~EAClB~~,~~MAAM~~,EAAE,~~gBAAgB~~;~~IAGzC~~;;;;;;;;;OASG;IACI,kBAAkB,~~CAAC~~,MAAM,EAAE,gBAAgB,~~GAAG;QACpD~~,IAAI,~~EAAE,aAAa,~~CAAC~~;QACpB~~,~~KAAK~~,EAAE,~~aAAa~~,CAAC;~~QACrB,gCAAgC,EAAE,aAAa,CAAC;KAChD;IA6CD~~;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB;~~IA0B7D~~;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,SAAS;CAIjB"}
1	+ {"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/simple-tree/api/view.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,iBAAiB,EAEjB,KAAK,QAAQ,EAGb,KAAK,gBAAgB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEN,KAAK,gBAAgB,EAOrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAEN,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,WAAW,CAAC;AAE3D;;GAEG;AACH,qBAAa,UAAU;aAcL,MAAM,EAAE,gBAAgB;aACxB,QAAQ,EAAE,QAAQ;IAdnC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAmB;IACtD;;OAEG;IACH,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC;;OAEG;gBAEc,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,QAAQ,EAClC,UAAU,EAAE,mBAAmB;IAMhC;;;;;;;;;OASG;IACI,kBAAkB,CACxB,MAAM,EAAE,gBAAgB,GACtB,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC;IAkKnD;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB;IAiC7D;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,SAAS;CAIjB"}

package/lib/simple-tree/api/view.js CHANGED Viewed

@@ -2,20 +2,24 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { AdaptedViewSchema, Compatibility, } from "../../core/index.js";
+import { AdaptedViewSchema, } from "../../core/index.js";
 import { fail } from "../../util/index.js";
-import { allowsRepoSuperset, isNeverTree, } from "../../feature-libraries/index.js";
+import { FieldKinds, getAllowedContentDiscrepancies, isNeverTree, PosetComparisonResult, fieldRealizer, comparePosetElements, } from "../../feature-libraries/index.js";
+import { normalizeFieldSchema, } from "../schemaTypes.js";
+import { toStoredSchema } from "../toStoredSchema.js";
+import { unreachableCase } from "@fluidframework/core-utils/internal";
 /**
  * A collection of View information for schema, including policy.
  */
 export class ViewSchema {
     /**
-     * @param schema - Cached conversion of view schema in the stored schema format.
+     * @param viewSchema - Schema for the root field of this view.
      */
-    constructor(policy, adapters, schema) {
+    constructor(policy, adapters, viewSchema) {
         this.policy = policy;
         this.adapters = adapters;
-        this.schema = schema;
+        this.schema = normalizeFieldSchema(viewSchema);
+        this.viewSchemaAsStored = toStoredSchema(this.schema);
     }
     /**
      * Determines the compatibility of a stored document
@@ -30,42 +34,127 @@ export class ViewSchema {
     checkCompatibility(stored) {
         // TODO: support adapters
         // const adapted = this.adaptRepo(stored);
-        const read = allowsRepoSuperset(this.policy, stored, this.schema)
-            ? Compatibility.Compatible
-            : // TODO: support adapters
-                // : allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-                // ? Compatibility.RequiresAdapters
-                Compatibility.Incompatible;
-        // TODO: Extract subset of adapters that are valid to use on stored
-        // TODO: separate adapters from schema updates
-        const write = allowsRepoSuperset(this.policy, this.schema, stored)
-            ? Compatibility.Compatible
-            : // TODO: support adapters
-                // : allowsRepoSuperset(this.policy, this.storedSchema, adapted.adaptedForViewSchema)
-                // TODO: IThis assumes adapters are bidirectional.
-                //   Compatibility.RequiresAdapters
-                Compatibility.Incompatible;
-        // TODO: compute this properly (and maybe include the set of schema changes needed for it?).
-        // Maybe updates would happen lazily when needed to store data?
-        // When willingness to updates can avoid need for some adapters,
-        // how should it be decided if the adapter should be used to avoid the update?
-        // TODO: is this case actually bi-variant, making this correct if we did it for each schema independently?
-        let writeAllowingStoredSchemaUpdates =
-        // TODO: This should consider just the updates needed
-        // (ex: when view covers a subset of stored after stored has a update to that subset).
-        allowsRepoSuperset(this.policy, stored, this.schema)
-            ? Compatibility.Compatible
-            : // TODO: this assumes adapters can translate in both directions. In general this will not be true.
-                // TODO: this also assumes that schema updates to the adapted repo would translate to
-                // updates on the stored schema, which is also likely untrue.
-                // // TODO: support adapters
-                // allowsRepoSuperset(this.policy, adapted.adaptedForViewSchema, this.storedSchema)
-                // ? Compatibility.RequiresAdapters // Requires schema updates. TODO: consider adapters that can update writes.
-                Compatibility.Incompatible;
-        // Since the above does not consider partial updates,
-        // we can improve the tolerance a bit by considering the op-op update:
-        writeAllowingStoredSchemaUpdates = Math.max(writeAllowingStoredSchemaUpdates, write);
-        return { read, write, writeAllowingStoredSchemaUpdates };
+        // View schema allows a subset of documents that stored schema does, and the discrepancies are allowed by policy
+        // determined by the view schema (i.e. objects with extra optional fields in the stored schema have opted into allowing this.
+        // In the future, this would also include things like:
+        // - fields with more allowed types in the stored schema than in the view schema have out-of-schema "unknown content" adapters
+        let canView = true;
+        // View schema allows a superset of documents that stored schema does, hence the document could be upgraded to use a persisted version
+        // of this view schema as its stored schema.
+        let canUpgrade = true;
+        const updateCompatibilityFromFieldDiscrepancy = (discrepancy) => {
+            switch (discrepancy.mismatch) {
+                case "allowedTypes": {
+                    // Since we only track the symmetric difference between the allowed types in the view and
+                    // stored schemas, it's sufficient to check if any extra allowed types still exist in the
+                    // stored schema.
+                    if (discrepancy.stored.some((identifier) => !isNeverTree(this.policy, stored, stored.nodeSchema.get(identifier)))) {
+                        // Stored schema has extra allowed types that the view schema does not.
+                        canUpgrade = false;
+                        canView = false;
+                    }
+                    if (discrepancy.view.some((identifier) => !isNeverTree(this.policy, this.viewSchemaAsStored, this.viewSchemaAsStored.nodeSchema.get(identifier)))) {
+                        // View schema has extra allowed types that the stored schema does not.
+                        canView = false;
+                    }
+                    break;
+                }
+                case "fieldKind": {
+                    const result = comparePosetElements(discrepancy.stored, discrepancy.view, fieldRealizer);
+                    if (result === PosetComparisonResult.Greater) {
+                        // Stored schema is more relaxed than view schema.
+                        canUpgrade = false;
+                        if (discrepancy.view === FieldKinds.forbidden.identifier &&
+                            discrepancy.identifier !== undefined &&
+                            this.policy.allowUnknownOptionalFields(discrepancy.identifier)) {
+                            // When the application has opted into it, we allow viewing documents which have additional
+                            // optional fields in the stored schema that are not present in the view schema.
+                        }
+                        else {
+                            canView = false;
+                        }
+                    }
+                    if (result === PosetComparisonResult.Less) {
+                        // View schema is more relaxed than stored schema.
+                        canView = false;
+                    }
+                    if (result === PosetComparisonResult.Incomparable) {
+                        canUpgrade = false;
+                        canView = false;
+                    }
+                    break;
+                }
+                case "valueSchema": {
+                    canView = false;
+                    canUpgrade = false;
+                    break;
+                }
+                default:
+                    unreachableCase(discrepancy);
+            }
+        };
+        for (const discrepancy of getAllowedContentDiscrepancies(this.viewSchemaAsStored, stored)) {
+            if (!canView && !canUpgrade) {
+                break;
+            }
+            switch (discrepancy.mismatch) {
+                case "nodeKind": {
+                    const viewNodeSchema = this.viewSchemaAsStored.nodeSchema.get(discrepancy.identifier);
+                    const storedNodeSchema = stored.nodeSchema.get(discrepancy.identifier);
+                    // We conservatively do not allow node types to change.
+                    // The only time this might be valid in the sense that the data canonically converts is converting an object node
+                    // to a map node over the union of all the object fields' types.
+                    if (discrepancy.stored === undefined) {
+                        const viewIsNever = viewNodeSchema !== undefined
+                            ? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+                            : true;
+                        if (!viewIsNever) {
+                            // View schema has added a node type that the stored schema doesn't know about.
+                            canView = false;
+                        }
+                    }
+                    else if (discrepancy.view === undefined) {
+                        const storedIsNever = storedNodeSchema !== undefined
+                            ? isNeverTree(this.policy, stored, storedNodeSchema)
+                            : true;
+                        if (!storedIsNever) {
+                            // Stored schema has a node type that the view schema doesn't know about.
+                            canUpgrade = false;
+                        }
+                    }
+                    else {
+                        // Node type exists in both schemas but has changed. We conservatively never allow this.
+                        const storedIsNever = storedNodeSchema !== undefined
+                            ? isNeverTree(this.policy, stored, storedNodeSchema)
+                            : true;
+                        const viewIsNever = viewNodeSchema !== undefined
+                            ? isNeverTree(this.policy, this.viewSchemaAsStored, viewNodeSchema)
+                            : true;
+                        if (!storedIsNever || !viewIsNever) {
+                            canView = false;
+                            canUpgrade = false;
+                        }
+                    }
+                    break;
+                }
+                case "valueSchema":
+                case "allowedTypes":
+                case "fieldKind": {
+                    updateCompatibilityFromFieldDiscrepancy(discrepancy);
+                    break;
+                }
+                case "fields": {
+                    discrepancy.differences.forEach(updateCompatibilityFromFieldDiscrepancy);
+                    break;
+                }
+                // No default
+            }
+        }
+        return {
+            canView,
+            canUpgrade,
+            isEquivalent: canView && canUpgrade,
+        };
     }
     /**
      * Compute a schema that `original` could be viewed as using adapters as needed.
@@ -79,7 +168,7 @@ export class ViewSchema {
         // and its impossible for an adapter to be correctly implemented if its output type is never
         // (unless its input is also never).
         for (const adapter of this.adapters?.tree ?? []) {
-            if (isNeverTree(this.policy, this.schema, this.schema.nodeSchema.get(adapter.output))) {
+            if (isNeverTree(this.policy, this.viewSchemaAsStored, this.viewSchemaAsStored.nodeSchema.get(adapter.output))) {
                 fail("tree adapter for stored adapter.output should not be never");
             }
         }