Skip to main content

SchemaStaticsAlpha Interface

Stateless APIs exposed via SchemaFactoryBeta as both instance properties and as statics.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

For more information about our API support guarantees, see here.

Sealed

This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.

Signature​

/** @sealed */
export interface SchemaStaticsAlpha

Properties​

PropertyAlertsModifiersTypeDescription
stagedOptionalAlphareadonly<const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>Creates a field schema that is Optional in the view but behaves as Required in the stored schema during the rollout period of an optional-field migration.
withDefaultAlphareadonly<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; }>Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors, allowing them to be omitted when creating new nodes.
withDefaultRecursiveAlpha<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; }>withDefault except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

Property Details​

stagedOptional​

Creates a field schema that is Optional in the view but behaves as Required in the stored schema during the rollout period of an optional-field migration.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

For more information about our API support guarantees, see here.

Signature​

readonly stagedOptional: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>;

Type: <const T extends ImplicitAllowedTypes, const TCustomMetadata = unknown>(t: T, props?: Omit<FieldPropsAlpha<TCustomMetadata>, "defaultProvider" | "stagedOptionalUpgrade">) => FieldSchemaAlpha<FieldKind.Optional, T, TCustomMetadata, FieldPropsAlpha<TCustomMetadata>>

Remarks​

Use this to incrementally migrate a required field to optional without a coordinated deployment. The migration path is:

  1. Start with sf.required(T) — all clients require the field. 2. Deploy sf.stagedOptional(T) — new clients can read documents where the field is present or absent, but the stored schema stays Required (so old clients are unaffected). Writing undefined is blocked at runtime. 3. Deploy sf.optional(T) once all clients support the staged optional field — the stored schema becomes Optional and the field can be cleared.

Analogous to staged for allowed types, but for field optionality.

withDefault​

Creates a field schema with a default value. Fields with defaults (whether required or optional) are recognized by the type system as optional in constructors, allowing them to be omitted when creating new nodes.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

For more information about our API support guarantees, see here.

Signature​

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;
    }>;

Type: <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; }>

Example​

const MySchema = factory.objectAlpha("MyObject", {
    // Provide values directly
    name: factory.withDefault(factory.required(factory.string), "untitled"),
    count: factory.withDefault(factory.required(factory.number), 0),
    metadata: factory.withDefault(factory.optional(Metadata), new Metadata({ version: 1 })),

    // Use generator functions for dynamic values
    timestamp: factory.withDefault(factory.required(factory.number), () => Date.now()),
    id: factory.withDefault(factory.required(factory.string), () => crypto.randomUUID()),
});

const obj1 = new MySchema({}); // All defaults applied
const obj2 = new MySchema({ name: "custom" }); // name="custom", other defaults applied

withDefaultRecursive​

withDefault except tweaked to work better for recursive types. Use with ValidateRecursiveSchema for improved type safety.

This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.

For more information about our API support guarantees, see here.

Signature​

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;
    }>;

Type: <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; }>

Remarks​

This version of withDefault has fewer type constraints to work around TypeScript limitations, see Unenforced. See ValidateRecursiveSchema for additional information about using recursive schema.

See Also​

SchemaStatics for why this is useful.