fluid-framework 2.90.0 → 2.91.0

package/CHANGELOG.md

@@ -1,5 +1,252 @@
 # fluid-framework
 
+## 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/api-report/fluid-framework.alpha.api.md

@@ -307,6 +307,15 @@ export abstract class ErasedBaseType<out Name = unknown> {
     protected abstract brand(dummy: never): Name;
 }
 
+// @alpha
+export type ErasedNode<TExtra, Identifier extends string> = TExtra & TreeNode & WithType<Identifier>;
+
+// @alpha
+export type ErasedSchema<NodeType extends TreeNode> = TreeNodeSchema<NodeType extends WithType<infer Identifier> ? Identifier : string, NodeKind, NodeType, never, false>;
+
+// @alpha
+export type ErasedSchemaSubclassable<TExtra, Identifier extends string> = TreeNodeSchemaClass<Identifier, NodeKind, ErasedNode<TExtra, Identifier>, never, false>;
+
 // @public @sealed
 export abstract class ErasedType<out Name = unknown> {
     static [Symbol.hasInstance](value: never): value is never;
@@ -356,6 +365,18 @@ type FieldHasDefault<T extends ImplicitFieldSchema> = [T] extends [
 FieldSchema<FieldKind.Optional | FieldKind.Identifier>
 ] ? true : false;
 
+// @alpha @system
+export type FieldHasDefaultAlpha<T extends ImplicitFieldSchema> = [
+T
+] extends [FieldSchemaAlpha<infer Kind, infer _Types, infer _Meta, infer TProps>] ? Kind extends FieldKind.Optional | FieldKind.Identifier ? true : TProps extends {
+    defaultProvider: DefaultProvider;
+} ? true : false : FieldHasDefault<T>;
+
+// @alpha @sealed @system
+export type FieldHasDefaultAlphaUnsafe<T extends System_Unsafe.ImplicitFieldSchemaUnsafe> = T extends FieldSchemaAlphaUnsafe<infer Kind, System_Unsafe.ImplicitAllowedTypesUnsafe, unknown, infer TProps> ? Kind extends FieldKind.Optional | FieldKind.Identifier ? true : TProps extends {
+    defaultProvider: DefaultProvider;
+} ? true : false : System_Unsafe.FieldHasDefaultUnsafe<T>;
+
 // @public
 export enum FieldKind {
     Identifier = 2,
@@ -391,7 +412,7 @@ export class FieldSchema<out Kind extends FieldKind = FieldKind, out Types exten
 }
 
 // @alpha @sealed
-export class FieldSchemaAlpha<Kind extends FieldKind = FieldKind, Types extends ImplicitAllowedTypes = ImplicitAllowedTypes, TCustomMetadata = unknown> extends FieldSchema<Kind, Types, TCustomMetadata> implements SimpleFieldSchema<SchemaType.View> {
+export class FieldSchemaAlpha<Kind extends FieldKind = FieldKind, Types extends ImplicitAllowedTypes = ImplicitAllowedTypes, TCustomMetadata = unknown, TProps extends FieldPropsAlpha<TCustomMetadata> | undefined = FieldPropsAlpha<TCustomMetadata> | undefined> extends FieldSchema<Kind, Types, TCustomMetadata> implements SimpleFieldSchema<SchemaType.View> {
     protected constructor(kind: Kind, types: Types, props?: FieldPropsAlpha<TCustomMetadata>);
     readonly allowedTypesFull: AllowedTypesFull;
     // (undocumented)
@@ -403,7 +424,7 @@ export class FieldSchemaAlpha<Kind extends FieldKind = FieldKind, Types extends
 }
 
 // @alpha @sealed @system
-export interface FieldSchemaAlphaUnsafe<out Kind extends FieldKind, out Types extends System_Unsafe.ImplicitAllowedTypesUnsafe, out TCustomMetadata = unknown> extends FieldSchemaAlpha<Kind, any, TCustomMetadata>, System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata> {
+export interface FieldSchemaAlphaUnsafe<out Kind extends FieldKind, out Types extends System_Unsafe.ImplicitAllowedTypesUnsafe, out TCustomMetadata = unknown, out TProps extends FieldPropsAlpha<TCustomMetadata> | undefined = undefined> extends FieldSchemaAlpha<Kind, any, TCustomMetadata, TProps>, System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata> {
     readonly allowedTypes: Types;
 }
 
@@ -838,6 +859,22 @@ type InsertableObjectFromSchemaRecord<T extends RestrictiveStringRecord<Implicit
     readonly [Property in keyof T as FieldHasDefault<T[Property & string]> extends false ? Property : never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
 }>;
 
+// @alpha @system
+export type InsertableObjectFromSchemaRecordAlpha<T extends RestrictiveStringRecord<ImplicitFieldSchema>> = RestrictiveStringRecord<ImplicitFieldSchema> extends T ? {
+    arbitraryKey: "arbitraryValue";
+} extends T ? Record<string, never> : never : FlattenKeys<{
+    readonly [Property in keyof T]?: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+} & {
+    readonly [Property in keyof T as FieldHasDefaultAlpha<T[Property & string]> extends false ? Property : never]: InsertableTreeFieldFromImplicitField<T[Property & string]>;
+}>;
+
+// @alpha @system
+export type InsertableObjectFromSchemaRecordAlphaUnsafe<T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>> = {
+    readonly [Property in keyof T as FieldHasDefaultAlphaUnsafe<T[Property & string]> extends false ? Property : never]: System_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;
+} & {
+    readonly [Property in keyof T as FieldHasDefaultAlphaUnsafe<T[Property & string]> extends true ? Property : never]?: System_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<T[Property & string]>;
+};
+
 // @public
 export type InsertableTreeFieldFromImplicitField<TSchemaInput extends ImplicitFieldSchema, TSchema = UnionToIntersection<TSchemaInput>> = [TSchema] extends [FieldSchema<infer Kind, infer Types>] ? ApplyKindInput<InsertableTreeNodeFromImplicitAllowedTypes<Types>, Kind, true> : [TSchema] extends [ImplicitAllowedTypes] ? InsertableTreeNodeFromImplicitAllowedTypes<TSchema> : never;
 
@@ -1169,6 +1206,9 @@ export enum NodeKind {
     Record = 4
 }
 
+// @alpha @sealed
+export type NodeProvider<T> = T | (() => T);
+
 // @public @sealed
 export interface NodeSchemaMetadata<out TCustomMetadata = unknown> {
     readonly custom?: TCustomMetadata | undefined;
@@ -1199,7 +1239,7 @@ export type ObjectFromSchemaRecord<T extends RestrictiveStringRecord<ImplicitFie
 };
 
 // @alpha @sealed
-export interface ObjectNodeSchema<out TName extends string = string, in out T extends RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>, ImplicitlyConstructable extends boolean = boolean, out TCustomMetadata = unknown> extends TreeNodeSchemaClass<TName, NodeKind.Object, TreeObjectNode<T, TName>, InsertableObjectFromSchemaRecord<T>, ImplicitlyConstructable, T, never, TCustomMetadata>, SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> {
+export interface ObjectNodeSchema<out TName extends string = string, in out T extends RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>, ImplicitlyConstructable extends boolean = boolean, out TCustomMetadata = unknown> extends TreeNodeSchemaClass<TName, NodeKind.Object, TreeObjectNode<T, TName>, object & InsertableObjectFromSchemaRecordAlpha<T>, ImplicitlyConstructable, T, never, TCustomMetadata>, SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> {
     readonly fields: ReadonlyMap<string, FieldSchemaAlpha & SimpleObjectFieldSchema>;
 }
 
@@ -1208,6 +1248,11 @@ export const ObjectNodeSchema: {
     readonly [Symbol.hasInstance]: (value: TreeNodeSchema) => value is ObjectNodeSchema<string, RestrictiveStringRecord<ImplicitFieldSchema>, boolean, unknown>;
 };
 
+// @alpha @sealed
+export type ObjectNodeSchemaWorkaround<TName extends string = string, T extends RestrictiveStringRecord<ImplicitFieldSchema> = RestrictiveStringRecord<ImplicitFieldSchema>, ImplicitlyConstructable extends boolean = boolean, TCustomMetadata = unknown> = ObjectNodeSchema<TName, T, ImplicitlyConstructable, TCustomMetadata> & {
+    readonly createFromInsertable: unknown;
+};
+
 // @beta @input
 export interface ObjectSchemaOptions<TCustomMetadata = unknown> extends NodeSchemaOptions<TCustomMetadata> {
     readonly allowUnknownOptionalFields?: boolean;
@@ -1393,28 +1438,39 @@ export const SchemaFactory_base: SchemaStatics & (new () => SchemaStatics);
 export class SchemaFactoryAlpha<out TScope extends string | undefined = string | undefined, TName extends number | string = string> extends SchemaFactoryBeta<TScope, TName> {
     arrayAlpha<const Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): ArrayNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     arrayRecursive<const Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): ArrayNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
-    static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema<SchemaType>, TCustomMetadata>;
+    static readonly identifier: <const TCustomMetadata = unknown>(props?: Omit<FieldProps<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Identifier, LeafSchema<"string", string> & SimpleLeafNodeSchema<SchemaType>, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     static readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"number", number> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"null", null> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"handle", IFluidHandle_2<unknown>> & SimpleLeafNodeSchema<SchemaType>];
     readonly leaves: readonly [LeafSchema<"string", string> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"number", number> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"boolean", boolean> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"null", null> & SimpleLeafNodeSchema<SchemaType>, LeafSchema<"handle", IFluidHandle_2<unknown>> & SimpleLeafNodeSchema<SchemaType>];
     mapAlpha<Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): MapNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     mapRecursive<Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): MapNodeCustomizableSchemaUnsafe<ScopedSchemaName<TScope, Name>, T, TCustomMetadata>;
-    objectAlpha<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: ObjectSchemaOptionsAlpha<TCustomMetadata>): ObjectNodeSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata> & {
-        readonly createFromInsertable: unknown;
-    };
+    objectAlpha<const Name extends TName, const T extends RestrictiveStringRecord<ImplicitFieldSchema>, const TCustomMetadata = unknown>(name: Name, fields: T, options?: ObjectSchemaOptionsAlpha<TCustomMetadata>): ObjectNodeSchemaWorkaround<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     objectRecursive<const Name extends TName, const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>, const TCustomMetadata = unknown>(name: Name, t: T, options?: ObjectSchemaOptionsAlpha<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & System_Unsafe.InsertableObjectFromSchemaRecordUnsafe<T>, false, T, never, TCustomMetadata> & SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> & Pick<ObjectNodeSchema, "fields">;
-    static readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
-    readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata>;
-    static readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
-    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata>;
+    objectRecursiveAlpha<const Name extends TName, const T extends RestrictiveStringRecord<System_Unsafe.ImplicitFieldSchemaUnsafe>, const TCustomMetadata = unknown>(name: Name, t: T, options?: ObjectSchemaOptionsAlpha<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Object, System_Unsafe.TreeObjectNodeUnsafe<T, ScopedSchemaName<TScope, Name>>, object & InsertableObjectFromSchemaRecordAlphaUnsafe<T>, false, T, never, TCustomMetadata> & SimpleObjectNodeSchema<SchemaType.View, TCustomMetadata> & Pick<ObjectNodeSchema, "fields">;
+    static readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly optional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    static readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly optionalRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     recordAlpha<const Name extends TName, const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): RecordNodeCustomizableSchema<ScopedSchemaName<TScope, Name>, T, true, TCustomMetadata>;
     recordRecursive<Name extends TName, const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(name: Name, allowedTypes: T, options?: NodeSchemaOptionsAlpha<TCustomMetadata>): TreeNodeSchemaClass<ScopedSchemaName<TScope, Name>, NodeKind.Record, TreeRecordNodeUnsafe<T> & WithType<ScopedSchemaName<TScope, Name>, NodeKind.Record, unknown>, {
         readonly [x: string]: System_Unsafe.InsertableTreeNodeFromImplicitAllowedTypesUnsafe<T>;
     }, false, T, undefined, TCustomMetadata>;
-    static readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
-    readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata>;
-    static readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;
-    readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata>;
+    static readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly required: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlpha<FieldKind.Required, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    static readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
+    readonly requiredRecursive: <const T extends System_Unsafe.ImplicitAllowedTypesUnsafe, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider"> | undefined) => FieldSchemaAlphaUnsafe<FieldKind.Required, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;
     scopedFactoryAlpha<const T extends TName, TNameInner extends number | string = string>(name: T): SchemaFactoryAlpha<ScopedSchemaName<TScope, T>, TNameInner>;
+    readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<ApplyKindInput_2<InsertableTreeNodeFromImplicitAllowedTypes_2<Types>, Kind, true>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
+    static readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<ApplyKindInput_2<InsertableTreeNodeFromImplicitAllowedTypes_2<Types>, Kind, true>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
+    readonly withDefaultRecursive: <Kind extends FieldKind, Types extends System_Unsafe.ImplicitAllowedTypesUnsafe, TCustomMetadata = unknown>(fieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>, defaultValue: unknown) => FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
+    static readonly withDefaultRecursive: <Kind extends FieldKind, Types extends System_Unsafe.ImplicitAllowedTypesUnsafe, TCustomMetadata = unknown>(fieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>, defaultValue: unknown) => FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
 }
 
 // @beta
@@ -1458,6 +1514,16 @@ export interface SchemaStatics {
     readonly string: LeafSchema<"string", string>;
 }
 
+// @alpha @sealed @system
+export interface SchemaStaticsAlpha {
+    readonly withDefault: <Kind extends FieldKind, Types extends ImplicitAllowedTypes, TCustomMetadata = unknown>(fieldSchema: FieldSchema<Kind, Types, TCustomMetadata>, defaultValue: NodeProvider<InsertableTreeFieldFromImplicitField<FieldSchema<Kind, Types>>>) => FieldSchemaAlpha<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
+    withDefaultRecursive: <Kind extends FieldKind, Types extends System_Unsafe.ImplicitAllowedTypesUnsafe, TCustomMetadata = unknown>(fieldSchema: System_Unsafe.FieldSchemaUnsafe<Kind, Types, TCustomMetadata>, defaultValue: Unenforced<NodeProvider<System_Unsafe.InsertableTreeFieldFromImplicitFieldUnsafe<System_Unsafe.FieldSchemaUnsafe<Kind, Types>>>>) => FieldSchemaAlphaUnsafe<Kind, Types, TCustomMetadata, FieldPropsAlpha<TCustomMetadata> & {
+        defaultProvider: DefaultProvider;
+    }>;
+}
+
 // @beta @sealed @system
 export interface SchemaStaticsBeta {
     readonly staged: <const T extends LazyItem<TreeNodeSchema>>(t: T | AnnotatedAllowedType<T>) => AnnotatedAllowedType<T>;

package/dist/alpha.d.ts

@@ -209,8 +209,13 @@ export {
 	CreateIndependentTreeAlphaOptions, 
 	DirtyTreeMap, 
 	DirtyTreeStatus, 
+	ErasedNode, 
+	ErasedSchema, 
+	ErasedSchemaSubclassable, 
 	FactoryContent, 
 	FactoryContentObject, 
+	FieldHasDefaultAlpha, 
+	FieldHasDefaultAlphaUnsafe, 
 	FieldPropsAlpha, 
 	FieldSchemaAlpha, 
 	FieldSchemaAlphaUnsafe, 
@@ -228,6 +233,8 @@ export {
 	Insertable, 
 	InsertableContent, 
 	InsertableField, 
+	InsertableObjectFromSchemaRecordAlpha, 
+	InsertableObjectFromSchemaRecordAlphaUnsafe, 
 	JsonArrayNodeSchema, 
 	JsonAsTree, 
 	JsonCompatibleReadOnly, 
@@ -253,8 +260,10 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	NoChangeConstraint, 
+	NodeProvider, 
 	NodeSchemaOptionsAlpha, 
 	ObjectNodeSchema, 
+	ObjectNodeSchemaWorkaround, 
 	ObjectSchemaOptionsAlpha, 
 	ObservationResults, 
 	ReadSchema, 
@@ -267,6 +276,7 @@ export {
 	RevertibleAlphaFactory, 
 	RunTransactionParams, 
 	SchemaFactoryAlpha, 
+	SchemaStaticsAlpha, 
 	SchemaType, 
 	SharedTreeFormatOptions, 
 	SharedTreeOptions, 

package/lib/alpha.d.ts

@@ -209,8 +209,13 @@ export {
 	CreateIndependentTreeAlphaOptions, 
 	DirtyTreeMap, 
 	DirtyTreeStatus, 
+	ErasedNode, 
+	ErasedSchema, 
+	ErasedSchemaSubclassable, 
 	FactoryContent, 
 	FactoryContentObject, 
+	FieldHasDefaultAlpha, 
+	FieldHasDefaultAlphaUnsafe, 
 	FieldPropsAlpha, 
 	FieldSchemaAlpha, 
 	FieldSchemaAlphaUnsafe, 
@@ -228,6 +233,8 @@ export {
 	Insertable, 
 	InsertableContent, 
 	InsertableField, 
+	InsertableObjectFromSchemaRecordAlpha, 
+	InsertableObjectFromSchemaRecordAlphaUnsafe, 
 	JsonArrayNodeSchema, 
 	JsonAsTree, 
 	JsonCompatibleReadOnly, 
@@ -253,8 +260,10 @@ export {
 	MapNodePojoEmulationSchema, 
 	MapNodeSchema, 
 	NoChangeConstraint, 
+	NodeProvider, 
 	NodeSchemaOptionsAlpha, 
 	ObjectNodeSchema, 
+	ObjectNodeSchemaWorkaround, 
 	ObjectSchemaOptionsAlpha, 
 	ObservationResults, 
 	ReadSchema, 
@@ -267,6 +276,7 @@ export {
 	RevertibleAlphaFactory, 
 	RunTransactionParams, 
 	SchemaFactoryAlpha, 
+	SchemaStaticsAlpha, 
 	SchemaType, 
 	SharedTreeFormatOptions, 
 	SharedTreeOptions, 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluid-framework",
-  "version": "2.90.0",
+  "version": "2.91.0",
   "description": "The main entry point into Fluid Framework public packages",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -57,25 +57,25 @@
   "main": "lib/index.js",
   "types": "lib/public.d.ts",
   "dependencies": {
-    "@fluidframework/container-definitions": "~2.90.0",
-    "@fluidframework/container-loader": "~2.90.0",
-    "@fluidframework/core-interfaces": "~2.90.0",
-    "@fluidframework/core-utils": "~2.90.0",
-    "@fluidframework/driver-definitions": "~2.90.0",
-    "@fluidframework/fluid-static": "~2.90.0",
-    "@fluidframework/map": "~2.90.0",
-    "@fluidframework/runtime-utils": "~2.90.0",
-    "@fluidframework/sequence": "~2.90.0",
-    "@fluidframework/shared-object-base": "~2.90.0",
-    "@fluidframework/tree": "~2.90.0"
+    "@fluidframework/container-definitions": "~2.91.0",
+    "@fluidframework/container-loader": "~2.91.0",
+    "@fluidframework/core-interfaces": "~2.91.0",
+    "@fluidframework/core-utils": "~2.91.0",
+    "@fluidframework/driver-definitions": "~2.91.0",
+    "@fluidframework/fluid-static": "~2.91.0",
+    "@fluidframework/map": "~2.91.0",
+    "@fluidframework/runtime-utils": "~2.91.0",
+    "@fluidframework/sequence": "~2.91.0",
+    "@fluidframework/shared-object-base": "~2.91.0",
+    "@fluidframework/tree": "~2.91.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@biomejs/biome": "~1.9.3",
+    "@biomejs/biome": "~2.4.5",
     "@fluid-tools/build-cli": "^0.63.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.63.0",
-    "@fluidframework/eslint-config-fluid": "~2.90.0",
+    "@fluidframework/eslint-config-fluid": "~2.91.0",
     "@microsoft/api-extractor": "7.52.11",
     "@types/node": "~20.19.30",
     "concurrently": "^9.2.1",