@fluidframework/tree 2.90.0 → 2.92.0

package/CHANGELOG.md

@@ -1,5 +1,370 @@
 # @fluidframework/tree
 
+## 2.92.0
+
+### Minor Changes
+
+- The deprecated getBranch API has been removed ([#26796](https://github.com/microsoft/FluidFramework/pull/26796)) [e80a48e25e](https://github.com/microsoft/FluidFramework/commit/e80a48e25ebab540ce9a0093edc12b9aa5ab03fb)
+
+  To obtain a branch-like object, create a view from your tree via `viewWith`.
+  Or, use `TreeAlpha.context` to get a view from a `TreeNode`.
+
+- Array node nodeChanged events now include a delta payload (via TreeAlpha) ([#26677](https://github.com/microsoft/FluidFramework/pull/26677)) [bf02e33aed](https://github.com/microsoft/FluidFramework/commit/bf02e33aed74295840ffa5b6ef889860d58f5654)
+
+  The `nodeChanged` event for array nodes (accessed via `TreeAlpha.on`) now provides a `delta` field, a sequence of `ArrayNodeDeltaOp` values that describe exactly what changed in the array. This lets you efficiently sync an external representation with tree changes, without taking a snapshot of the old state or diffing the entire array.
+
+  The delta follows [Quill](https://quilljs.com/docs/)-style semantics: each op covers a contiguous run of positions in the array before the change.
+  - `{ type: "retain", count: N }`—N elements stayed in place. Their positions are unchanged, though their contents may have changed (which would fire separate `nodeChanged` events on those elements).
+  - `{ type: "insert", count: N }`—N elements were inserted; read their values from the current tree at these positions.
+  - `{ type: "remove", count: N }`—N elements were removed.
+
+  Trailing unchanged elements are not represented by a trailing `"retain"` op.
+
+  Use `TreeAlpha.on` to subscribe to the richer alpha events. The data passed to the callback is typed as `NodeChangedDataAlpha<TNode>`:
+  - Object, map, and record nodes receive `NodeChangedDataProperties` (with a required `changedProperties` set).
+  - Array nodes receive `NodeChangedDataDelta` (with a `delta` field).
+
+  `TreeBeta.on` is unchanged and does not include delta information.
+
+  #### Example: Applying a Delta to a Plain Array Mirror
+
+  ```typescript
+  // Walk the delta to keep a plain JS array in sync with an array node.
+  // retain = advance past unchanged elements,
+  // insert = splice in new elements,
+  // remove = splice out removed elements.
+  const mirror: number[] = [1, 2, 3];
+
+  TreeAlpha.on(myArrayNode, "nodeChanged", ({ delta }) => {
+    let readPos = 0; // position in the current (post-change) tree
+    let writePos = 0; // position in the mirror array
+
+    for (const op of delta ?? []) {
+      if (op.type === "retain") {
+        writePos += op.count;
+        readPos += op.count;
+      } else if (op.type === "insert") {
+        const newItems = Array.from(
+          { length: op.count },
+          (_, i) => myArrayNode[readPos + i],
+        );
+        mirror.splice(writePos, 0, ...newItems);
+        writePos += op.count;
+        readPos += op.count;
+      } else if (op.type === "remove") {
+        mirror.splice(writePos, op.count);
+      }
+    }
+  });
+  ```
+
+  #### Example: Narrowing the Union in a Generic Handler
+
+  ```typescript
+  TreeAlpha.on(node as TreeNode, "nodeChanged", (data) => {
+    if ("delta" in data) {
+      // Array node — data is NodeChangedDataDelta
+      console.log("array changed, delta:", data.delta);
+    } else {
+      // Object/map/record node — data is NodeChangedDataProperties
+      console.log("properties changed:", data.changedProperties);
+    }
+  });
+  ```
+
+  > **Note:** The `delta` value may be `undefined` in two cases:
+  >
+  > - The node was created locally and has not yet been inserted into a document tree (a known temporary limitation).
+  > - The document was updated in a way that required multiple internal change passes in a single operation (for example, a data change combined with a schema upgrade).
+
+- Add TreeArrayNodeAlpha with a new splice method ([#26740](https://github.com/microsoft/FluidFramework/pull/26740)) [f2b0cf9176](https://github.com/microsoft/FluidFramework/commit/f2b0cf917609b84952db2b9492867e70e0d57981)
+
+  Adds a `splice` method on `TreeArrayNodeAlpha` that supports removing and inserting items in a single operation to align with JavaScript's Array splice API.
+  Returns the removed items as an array.
+  Supports negative `start` indices (wraps from end).
+  Optional `deleteCount` (omitting removes everything from `start` onward).
+  The alpha API is accessible by an `asAlpha` cast on existing TreeArrayNodes, or using `schemaFactoryAlpha`.
+  `arrayAlpha` nodes are accepted wherever `TreeArrayNode` is expected, but not the reverse.
+  `asAlpha` is bidirectional since it's the same underlying schema.
+
+  #### Usage
+
+  ```typescript
+  import {
+    SchemaFactory,
+    SchemaFactoryAlpha,
+    asAlpha,
+  } from "@fluidframework/tree";
+
+  // Using asAlpha to cast an existing TreeArrayNode
+  const sf = new SchemaFactory("example");
+  const Inventory = sf.array("Inventory", sf.string);
+  const inventory = new Inventory(["Apples", "Bananas", "Pears"]);
+  const inventoryAlpha = asAlpha(inventory);
+
+  // Using SchemaFactoryAlpha so splice is available directly
+  const sf = new SchemaFactoryAlpha("example");
+  const Inventory = sf.arrayAlpha("Inventory", sf.string);
+  const inventoryAlpha = new Inventory(["Apples", "Bananas", "Pears"]);
+
+  // Remove 2 items starting at index 0, insert new items in their place
+  const removed = inventoryAlpha.splice(0, 2, "Oranges", "Grapes");
+  // removed: ["Apples", "Bananas"]
+  // inventory: ["Oranges", "Grapes", "Pears"]
+
+  // Removed everything from index 1 onward (omitting deleteCount)
+  const rest = inventoryAlpha.splice(1);
+  // rest: ["Grapes", "Pears"]
+  // inventory: ["Oranges"]
+  ```
+
+## 2.91.0
+
+### Minor Changes
+
+- Adds withDefault API to allow defining default values for required and optional fields ([#26502](https://github.com/microsoft/FluidFramework/pull/26502)) [44fdd9421e4](https://github.com/microsoft/FluidFramework/commit/44fdd9421e4d0bfa3cdfa9ab3672ebf3c0ad20a6)
+
+  The `withDefault` API is now available on `SchemaFactoryAlpha`. It allows you to specify default values for fields,
+  making them optional in constructors even when the field is marked as required in the schema.
+  This provides a better developer experience by reducing boilerplate when creating objects.
+
+  The `withDefault` API wraps a field schema and defines a default value to use when the field is not provided during
+  construction. The default value must be of an allowed type of the field. You can provide defaults in two ways:
+  - **A value**: When a value is provided directly, the data is copied for each use to ensure independence between instances
+  - **A generator function**: A function that is called each time to produce a fresh value
+
+  Defaults are evaluated eagerly during node construction.
+
+  #### Required fields with defaults
+
+  ```typescript
+  import { SchemaFactoryAlpha, TreeAlpha } from "@fluidframework/tree/alpha";
+
+  const sf = new SchemaFactoryAlpha("example");
+
+  class Person extends sf.objectAlpha("Person", {
+    name: sf.required(sf.string),
+    age: sf.withDefault(sf.required(sf.number), -1),
+    role: sf.withDefault(sf.required(sf.string), "guest"),
+  }) {}
+
+  // Before: all fields were required
+  // const person = new Person({ name: "Alice", age: -1, role: "guest" });
+
+  // After: fields with defaults are optional
+  const person = new Person({ name: "Alice" });
+  // person.age === -1
+  // person.role === "guest"
+
+  // You can still provide values to override the defaults
+  const admin = new Person({ name: "Bob", age: 30, role: "admin" });
+  ```
+
+  #### Optional fields with custom defaults
+
+  Optional fields (`sf.optional`) already default to `undefined`, but `withDefault` allows you to specify a different
+  default value:
+
+  ```typescript
+  class Config extends sf.object("Config", {
+    timeout: sf.withDefault(sf.optional(sf.number), 5000),
+    retries: sf.withDefault(sf.optional(sf.number), 3),
+  }) {}
+
+  // All fields are optional, using custom defaults when not provided
+  const config = new Config({});
+  // config.timeout === 5000
+  // config.retries === 3
+
+  const customConfig = new Config({ timeout: 10000 });
+  // customConfig.timeout === 10000
+  // customConfig.retries === 3
+  ```
+
+  #### Value defaults vs function defaults
+
+  When you provide a value directly, the data is copied for each use, ensuring each instance is independent:
+
+  ```typescript
+  class Metadata extends sf.object("Metadata", {
+    tags: sf.array(sf.string),
+    version: sf.number,
+  }) {}
+
+  class Article extends sf.object("Article", {
+    title: sf.required(sf.string),
+
+    // a node is provided directly, it is copied for each use
+    metadata: sf.withDefault(
+      sf.optional(Metadata),
+      new Metadata({ tags: [], version: 1 }),
+    ),
+
+    // also works with arrays
+    authors: sf.withDefault(sf.optional(sf.array(sf.string)), []),
+  }) {}
+
+  const article1 = new Article({ title: "First" });
+  const article2 = new Article({ title: "Second" });
+
+  // each article gets its own independent copy
+  assert(article1.metadata !== article2.metadata);
+  article1.metadata.version = 2; // Doesn't affect article2
+  assert(article2.metadata.version === 1);
+  ```
+
+  Alternatively, you can use generator functions to explicitly create new instances:
+
+  ```typescript
+  class Article extends sf.object("Article", {
+    title: sf.required(sf.string),
+
+    // generators are called each time to create a new instance
+    metadata: sf.withDefault(
+      sf.optional(Metadata),
+      () => new Metadata({ tags: [], version: 1 }),
+    ),
+    authors: sf.withDefault(sf.optional(sf.array(sf.string)), () => []),
+  }) {}
+  ```
+
+  Insertable object literals, arrays, and map objects can be used in place of node instances in both static defaults
+  and generator functions:
+
+  ```typescript
+  class Article extends sf.object("Article", {
+    title: sf.required(sf.string),
+
+    // plain object literal instead of new Metadata(...)
+    metadata: sf.withDefault(sf.optional(Metadata), () => ({
+      tags: [],
+      version: 1,
+    })),
+
+    // plain array instead of new ArrayNode(...)
+    authors: sf.withDefault(sf.optional(sf.array(sf.string)), () => [
+      "anonymous",
+    ]),
+  }) {}
+  ```
+
+  ##### Dynamic defaults
+
+  Generator functions are called each time a new node is created, enabling dynamic defaults:
+
+  ```typescript
+  class Document extends sf.object("Document", {
+    id: sf.withDefault(sf.required(sf.string), () => crypto.randomUUID()),
+    title: sf.required(sf.string),
+  }) {}
+
+  const doc1 = new Document({ title: "First Document" });
+  const doc2 = new Document({ title: "Second Document" });
+  // doc1.id !== doc2.id (each gets a unique UUID)
+  ```
+
+  Generator functions also work with primitive types:
+
+  ```typescript
+  let counter = 0;
+
+  class GameState extends sf.object("GameState", {
+    playerId: sf.withDefault(
+      sf.required(sf.string),
+      () => `player-${counter++}`,
+    ),
+    score: sf.withDefault(sf.required(sf.number), () =>
+      Math.floor(Math.random() * 100),
+    ),
+    isActive: sf.withDefault(sf.required(sf.boolean), () => counter % 2 === 0),
+  }) {}
+  ```
+
+  #### Recursive types
+
+  `withDefaultRecursive` is available for use inside recursive schemas. Use `objectRecursiveAlpha` (rather than
+  `objectRecursive`) when defining recursive schemas with defaults, as it correctly makes defaulted fields optional in
+  the constructor for all field kinds including `requiredRecursive`. It works the same as `withDefault` but is
+  necessary to avoid TypeScript's circular reference limitations.
+
+  ```typescript
+  class TreeNode extends sf.objectRecursiveAlpha("TreeNode", {
+    value: sf.number,
+    label: SchemaFactoryAlpha.withDefaultRecursive(
+      sf.optional(sf.string),
+      "untitled",
+    ),
+    child: sf.optionalRecursive([() => TreeNode]),
+  }) {}
+
+  // `label` is optional in the constructor — the default is used when omitted
+  const leaf = new TreeNode({ value: 1 });
+  // leaf.label === "untitled"
+
+  const root = new TreeNode({ value: 0, label: "root", child: leaf });
+  // root.label === "root"
+  // root.child.label === "untitled"
+  ```
+
+  > **Warning:** Be careful about using the recursive type itself as a default value — this is likely to cause
+  > infinite recursion at construction time, since creating the default value would trigger the same default again.
+  > Instead, use a primitive or a separate node type as the default:
+  >
+  > ```typescript
+  > const DefaultTag = sf.objectRecursiveAlpha("Tag", {
+  >   id: sf.number,
+  >   child: sf.optionalRecursive([() => TreeNode]),
+  > });
+  >
+  > class TreeNode extends sf.objectRecursiveAlpha("TreeNode", {
+  >   value: sf.number,
+  >   // ✅ Safe: default is a non-recursive node
+  >   tag: SchemaFactoryAlpha.withDefaultRecursive(
+  >     sf.optional(DefaultTag),
+  >     () => new DefaultTag({ id: 0, child: new DefaultTag({ id: 1 }) }),
+  >   ),
+  >   child: sf.optionalRecursive([() => TreeNode]),
+  > }) {}
+  > ```
+  >
+  > The following definition for child would cause infinite recursion at construction time:
+  >
+  > ```typescript
+  > child: SchemaFactoryAlpha.withDefaultRecursive(
+  >   sf.optionalRecursive([() => TreeNode]),
+  >   () => new TreeNode({ value: 0 }),
+  > );
+  > ```
+
+  > The infinite recursion can be solved by passing in undefined explicitly but it is
+  > recommended to not use defaults in this case:
+  >
+  > ```typescript
+  > child: SchemaFactoryAlpha.withDefaultRecursive(
+  >   sf.optionalRecursive([() => TreeNode]),
+  >   () => new TreeNode({ value: 0, child: undefined }),
+  > );
+  > ```
+
+  #### Type safety
+
+  The default value (or the value returned by a generator function) must be of an allowed type for the field. TypeScript
+  enforces this at compile time:
+
+  ```typescript
+  // ✅ Valid: number default for number field
+  sf.withDefault(sf.optional(sf.number), 8080);
+
+  // ✅ Valid: generator returns string for string field
+  sf.withDefault(sf.optional(sf.string), () => "localhost");
+
+  // ❌ TypeScript error: string default for number field
+  sf.withDefault(sf.optional(sf.number), "8080");
+
+  // ❌ TypeScript error: generator returns number for string field
+  sf.withDefault(sf.optional(sf.string), () => 8080);
+  ```
+
 ## 2.90.0
 
 ### Minor Changes

package/alpha.d.ts

@@ -5,7 +5,7 @@
 
 /*
  * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
- * Generated by "flub generate entrypoints" in @fluid-tools/build-cli.
+ * Generated by "flub generate node10Entrypoints" in @fluid-tools/build-cli.
  */
 
-export * from "./lib/alpha.js";
+export * from "./lib/entrypoints/alpha.js";

package/api-extractor/api-extractor-lint-alpha.cjs.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/alpha.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/entrypoints/alpha.d.ts"
 }

package/api-extractor/api-extractor-lint-alpha.esm.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/alpha.d.ts"
 }

package/api-extractor/api-extractor-lint-beta.cjs.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/beta.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/entrypoints/beta.d.ts"
 }

package/api-extractor/api-extractor-lint-beta.esm.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/beta.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/beta.d.ts"
 }

package/api-extractor/api-extractor-lint-bundle.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/internal.d.ts"
 }

package/api-extractor/api-extractor-lint-legacy.cjs.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/legacy.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/entrypoints/legacy.d.ts"
 }

package/api-extractor/api-extractor-lint-legacy.esm.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/legacy.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/legacy.d.ts"
 }

package/api-extractor/api-extractor-lint-public.cjs.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/dist/public.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/dist/entrypoints/public.d.ts"
 }

package/api-extractor/api-extractor-lint-public.esm.json

@@ -1,5 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-lint.entrypoint.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/public.d.ts"
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/public.d.ts"
 }

package/api-extractor/api-extractor.current.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.current.json",
-	"mainEntryPointFilePath": "<projectFolder>/lib/alpha.d.ts",
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/alpha.d.ts",
 	"apiReport": {
 		// The base config omits alpha. Explicitly opt into alpha reports (in addition to public/beta) for this package.
 		"reportVariants": ["public", "beta", "alpha"]

package/api-extractor/api-extractor.legacy.json

@@ -1,4 +1,5 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.legacy.json"
+	"extends": "<projectFolder>/../../../common/build/build-common/api-extractor-report.esm.legacy.json",
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/legacy.d.ts"
 }

package/api-extractor.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
 	"extends": "../../../common/build/build-common/api-extractor-model.esm.json",
+	"mainEntryPointFilePath": "<projectFolder>/lib/entrypoints/internal.d.ts",
 	"compiler": {
 		// api-extractor has trouble with Node16 moduleResolution, but Bundler looks okay.
 		"overrideTsconfig": {