@fluidframework/tree 2.93.0 → 2.101.0

package/docs/user-facing/isolated-declarations.md

@@ -0,0 +1,147 @@
+# Isolated declarations
+
+This document covers TypeScript's `isolatedDeclarations` option, its use in optimizing large TypeScript builds, and the complications that arise in such setups when using SharedTree schema.
+
+The approaches described in this document can be applied to other TypeScript types that are problematic for use with `isolatedDeclarations`: only some minor details are actually specific to SharedTree schema.
+
+## TypeScript background
+
+Official documentation for [TypeScript's isolatedDeclarations](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations).
+
+Added in TypeScript 5.5: [TypeScript: Documentation - TypeScript 5.5](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html#isolated-declarations).
+
+Important for this document is that `isolatedDeclarations` requires that the types of all exported values be determinable without reading any imported files or parsing expressions.
+Specifically, type inference cannot depend on the types of expressions or contents of other files (beyond referring to types imported from them).
+This means that:
+
+- It's possible to emit a `.d.ts` file as a pure function of the input file, without reading any other imported files.
+- The logic needed to do this `.d.ts` emission is relatively simple and practical to implement in third-party tools.
+
+This means it's possible for a build system to compile all required `.d.ts` files in parallel, without any need to respect dependency order between projects.
+Once that is done, all the projects can be type checked in parallel.
+
+This prevents the dependency graph from delaying parts of the build, and can greatly speed up builds with long project dependency chains.
+
+One way to do the first pass (which generates `.d.ts` files) is with the TypeScript compiler, using the following options (requiring at least TypeScript 5.6 for these specific options):
+
+```jsonc
+{
+	"compilerOptions": {
+		// Enable `.d.ts` generation.
+		"declaration": true,
+		// Skip JavaScript emissions: it can be done later.
+		"emitDeclarationOnly": true,
+		// Skip type checking: this is done in the second pass instead.
+		"noCheck": true,
+
+		// Optional: Limit TypeScript to handling simple cases which other tools could also handle.
+		// If compatible with this option,
+		// typically a faster tool than the TypeScript compiler (like oxc) would be used.
+		// If using such a tool, only the second pass would use the TypeScript compiler,
+		// and it would use this option instead.
+		"isolatedDeclarations": true,
+
+		// Optional: Omit `@internal` APIs from `.d.ts` files.
+		"stripInternal": true,
+		// ... Your project will require additional project specific options
+	}
+}
+```
+
+The second pass can then run full type checking (with `noEmit` if using a separate operation to emit the JavaScript files).
+
+Such builds can further be sped up by using a faster third-party tool for the first pass like [oxc's isolatedDeclaration API](https://oxc.rs/docs/guide/usage/transformer/isolated-declarations.html).
+
+## SharedTree schema background
+
+For SharedTree, we require both runtime and compile-time types for schema, and want an easy way to derive the runtime and compile-time types for the TreeNodes from those.
+
+TypeScript provides a few ways to declare both at once without having to repeat it in the code (once as an expression, and once as a type).
+
+- Using the type of an expression, and its value.
+- Using a specific language feature that does both at once, like `class` or `enum`
+
+SharedTree schema use both of these tools together, using `class`. In this example, consider a class named `Foo`:
+
+- The class `Foo` is the schema:
+  - The expression `Foo` is the schema.
+  When the user needs to refer to a node type at runtime, they use the schema to do so.
+  - The type of the schema is `typeof Foo`: this is usually inferred when passing the schema into something, but occasionally explicitly stated.
+- The type `Foo` is the node:
+  - The type named `Foo` is the node type, avoiding the need to add an extra declaration.
+  - This type comes from the non-static members of the class/schema `Foo`, and can be extended with additional class members to express type and runtime data together.
+
+To support recursive schema, schema are occasionally referenced as `() => Foo` to allow forward references.
+
+To avoid limitations in TypeScript `.d.ts` emission for recursive schema — and to get better IntelliSense and error messages — schema must use explicitly named types (like a class or interface) rather than simple `type` declarations.
+
+The portion of the class that directly works with the underlying tree content is generated via `SchemaFactory` so we can control the API for building it and intercept all access to data as needed.
+This also allows common functionality to be shared across all schema classes (such as static implementations of the various schema interfaces for schema reflection, and centralized control of schema scopes and other settings).
+
+## `isolatedDeclarations` and tree schema
+
+`isolatedDeclarations` bans exporting values whose types depend on the types of expressions.
+
+This includes base classes when the base class expression is not simply a single identifier referring to a value with an explicit type.
+
+Thus when both runtime and compile-time data are needed about something, the trick of using an expression and its type is no longer valid.
+
+### Recommended approach:
+
+This assumes the tooling in question is already:
+
+- building a monorepo or large collection of TypeScript projects (often one package per project, but this is not a requirement).
+- using `isolatedDeclarations`.
+- having a separate "emit" phase (for emitting `.d.ts` files) and "type check" phase of the TypeScript build.
+- running all projects' "emit" phase in parallel.
+- wanting to use SharedTree schema in a way that makes it hard to keep this setup.
+
+To add SharedTree schema to such a setup:
+
+- Factor your code to minimize the need to export schema from both files and projects.
+- For schema that are file-exported but not project-exported, mark them as `@internal` and use `stripInternal`.
+  - If inconsistent tagging becomes a problem (package-exported types accidentally referencing tagged types causing type errors that are hard to diagnose), use API Extractor as a linter to validate tagging is done consistently.
+- For projects that still export schema, pick one of:
+    1. Simplify the exported types as much as is practical, including using tools like `eraseSchemaDetails`, and specify the simplified types explicitly.
+       (Recommended if this is easy to do)
+    2. Remove `isolatedDeclarations`, and do the `.d.ts` emission using the TypeScript compiler, keeping the separate emit and type-check passes.
+       This might require delaying this emission until some or all of the dependencies of the project have had their types emitted.
+       This does not require any new dependencies for the full type-checking phase (that can still be fully parallel), nor delaying `.d.ts` emission for projects that reference this one (assuming they still use `isolatedDeclarations`).
+       If picking this option, you likely also want to refactor the code to minimize the size and dependencies of the impacted package.
+       (Recommended when option 1 isn't straightforward, and the project in question isn't exceptionally slow to emit `.d.ts` files using TypeScript using the options listed at the top of this document)
+    3. Explicitly pre-generate the `.d.ts` files.
+       As a last resort (other than disabling the optimized build setup), the `.d.ts` files can be generated the same as the above option. However, instead of generating them during the emit phase, generate them with a separate command and commit them to the repo. During the type check phase of the build, error if they are out of date.
+       (Recommended when the above options (1 and 2) are not suitable)
+
+### Mitigations:
+
+An exhaustive list of things that can be done to mitigate issues related to use of SharedTree schema with `isolatedDeclarations`.
+The recommendations above use a subset of these approaches.
+
+1. Reduce the pain of having to restate types from expressions:
+    - Add types that mirror the runtime APIs, making it practical (and supported — no `@system` types or unnamable types) to express any type explicitly without relying on inferred expression types. SharedTree tries to provide such types, but more may be helpful.
+    - Export fewer types:
+        - Put the code that uses a schema in the same file as the schema (often inside its class as an implementation of an interface for that class)
+        - Type-erase the complex types (which include the actual shared tree fields and similar) before exporting them. See `eraseSchemaDetails()`
+        - If applying mitigation 2 (below), the relevant scopes for minimizing exports change accordingly.
+2. Reduce where the rules of `isolatedDeclarations` apply:
+    - Split up packages or add more tsconfig files within them to allow finer-grained scoping of this option.
+    - If the goal of using `isolatedDeclarations` is to reduce the critical path for type checking packages, then realistically this restriction only needs to apply to types transitively reachable from package exports, not all module exports. Some ways to achieve this:
+        - Use `stripInternal`, then mark offending non-package-exported APIs with `@internal`. Optionally use [API Extractor](https://api-extractor.com/) to ensure types reachable from the non-`@internal` types are not tagged `@internal`.
+        - Get TypeScript to add such an option. It would be nice if TypeScript had a way to restrict the `.d.ts` emission it does to only things reachable from an entry point (or set of entry points) or (as an alternative feature) limit it to types directly in some entry point (and error for referenced types not included in that entry point). If TypeScript had such a feature, it would help with lots of things and would pair well with an option for only applying `isolatedDeclarations` restrictions to types that are included in the entry points. We would also need to confirm the third-party tool being used to generate the `.d.ts` file also could work in these cases.
+        - Use a tool other than TypeScript to enforce `isolatedDeclarations` in a way that reflects your actual needs. For example, whatever tool is actually generating package `.d.ts` files, ensure it does not object to code that violates this rule if it's not package-exported (similar to above), then use that tool itself to enforce the code will work for it rather than also having TypeScript enforce it. Might pair well with a lint rule to flag incompatible exported types (which could be suppressed for non-package-exported ones).
+
+### Solutions:
+
+An exhaustive list of things that can be done to fix issues related to use of SharedTree schema with `isolatedDeclarations`.
+The recommendations above use a subset of these approaches.
+
+- Don't use `isolatedDeclarations` for the tsconfigs that contain files that export schema.
+  - This could be parts of packages, or whole packages. Applying this to portions of packages that contain no package-exported types might handle some use cases well.
+  - You can still do a two-pass build, with the first pass just emitting `.d.ts` files. For projects exporting SharedTree schema, do this using TypeScript instead of a third-party tool, and ensure that the dependencies of these projects have their types emitted first (in dependency order). The second type-checking pass can still be fully parallel.
+- Handwrite all those types, duplicating the data expressed in the expressions (ideally paired with the above mitigations to make this less painful).
+- Use a code generator to produce the needed types. The TypeScript compiler with `emitDeclarationOnly` is such a tool.
+  - This can replace the non-TypeScript tool previously used to emit `.d.ts` files for these cases.
+  - This could generate code that is used by whatever tool would process the TypeScript to emit the `.d.ts`, instead of the developer-written source files.
+  - The files emitted could either be generated as needed (possibly slowing down the processing of dependencies), committed as part of the code (similar to if they were handwritten), or published alongside the code through some other mechanism (like via a package that contains them already generated, as is normal for TypeScript packages).
+- Replace SharedTree's schema language with one that avoids this problem by expressing everything as class members directly without any typed expressions or expression-based inheritance (this would likely be a mess, with many limitations and poor error reporting, but is technically possible).

package/lib/core/change-family/changeFamily.d.ts

@@ -17,6 +17,29 @@ export interface ChangeEncodingContext {
     readonly revision: RevisionTag | undefined;
     readonly idCompressor: IIdCompressor;
     readonly schema?: SchemaAndPolicy;
+    /**
+     * `true` when this context is encoding to or decoding from a summary blob.
+     * `false` when this context is for an op (or any other non-summary path,
+     * including utility encoders that aren't tied to persistence).
+     *
+     * @remarks
+     * Used to gate decode-time recovery behavior — for example, healing of
+     * unresolvable identifier IDs — that should only run when loading a
+     * (possibly broken) attach-summary blob, never when applying ops.
+     */
+    readonly isSummary: boolean;
+    /**
+     * If `true`, identifier values that the local id-compressor cannot resolve
+     * during decode are healed into deterministic stable UUIDs instead of
+     * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.
+     * Only takes effect when `isSummary` is also `true`.
+     */
+    readonly healUnresolvableIdentifiersOnDecode?: boolean;
+    /**
+     * The SharedTree's shared-object id, used as input to the deterministic
+     * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.
+     */
+    readonly sharedObjectId?: string;
 }
 export type ChangeFamilyCodec<TChange> = IJsonCodec<TChange, JsonCompatibleReadOnly, JsonCompatibleReadOnly, ChangeEncodingContext>;
 export interface ChangeFamilyEditor {

package/lib/core/change-family/changeFamily.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}
+{"version":3,"file":"changeFamily.d.ts","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE9E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,kBAAkB,EAAE,OAAO;IACxE,WAAW,CACV,eAAe,EAAE,MAAM,WAAW,EAClC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,KAAK,IAAI,GACrD,OAAO,CAAC;IAEX,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,mCAAmC,CAAC,EAAE,OAAO,CAAC;IACvD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI,UAAU,CAClD,OAAO,EACP,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC;;;;;;;OAOG;IACH,gBAAgB,IAAI,IAAI,CAAC;IAEzB;;;;;;;OAOG;IACH,eAAe,IAAI,IAAI,CAAC;CACxB"}

package/lib/core/change-family/changeFamily.js.map

@@ -1 +1 @@
-{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}
+{"version":3,"file":"changeFamily.js","sourceRoot":"","sources":["../../../src/core/change-family/changeFamily.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { IIdCompressor, SessionId } from \"@fluidframework/id-compressor\";\n\nimport type { ICodecFamily, IJsonCodec } from \"../../codec/index.js\";\nimport type { SchemaAndPolicy } from \"../../core/index.js\";\n// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Referenced by doc comments\nimport type { FieldBatchEncodingContext } from \"../../feature-libraries/index.js\";\nimport type { JsonCompatibleReadOnly } from \"../../util/index.js\";\nimport type { ChangeRebaser, RevisionTag, TaggedChange } from \"../rebase/index.js\";\n\nexport interface ChangeFamily<TEditor extends ChangeFamilyEditor, TChange> {\n\tbuildEditor(\n\t\tmintRevisionTag: () => RevisionTag,\n\t\tchangeReceiver: (change: TaggedChange<TChange>) => void,\n\t): TEditor;\n\n\treadonly rebaser: ChangeRebaser<TChange>;\n\treadonly codecs: ICodecFamily<TChange, ChangeEncodingContext>;\n}\n\nexport interface ChangeEncodingContext {\n\treadonly originatorId: SessionId;\n\treadonly revision: RevisionTag | undefined;\n\treadonly idCompressor: IIdCompressor;\n\treadonly schema?: SchemaAndPolicy;\n\t/**\n\t * `true` when this context is encoding to or decoding from a summary blob.\n\t * `false` when this context is for an op (or any other non-summary path,\n\t * including utility encoders that aren't tied to persistence).\n\t *\n\t * @remarks\n\t * Used to gate decode-time recovery behavior — for example, healing of\n\t * unresolvable identifier IDs — that should only run when loading a\n\t * (possibly broken) attach-summary blob, never when applying ops.\n\t */\n\treadonly isSummary: boolean;\n\t/**\n\t * If `true`, identifier values that the local id-compressor cannot resolve\n\t * during decode are healed into deterministic stable UUIDs instead of\n\t * throwing. See {@link FieldBatchEncodingContext.healUnresolvableIdentifiersOnDecode}.\n\t * Only takes effect when `isSummary` is also `true`.\n\t */\n\treadonly healUnresolvableIdentifiersOnDecode?: boolean;\n\t/**\n\t * The SharedTree's shared-object id, used as input to the deterministic\n\t * UUID derivation when {@link healUnresolvableIdentifiersOnDecode} triggers.\n\t */\n\treadonly sharedObjectId?: string;\n}\n\nexport type ChangeFamilyCodec<TChange> = IJsonCodec<\n\tTChange,\n\tJsonCompatibleReadOnly,\n\tJsonCompatibleReadOnly,\n\tChangeEncodingContext\n>;\n\nexport interface ChangeFamilyEditor {\n\t/**\n\t * Must be called when a new transaction starts.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `exitTransaction` must be made at a later time.\n\t * Can be called repeatedly to indicate the start of nesting transactions.\n\t */\n\tenterTransaction(): void;\n\n\t/**\n\t * Must be called when a transaction ends.\n\t *\n\t * Note: transactions are an optional feature. It is valid to make edits outside of a transaction.\n\t *\n\t * For each call to this function, a matching call to `enterTransaction` must be made at an earlier time.\n\t * Can be called repeatedly to indicate the end of nesting transactions.\n\t */\n\texitTransaction(): void;\n}\n"]}

package/lib/core/tree/detachedFieldIndexCodecV1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAgDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV1.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAEN,KAAK,gBAAgB,EAGrB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAkDpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/lib/core/tree/detachedFieldIndexCodecV1.js

@@ -41,6 +41,8 @@ class MajorCodec {
             originatorId: this.revisionTagCodec.localSessionId,
             idCompressor: this.idCompressor,
             revision: undefined,
+            // DetachedFieldIndex codecs are only used by the summarizer.
+            isSummary: true,
         });
     }
 }

package/lib/core/tree/detachedFieldIndexCodecV1.js.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAI7D,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAIN,iBAAiB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,yCAAyC,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,+BAA+B,EAAE,MAAM,qCAAqC,CAAC;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,MAAM,CACL,EAAE,KAAK,MAAM,IAAI,EAAE,IAAI,CAAC,EACxB,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,MAAM,CACL,KAAK,KAAK,MAAM,IAAI,KAAK,IAAI,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC;IACJ,CAAC;CACD;AAED,MAAM,UAAU,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,yCAAyC,CAC/C,UAAU,EACV,KAAK,CAAC,+BAA+B,CAAC,EAAE,CAAC,EACzC,iBAAiB,CACjB,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || id >= 0,\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || major >= 0,\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}
+{"version":3,"file":"detachedFieldIndexCodecV1.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV1.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAI7D,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAIN,iBAAiB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,yCAAyC,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,+BAA+B,EAAE,MAAM,qCAAqC,CAAC;AAGtF,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C;;;;;;;;;;;;;;;;WAgBG;QACH,MAAM,CACL,EAAE,KAAK,MAAM,IAAI,EAAE,IAAI,CAAC,EACxB,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAyB;QACtC,MAAM,CACL,KAAK,KAAK,MAAM,IAAI,KAAK,IAAI,CAAC,EAC9B,KAAK,CAAC,kEAAkE,CACxE,CAAC;QACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,MAAM,UAAU,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,yCAAyC,CAC/C,UAAU,EACV,KAAK,CAAC,+BAA+B,CAAC,EAAE,CAAC,EACzC,iBAAiB,CACjB,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor } from \"@fluidframework/id-compressor\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport { brand } from \"../../util/index.js\";\nimport {\n\ttype EncodedRevisionTag,\n\ttype RevisionTagCodec,\n\ttype RevisionTag,\n\tRevisionTagSchema,\n} from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major, EncodedRevisionTag> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag {\n\t\tassert(major !== undefined, 0x88e /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\t\t/**\n\t\t * Preface: this codec is only used at summarization time (not for ops).\n\t\t * Note that the decode path must provide a session id in which to interpret the revision tag.\n\t\t * The revision associated with a detached root generally comes from the session which detaches that subtree,\n\t\t * which isn't generally the local session (nor is it available at decode time with the layering of the tree\n\t\t * package), despite decode using the local session id.\n\t\t *\n\t\t * This is made OK by enforcing that all ids on encode/decode are non-local, since local ids won't be interpretable\n\t\t * at decode time.\n\t\t * This assert is valid because the revision for an acked edit will have already been finalized, and a revision\n\t\t * for a local-only edit will be finalizable at summarization time (local edits can only occur on a summarizing client\n\t\t * if they're created while detached, and local ids made while detached are finalized before generating the attach summary).\n\t\t *\n\t\t * WARNING: the above is true when the whole container transitions from detached to attached,\n\t\t * but not when the container is already attached and it's just the shared-tree that is attaching.\n\t\t * The assert below will fail in such a scenario. This is addressed in the v2 codec.\n\t\t */\n\t\tassert(\n\t\t\tid === \"root\" || id >= 0,\n\t\t\t0x88f /* Expected final id on encode of detached field index revision */,\n\t\t);\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || major >= 0,\n\t\t\t0x890 /* Expected final id on decode of detached field index revision */,\n\t\t);\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV1(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tbrand(DetachedFieldIndexFormatVersion.v1),\n\t\tRevisionTagSchema,\n\t);\n}\n"]}

package/lib/core/tree/detachedFieldIndexCodecV2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AAwCpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}
+{"version":3,"file":"detachedFieldIndexCodecV2.d.ts","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,+BAA+B,CAAC;AAG7E,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAsB,gBAAgB,EAAe,MAAM,oBAAoB,CAAC;AAK5F,OAAO,KAAK,EAAE,wBAAwB,EAAS,MAAM,8BAA8B,CAAC;AA0CpF,wBAAgB,8BAA8B,CAC7C,gBAAgB,EAAE,gBAAgB,EAClC,YAAY,EAAE,aAAa,GACzB,cAAc,CAAC,wBAAwB,CAAC,CAO1C"}

package/lib/core/tree/detachedFieldIndexCodecV2.js

@@ -35,6 +35,8 @@ class MajorCodec {
             originatorId: this.revisionTagCodec.localSessionId,
             idCompressor: this.idCompressor,
             revision: undefined,
+            // DetachedFieldIndex codecs are only used by the summarizer.
+            isSummary: true,
         });
     }
 }

package/lib/core/tree/detachedFieldIndexCodecV2.js.map

@@ -1 +1 @@
-{"version":3,"file":"detachedFieldIndexCodecV2.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAKpE,OAAO,EAAE,yCAAyC,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,+BAA+B,EAAE,MAAM,qCAAqC,CAAC;AACtF,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/C,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7B;;;eAGG;YACH,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAoC;QACjD,MAAM,CACL,KAAK,KAAK,MAAM,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAClF,KAAK,CAAC,mDAAmD,CACzD,CAAC;QACF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;SACnB,CAAC,CAAC;IACJ,CAAC;CACD;AAED,MAAM,UAAU,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,yCAAyC,CAC/C,UAAU,EACV,+BAA+B,CAAC,EAAE,EAClC,wBAAwB,CACxB,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor, StableId } from \"@fluidframework/id-compressor\";\nimport { isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport { StableOrFinalRevisionTag } from \"./detachedFieldIndexFormatV2.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag | StableId {\n\t\tassert(major !== undefined, 0xbfb /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\n\t\tif (id !== \"root\" && id < 0) {\n\t\t\t/**\n\t\t\t * This code path handles the case where the major revision is not finalized.\n\t\t\t * This can happen the SharedTree is being attached to an already attached container.\n\t\t\t */\n\t\t\tassert(major !== \"root\", 0xbfc /* Major revision cannot be 'root' */);\n\t\t\tconst long = this.idCompressor.decompress(major);\n\t\t\treturn long;\n\t\t}\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag | StableId): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || (typeof major === \"string\" && isStableId(major)) || major >= 0,\n\t\t\t0xbfd /* Expected root, stable, or final compressed id */,\n\t\t);\n\t\tif (typeof major === \"string\" && isStableId(major)) {\n\t\t\treturn this.idCompressor.recompress(major);\n\t\t}\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV2(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tDetachedFieldIndexFormatVersion.v2,\n\t\tStableOrFinalRevisionTag,\n\t);\n}\n"]}
+{"version":3,"file":"detachedFieldIndexCodecV2.js","sourceRoot":"","sources":["../../../src/core/tree/detachedFieldIndexCodecV2.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAKpE,OAAO,EAAE,yCAAyC,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,+BAA+B,EAAE,MAAM,qCAAqC,CAAC;AACtF,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAG3E,MAAM,UAAU;IACf,YACkB,gBAAkC,EAClC,YAA2B;QAD3B,qBAAgB,GAAhB,gBAAgB,CAAkB;QAClC,iBAAY,GAAZ,YAAY,CAAe;IAC1C,CAAC;IAEG,MAAM,CAAC,KAAY;QACzB,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvE,MAAM,EAAE,GAAG,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAE/C,IAAI,EAAE,KAAK,MAAM,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7B;;;eAGG;YACH,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACtE,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACjD,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,EAAE,CAAC;IACX,CAAC;IAEM,MAAM,CAAC,KAAoC;QACjD,MAAM,CACL,KAAK,KAAK,MAAM,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAClF,KAAK,CAAC,mDAAmD,CACzD,CAAC;QACF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,OAAO,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,EAAE;YAC1C,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,cAAc;YAClD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,QAAQ,EAAE,SAAS;YACnB,6DAA6D;YAC7D,SAAS,EAAE,IAAI;SACf,CAAC,CAAC;IACJ,CAAC;CACD;AAED,MAAM,UAAU,8BAA8B,CAC7C,gBAAkC,EAClC,YAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;IAClE,OAAO,yCAAyC,CAC/C,UAAU,EACV,+BAA+B,CAAC,EAAE,EAClC,wBAAwB,CACxB,CAAC;AACH,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\nimport type { IIdCompressor, StableId } from \"@fluidframework/id-compressor\";\nimport { isStableId } from \"@fluidframework/id-compressor/internal\";\n\nimport type { CodecAndSchema, IJsonCodec } from \"../../codec/index.js\";\nimport type { EncodedRevisionTag, RevisionTagCodec, RevisionTag } from \"../rebase/index.js\";\n\nimport { makeDetachedFieldIndexCodecFromMajorCodec } from \"./detachedFieldIndexCodecCommon.js\";\nimport { DetachedFieldIndexFormatVersion } from \"./detachedFieldIndexFormatCommon.js\";\nimport { StableOrFinalRevisionTag } from \"./detachedFieldIndexFormatV2.js\";\nimport type { DetachedFieldSummaryData, Major } from \"./detachedFieldIndexTypes.js\";\n\nclass MajorCodec implements IJsonCodec<Major> {\n\tpublic constructor(\n\t\tprivate readonly revisionTagCodec: RevisionTagCodec,\n\t\tprivate readonly idCompressor: IIdCompressor,\n\t) {}\n\n\tpublic encode(major: Major): EncodedRevisionTag | StableId {\n\t\tassert(major !== undefined, 0xbfb /* Unexpected undefined revision */);\n\t\tconst id = this.revisionTagCodec.encode(major);\n\n\t\tif (id !== \"root\" && id < 0) {\n\t\t\t/**\n\t\t\t * This code path handles the case where the major revision is not finalized.\n\t\t\t * This can happen the SharedTree is being attached to an already attached container.\n\t\t\t */\n\t\t\tassert(major !== \"root\", 0xbfc /* Major revision cannot be 'root' */);\n\t\t\tconst long = this.idCompressor.decompress(major);\n\t\t\treturn long;\n\t\t}\n\t\treturn id;\n\t}\n\n\tpublic decode(major: EncodedRevisionTag | StableId): RevisionTag {\n\t\tassert(\n\t\t\tmajor === \"root\" || (typeof major === \"string\" && isStableId(major)) || major >= 0,\n\t\t\t0xbfd /* Expected root, stable, or final compressed id */,\n\t\t);\n\t\tif (typeof major === \"string\" && isStableId(major)) {\n\t\t\treturn this.idCompressor.recompress(major);\n\t\t}\n\t\treturn this.revisionTagCodec.decode(major, {\n\t\t\toriginatorId: this.revisionTagCodec.localSessionId,\n\t\t\tidCompressor: this.idCompressor,\n\t\t\trevision: undefined,\n\t\t\t// DetachedFieldIndex codecs are only used by the summarizer.\n\t\t\tisSummary: true,\n\t\t});\n\t}\n}\n\nexport function makeDetachedNodeToFieldCodecV2(\n\trevisionTagCodec: RevisionTagCodec,\n\tidCompressor: IIdCompressor,\n): CodecAndSchema<DetachedFieldSummaryData> {\n\tconst majorCodec = new MajorCodec(revisionTagCodec, idCompressor);\n\treturn makeDetachedFieldIndexCodecFromMajorCodec(\n\t\tmajorCodec,\n\t\tDetachedFieldIndexFormatVersion.v2,\n\t\tStableOrFinalRevisionTag,\n\t);\n}\n"]}

package/lib/feature-libraries/chunked-forest/basicChunk.d.ts

@@ -96,10 +96,27 @@ export declare class BasicChunkCursor extends SynchronousCursor implements Chunk
     atChunkRoot(): boolean;
     fork(): BasicChunkCursor;
     get mode(): CursorLocationType;
+    /**
+     * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+     * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+     * their length should always equal the number of node levels traversed.
+     */
+    private assertChunkStacksMatchNodeDepth;
     getFieldKey(): FieldKey;
     private getStackedFieldKey;
     private getStackedNodeIndex;
-    private getStackedNode;
+    private getStackedChunkIndex;
+    private getStackedChunk;
+    /**
+     * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+     * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+     * only pushed on node-level transitions.
+     *
+     * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+     * current length, which gives the current depth of the node-only stacks.
+     * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+     */
+    private getNodeOnlyHeightFromHeight;
     getFieldLength(): number;
     enterNode(index: number): void;
     getPath(prefix?: PathRootPrefix): UpPath;
@@ -116,6 +133,13 @@ export declare class BasicChunkCursor extends SynchronousCursor implements Chunk
     exitField(): void;
     exitNode(): void;
     private getNode;
+    /**
+     * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+     * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+     * and the result is looked up on the parent node using the current field key.
+     *
+     * @returns The chunks that make up the field the cursor is currently in.
+     */
     private getField;
     get value(): Value;
     get type(): TreeType;

package/lib/feature-libraries/chunked-forest/basicChunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basicChunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/basicChunk.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"basicChunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/basicChunk.ts"],"names":[],"mappings":"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"}

package/lib/feature-libraries/chunked-forest/basicChunk.js

@@ -2,7 +2,7 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { assert, oob, fail } from "@fluidframework/core-utils/internal";
+import { assert, oob, fail, debugAssert } from "@fluidframework/core-utils/internal";
 import { cursorChunk, dummyRoot, } from "../../core/index.js";
 import { ReferenceCountedBase } from "../../util/index.js";
 import { SynchronousCursor, prefixPath } from "../treeCursorUtils.js";
@@ -126,16 +126,21 @@ export class BasicChunkCursor extends SynchronousCursor {
         if (this.nestedCursor !== undefined) {
             return this.nestedCursor.mode;
         }
-        // Compute the number of nodes deep the current depth is.
-        // We want the floor of the result, which can computed using a bitwise shift assuming the depth is less than 2^31, which seems safe.
-        // eslint-disable-next-line no-bitwise
-        const halfHeight = (this.siblingStack.length + 1) >> 1;
-        assert(this.indexOfChunkStack.length === halfHeight, 0x51c /* unexpected indexOfChunkStack */);
-        assert(this.indexWithinChunkStack.length === halfHeight, 0x51d /* unexpected indexWithinChunkStack */);
+        this.assertChunkStacksMatchNodeDepth();
         return this.siblingStack.length % 2 === 0
             ? 1 /* CursorLocationType.Fields */
             : 0 /* CursorLocationType.Nodes */;
     }
+    /**
+     * Asserts that the node-only stacks (`indexOfChunkStack` and `indexWithinChunkStack`) are in sync with `siblingStack`.
+     * Since `siblingStack` interleaves field and node levels while the node-only stacks are pushed/popped only on node-level transitions,
+     * their length should always equal the number of node levels traversed.
+     */
+    assertChunkStacksMatchNodeDepth() {
+        const halfHeight = this.getNodeOnlyHeightFromHeight();
+        assert(this.indexOfChunkStack.length === halfHeight, 0x51c /* unexpected indexOfChunkStack */);
+        assert(this.indexWithinChunkStack.length === halfHeight, 0x51d /* unexpected indexWithinChunkStack */);
+    }
     getFieldKey() {
         if (this.nestedCursor !== undefined) {
             return this.nestedCursor.getFieldKey();
@@ -153,9 +158,30 @@ export class BasicChunkCursor extends SynchronousCursor {
         assert(height >= 0, 0x521 /* must not be above root */);
         return this.indexStack[height] ?? oob();
     }
-    getStackedNode(height) {
-        const index = this.getStackedNodeIndex(height);
-        return this.siblingStack[height][index];
+    getStackedChunkIndex(height) {
+        assert(height % 2 === 1, 0xcf3 /* must be node height */);
+        assert(height >= 0, 0xcf4 /* must not be above root */);
+        return this.indexOfChunkStack[this.getNodeOnlyHeightFromHeight(height)] ?? oob();
+    }
+    getStackedChunk(height) {
+        const index = this.getStackedChunkIndex(height);
+        const chunk = this.siblingStack[height][index];
+        debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+        return chunk;
+    }
+    /**
+     * Converts a {@link height}, which contains field and node levels, into the corresponding depth/index
+     * for the node-only stacks ({@link indexOfChunkStack} and {@link indexWithinChunkStack}), which are
+     * only pushed on node-level transitions.
+     *
+     * @param height - A depth in {@link siblingStack} to convert. Defaults to {@link siblingStack}'s
+     * current length, which gives the current depth of the node-only stacks.
+     * @returns `floor(height / 2)` — the number of node levels at or below the given stack height.
+     */
+    getNodeOnlyHeightFromHeight(height = this.siblingStack.length) {
+        // The bitwise shift computes the floor, which is valid assuming the depth is less than 2^31, which seems safe.
+        // eslint-disable-next-line no-bitwise
+        return height >> 1;
     }
     getFieldLength() {
         if (this.nestedCursor !== undefined) {
@@ -252,6 +278,11 @@ export class BasicChunkCursor extends SynchronousCursor {
         assert(this.mode === 0 /* CursorLocationType.Nodes */, 0x528 /* must be in nodes mode */);
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
+        // Save the chunk array position of the current node. When siblings contain
+        // multi node chunks, the flat node index diverges from the array position,
+        // so getField needs this to locate the parent in the sibling array.
+        this.indexOfChunkStack.push(this.indexOfChunk);
+        this.indexWithinChunkStack.push(this.indexWithinChunk);
         // For fields, siblings are only used for key lookup and
         // nextField and which has arbitrary iteration order,
         // so making a array of just key here works.
@@ -259,6 +290,7 @@ export class BasicChunkCursor extends SynchronousCursor {
         // at the cost of an allocation here.
         this.index = 0;
         this.siblings = [key];
+        this.assertChunkStacksMatchNodeDepth();
     }
     nextField() {
         if (this.nestedCursor !== undefined) {
@@ -281,8 +313,11 @@ export class BasicChunkCursor extends SynchronousCursor {
         }
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
+        this.indexOfChunkStack.push(this.indexOfChunk);
+        this.indexWithinChunkStack.push(this.indexWithinChunk);
         this.index = 0;
         this.siblings = [...fields.keys()]; // TODO: avoid this copy
+        this.assertChunkStacksMatchNodeDepth();
         return true;
     }
     seekNodes(offset) {
@@ -339,12 +374,11 @@ export class BasicChunkCursor extends SynchronousCursor {
         }
         this.siblingStack.push(this.siblings);
         this.indexStack.push(this.index);
-        this.indexOfChunkStack.push(this.indexOfChunk);
-        this.indexWithinChunkStack.push(this.indexWithinChunk);
         this.index = 0;
         this.siblings = siblings;
         this.indexOfChunk = 0;
         this.indexWithinChunk = 0;
+        this.assertChunkStacksMatchNodeDepth();
         this.initNestedCursor();
         return true;
     }
@@ -389,6 +423,12 @@ export class BasicChunkCursor extends SynchronousCursor {
         this.siblings =
             this.siblingStack.pop() ?? fail(0xaf0 /* Unexpected siblingStack.length */);
         this.index = this.indexStack.pop() ?? fail(0xaf1 /* Unexpected indexStack.length */);
+        this.indexOfChunk =
+            this.indexOfChunkStack.pop() ?? fail(0xcf5 /* Unexpected indexOfChunkStack.length */);
+        this.indexWithinChunk =
+            this.indexWithinChunkStack.pop() ??
+                fail(0xcf6 /* Unexpected indexWithinChunkStack.length */);
+        this.assertChunkStacksMatchNodeDepth();
     }
     exitNode() {
         if (this.nestedCursor !== undefined) {
@@ -401,22 +441,35 @@ export class BasicChunkCursor extends SynchronousCursor {
         this.siblings =
             this.siblingStack.pop() ?? fail(0xaf2 /* Unexpected siblingStack.length */);
         this.index = this.indexStack.pop() ?? fail(0xaf3 /* Unexpected indexStack.length */);
-        this.indexOfChunk =
-            this.indexOfChunkStack.pop() ?? fail(0xaf4 /* Unexpected indexOfChunkStack.length */);
-        this.indexWithinChunk =
-            this.indexWithinChunkStack.pop() ??
-                fail(0xaf5 /* Unexpected indexWithinChunkStack.length */);
+        // At the Fields level these aren't semantically used, but reset for consistent state
+        // (so a fully-iterated cursor matches a fresh cursor at the same logical position).
+        this.indexOfChunk = 0;
+        this.indexWithinChunk = 0;
+        this.assertChunkStacksMatchNodeDepth();
     }
     getNode() {
         assert(this.mode === 0 /* CursorLocationType.Nodes */, 0x52f /* can only get node when in node */);
-        return this.siblings[this.index];
+        const chunk = this.siblings[this.indexOfChunk];
+        debugAssert(() => chunk instanceof BasicChunk || "only basic chunks are expected");
+        return chunk;
     }
+    /**
+     * Resolves the chunks that make up the field the cursor is currently in. At the root, this is
+     * {@link root} directly. Otherwise, the cursor must be in {@link CursorLocationType.Fields} mode,
+     * and the result is looked up on the parent node using the current field key.
+     *
+     * @returns The chunks that make up the field the cursor is currently in.
+     */
     getField() {
         if (this.siblingStack.length === 0) {
             return this.root;
         }
         assert(this.mode === 1 /* CursorLocationType.Fields */, 0x530 /* can only get field when in fields */);
-        const parent = this.getStackedNode(this.indexStack.length - 1);
+        // The parent node is the `BasicChunk` in the node array at the top of
+        // `siblingStack` while we are in `CursorLocationType.Fields` mode. We need the parent
+        // since a field's chunks are stored on the parent node's `BasicChunk.fields` map, not on
+        // the cursor itself.
+        const parent = this.getStackedChunk(this.siblingStack.length - 1);
         const key = this.getFieldKey();
         const field = parent.fields.get(key) ?? [];
         return field;