@colyseus/schema 5.0.0 → 5.0.2

package/build/types/HelperTypes.d.ts

@@ -66,8 +66,14 @@ export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends
 } ? StreamSchema<InstanceType<ChildType>> : T extends {
     stream: infer ChildType;
 } ? StreamSchema<ChildType> : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
+type OptionalBuilderKeys<T> = {
+    [K in keyof T]: T[K] extends FieldBuilder<infer V> ? (undefined extends V ? K : never) : never;
+}[keyof T];
+type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
 export type InferSchemaInstanceType<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
+    [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
+} & {
+    [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V> ? V : never;
 } & Schema;
 export type NonFunctionProps<T> = Omit<T, {
     [K in keyof T]: T[K] extends Function ? K : never;
@@ -79,8 +85,17 @@ export type NonFunctionNonPrimitivePropNames<T> = {
     [K in keyof T]: T[K] extends Function ? never : T[K] extends number | string | boolean ? never : K;
 }[keyof T];
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
+type ToJSONField<X> = X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : X extends ArraySchema<infer U> ? ToJSONValue<U>[] : X extends SetSchema<infer U> ? ToJSONValue<U>[] : X extends CollectionSchema<infer U> ? ToJSONValue<U>[] : X extends Schema ? ToJSON<X> : X;
+type ToJSONRequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+type ToJSONOptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T];
 export type ToJSON<T> = NonFunctionProps<{
-    [K in keyof T]: T[K] extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : T[K] extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : T[K] extends ArraySchema<infer U> ? ToJSONValue<U>[] : T[K] extends SetSchema<infer U> ? ToJSONValue<U>[] : T[K] extends CollectionSchema<infer U> ? ToJSONValue<U>[] : T[K] extends Schema ? ToJSON<T[K]> : T[K];
+    [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
+} & {
+    [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
 }>;
 export type IsNever<T> = [T] extends [never] ? true : false;
 /**
@@ -90,6 +105,35 @@ export type IsNever<T> = [T] extends [never] ? true : false;
  * - Collections can be assigned from their JSON representations
  */
 export type AssignableProps<T> = {
-    [K in NonFunctionPropNames<T>]?: T[K] extends MapSchema<infer U> ? MapSchema<U> | Record<string, U extends Schema ? (U | AssignableProps<U>) : U> : T[K] extends ArraySchema<infer U> ? ArraySchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends SetSchema<infer U> ? SetSchema<U> | Set<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends CollectionSchema<infer U> ? CollectionSchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends Schema ? T[K] | AssignableProps<T[K]> : T[K];
+    [K in NonFunctionPropNames<T>]?: AssignableValue<T[K]>;
+};
+/**
+ * Value-level assignment shape shared by `AssignableProps` and
+ * `BuilderInitProps`. Captures the "you can pass the real instance, or the
+ * plain-object / array shape" pattern.
+ */
+export type AssignableValue<V> = V extends MapSchema<infer U> ? MapSchema<U> | Record<string, U extends Schema ? (U | AssignableProps<U>) : U> : V extends ArraySchema<infer U> ? ArraySchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends SetSchema<infer U> ? SetSchema<U> | Set<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends CollectionSchema<infer U> ? CollectionSchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends Schema ? V | AssignableProps<V> : V;
+export type RefHasDefault<C> = C extends {
+    prototype: {
+        initialize(...args: infer P): any;
+    };
+} ? (P extends readonly [] ? true : false) : true;
+type FieldValue<F> = F extends FieldBuilder<infer V, boolean, boolean> ? V : F extends new (...args: any[]) => infer I ? (I extends Schema ? I : never) : never;
+type KeyClass<T, K extends keyof T> = T[K] extends FieldBuilder<unknown, infer D extends boolean, infer O extends boolean> ? (D extends true ? "optional" : O extends true ? "optional" : "required") : T[K] extends new (...args: any[]) => Schema ? (RefHasDefault<T[K]> extends true ? "optional" : "required") : "none";
+export type BuilderRequiredKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "required" ? K : never;
+}[keyof T];
+export type BuilderOptionalKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "optional" ? K : never;
+}[keyof T];
+/**
+ * Constructor/init-props type for a schema() fields map. Required fields
+ * (primitives without `.default()` or `.optional()`, and Schema refs with
+ * non-zero-arg `initialize()`) are `:`; everything else is `?:`.
+ */
+export type BuilderInitProps<T> = {
+    [K in BuilderRequiredKeys<T>]: AssignableValue<FieldValue<T[K]>>;
+} & {
+    [K in BuilderOptionalKeys<T>]?: AssignableValue<Exclude<FieldValue<T[K]>, undefined>>;
 };
 export {};

package/build/types/builder.d.ts

@@ -22,6 +22,7 @@ export interface BuilderDefinition {
     deprecatedThrows?: boolean;
     static?: boolean;
     stream?: boolean;
+    optional?: boolean;
     /** Declaration-scope priority callback for `.stream()` fields. */
     streamPriority?: (view: any, element: any) => number;
 }
@@ -32,11 +33,25 @@ export type BuilderOf<T> = FieldBuilder<T>;
 /**
  * Chainable field builder. Instances are produced by `t.*()` factories.
  *
- * The generic parameter T is the runtime/JS type of the field (e.g. `number`,
- * `string`, `ArraySchema<Item>`). schema() reads the internal configuration
- * via `toDefinition()` and wires up metadata through the existing pipeline.
+ * Generics:
+ *  - `T` is the runtime/JS type of the field (e.g. `number`, `string`,
+ *    `ArraySchema<Item>`). `.optional()` widens it to `T | undefined`
+ *    so the inferred instance/toJSON shapes reflect absence.
+ *  - `HasDefault` is a compile-time flag that the field carries a
+ *    construction-time default — either an explicit `.default(v)` or an
+ *    auto-default from a collection factory (`t.array`, `t.map`, …) or a
+ *    Schema ref whose `initialize` takes zero args.
+ *  - `IsOptional` is a compile-time brand for `.optional()`. Both
+ *    `HasDefault` and `IsOptional` make the field omittable in
+ *    `BuilderInitProps<T>`. A separate brand (rather than reading
+ *    `undefined extends V`) sidesteps a TypeScript quirk where
+ *    class-generic-inferred `V` resolves `undefined extends V` as `true`
+ *    even for non-undefined types.
+ *
+ * schema() reads the internal configuration via `toDefinition()` and wires
+ * up metadata through the existing pipeline.
  */
-export declare class FieldBuilder<T = unknown> {
+export declare class FieldBuilder<T = unknown, HasDefault extends boolean = false, IsOptional extends boolean = false> {
     readonly [$builder]: true;
     _type: DefinitionType;
     _default: any;
@@ -49,10 +64,11 @@ export declare class FieldBuilder<T = unknown> {
     _deprecatedThrows: boolean;
     _static: boolean;
     _stream: boolean;
+    _optional: boolean;
     _streamPriority: ((view: any, element: any) => number) | undefined;
     constructor(type: DefinitionType);
     /** Provide a default value for this field. */
-    default(value: T): this;
+    default(value: T): FieldBuilder<T, true, IsOptional>;
     /** Tag this field with a view tag (DEFAULT_VIEW_TAG when called without arg). */
     view(tag?: number): this;
     /** Mark this field as owned (encoder-side ownership filtering). */
@@ -107,52 +123,66 @@ export declare class FieldBuilder<T = unknown> {
     priority<V = any>(fn: (view: any, element: V) => number): this;
     /** Mark this field as deprecated. Pass `false` to silence the access error. */
     deprecated(throws?: boolean): this;
+    /**
+     * Mark this field as optional — inferred instance type becomes
+     * `T | undefined` and the property becomes omittable in initialization
+     * props. Skips the auto-instantiation of collection / Schema-ref
+     * defaults, so the field starts as `undefined` at runtime.
+     */
+    optional(): FieldBuilder<T | undefined, HasDefault, true>;
     toDefinition(): BuilderDefinition;
 }
 export declare function isBuilder(value: any): value is FieldBuilder<any>;
 export type ChildType = RawPrimitiveType | Constructor<Schema> | FieldBuilder<any>;
 interface ArrayFactory {
-    <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>>;
-    <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>>;
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>, true, false>;
 }
 interface MapFactory {
-    <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>>;
-    <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>>;
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>, true, false>;
 }
 interface SetFactory {
-    <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>>;
-    <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>>;
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>, true, false>;
 }
 interface CollectionFactory {
-    <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>>;
-    <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>>;
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>, true, false>;
 }
 interface StreamFactory {
-    <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>>;
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>, true, false>;
+}
+type RefHasDefault<C> = C extends {
+    prototype: {
+        initialize(...args: infer P): any;
+    };
+} ? (P extends readonly [] ? true : false) : true;
+interface RefFactory {
+    <C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
 }
-declare function refFactory<C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>>;
 export declare const t: Readonly<{
-    string: () => FieldBuilder<string>;
-    number: () => FieldBuilder<number>;
-    boolean: () => FieldBuilder<boolean>;
-    int8: () => FieldBuilder<number>;
-    uint8: () => FieldBuilder<number>;
-    int16: () => FieldBuilder<number>;
-    uint16: () => FieldBuilder<number>;
-    int32: () => FieldBuilder<number>;
-    uint32: () => FieldBuilder<number>;
-    int64: () => FieldBuilder<number>;
-    uint64: () => FieldBuilder<number>;
-    float32: () => FieldBuilder<number>;
-    float64: () => FieldBuilder<number>;
-    bigint64: () => FieldBuilder<bigint>;
-    biguint64: () => FieldBuilder<bigint>;
+    string: () => FieldBuilder<string, false, false>;
+    number: () => FieldBuilder<number, false, false>;
+    boolean: () => FieldBuilder<boolean, false, false>;
+    int8: () => FieldBuilder<number, false, false>;
+    uint8: () => FieldBuilder<number, false, false>;
+    int16: () => FieldBuilder<number, false, false>;
+    uint16: () => FieldBuilder<number, false, false>;
+    int32: () => FieldBuilder<number, false, false>;
+    uint32: () => FieldBuilder<number, false, false>;
+    int64: () => FieldBuilder<number, false, false>;
+    uint64: () => FieldBuilder<number, false, false>;
+    float32: () => FieldBuilder<number, false, false>;
+    float64: () => FieldBuilder<number, false, false>;
+    bigint64: () => FieldBuilder<bigint, false, false>;
+    biguint64: () => FieldBuilder<bigint, false, false>;
     /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
-    ref: typeof refFactory;
+    ref: RefFactory;
     array: ArrayFactory;
     map: MapFactory;
     set: SetFactory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {

package/src/Metadata.ts

@@ -17,6 +17,7 @@ export type MetadataField = {
     owned?: boolean,
     static?: boolean,
     stream?: boolean,
+    optional?: boolean,
 };
 
 export type Metadata =

package/src/Reflection.ts

@@ -52,8 +52,8 @@ export const Reflection = schema({
     types: t.array(ReflectionType),
     rootType: t.number(),
 }, "Reflection") as ReturnType<typeof schema<{
-    types: FieldBuilder<ArraySchema<ReflectionType>>;
-    rootType: FieldBuilder<number>;
+    types: FieldBuilder<ArraySchema<ReflectionType>, true, false>;
+    rootType: FieldBuilder<number, false, false>;
 }>> & ReflectionStatic;
 
 export type Reflection = SchemaType<typeof Reflection>;

package/src/annotations.ts

@@ -9,7 +9,7 @@ import { TypeDefinition, getType } from "./types/registry.js";
 import { OPERATION } from "./encoding/spec.js";
 import { TypeContext } from "./types/TypeContext.js";
 import { assertInstanceType, assertType, EncodeSchemaError } from "./encoding/assert.js";
-import type { InferValueType, InferSchemaInstanceType, AssignableProps, IsNever } from "./types/HelperTypes.js";
+import type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderInitProps, IsNever } from "./types/HelperTypes.js";
 import { CollectionSchema } from "./types/custom/CollectionSchema.js";
 import { SetSchema } from "./types/custom/SetSchema.js";
 import { StreamSchema } from "./types/custom/StreamSchema.js";
@@ -529,9 +529,13 @@ export function deprecated(throws: boolean = true): PropertyDecorator {
     }
 }
 
-// Helper type to extract InitProps from initialize method
-// Supports both single object parameter and multiple parameters
-// If no initialize method is specified, use AssignableProps for field initialization
+// Helper type to extract InitProps from initialize method.
+// - Non-empty initialize params: use them directly.
+// - Zero-arg initialize: no args accepted (`never`) — user-supplied field
+//   values would be dropped at runtime (parent's initialize is skipped
+//   during child construction via the `new.target === klass` guard, and
+//   own-field auto-assignment happens only inside initialize).
+// - No initialize at all: derive from fields map.
 type ExtractInitProps<T> = T extends { initialize: (...args: infer P) => void }
     ? P extends readonly []
         ? never
@@ -540,28 +544,40 @@ type ExtractInitProps<T> = T extends { initialize: (...args: infer P) => void }
                 ? First
                 : P
             : P
-    : AssignableProps<InferSchemaInstanceType<T>>;
+    : BuilderInitProps<T>;
 
-// Helper type to determine if InitProps should be required
-type IsInitPropsRequired<T> = T extends { initialize: (props: any) => void }
-    ? true
-    : T extends { initialize: (...args: infer P) => void }
-        ? P extends readonly []
-            ? false
-            : true
-        : false;
+// Does the init-props shape have at least one required property?
+type HasRequiredKeys<X> = {} extends X ? false : true;
+
+// Whether the constructor's init-props argument must be supplied.
+// Mirrors the cases inside ExtractInitProps: non-empty initialize params
+// are required; zero-arg initialize accepts nothing; no initialize
+// depends on whether the derived BuilderInitProps has any required keys.
+type IsInitPropsRequired<T> = T extends { initialize: (...args: infer P) => void }
+    ? P extends readonly []
+        ? false
+        : true
+    : HasRequiredKeys<BuilderInitProps<T>>;
+
+// Whether T declares any non-empty `initialize` method. Used to tighten
+// the constructor signature: authors who write an explicit `initialize()`
+// with args opt into strict required args. Without an initialize the sig
+// also allows `[]` so the common `new X(); x.field = ...` pattern works.
+type HasExplicitInit<T> = T extends { initialize: (...args: infer P) => void }
+    ? P extends readonly [] ? false : true
+    : false;
 
 /**
  * A `schema()` field definition accepts a FieldBuilder, a Schema subclass
  * (shorthand for `t.ref(Class)`), or a method (attached to the prototype).
  */
-export type FieldsAndMethods = Record<string, FieldBuilder<any> | (new (...args: any[]) => Schema) | Function>;
+export type FieldsAndMethods = Record<string, FieldBuilder<any, boolean, boolean> | (new (...args: any[]) => Schema) | Function>;
 
 export interface SchemaWithExtends<T, P extends typeof Schema> {
     extend: <T2 extends FieldsAndMethods = FieldsAndMethods>(
         fields: T2 & ThisType<InferSchemaInstanceType<T & T2>>,
         name?: string,
-    ) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T2>, P>;
+    ) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
 }
 
 /**
@@ -582,7 +598,22 @@ export interface SchemaWithExtendsConstructor<
     P extends typeof Schema
 > extends SchemaWithExtends<T, P> {
     '~type': InferSchemaInstanceType<T>;
-    new (...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : IsInitPropsRequired<T> extends true ? [InitProps] : [InitProps?]): InferSchemaInstanceType<T> & InstanceType<P>;
+    // Constructor signature:
+    //  - InitProps = never (zero-arg initialize): no args.
+    //  - InitProps is a tuple (multi-arg initialize): spread it.
+    //  - Explicit `initialize(arg)` with required args: strict [InitProps]
+    //    — the author opted into requiring them.
+    //  - No initialize, but required builder fields: allow `[]` or
+    //    `[InitProps]`. Preserves `new X(); x.field = ...` while still
+    //    flagging incomplete-object mistakes like `new X({ hp: 1 })`.
+    //  - Otherwise: optional single-arg.
+    new (...args:
+        [InitProps] extends [never] ? []
+        : InitProps extends readonly any[] ? InitProps
+        : HasExplicitInit<T> extends true ? [InitProps]
+        : IsInitPropsRequired<T> extends true ? ([] | [InitProps])
+        : [InitProps?]
+    ): InferSchemaInstanceType<T> & InstanceType<P>;
     prototype: InferSchemaInstanceType<T> & InstanceType<P> & {
         initialize(...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : [InitProps]): void;
     };
@@ -627,6 +658,7 @@ export function schema<
     const staticFields: string[] = [];
     const streamFields: string[] = [];
     const streamPriorityFields: { [field: string]: (view: any, element: any) => number } = {};
+    const optionalFields: string[] = [];
 
     for (const fieldName in fieldsAndMethods) {
         const value: any = (fieldsAndMethods as any)[fieldName];
@@ -643,11 +675,13 @@ export function schema<
             if (def.static) { staticFields.push(fieldName); }
             if (def.stream) { streamFields.push(fieldName); }
             if (def.streamPriority !== undefined) { streamPriorityFields[fieldName] = def.streamPriority; }
+            if (def.optional) { optionalFields.push(fieldName); }
 
             if (def.hasDefault) {
                 defaultValues[fieldName] = def.default;
-            } else {
+            } else if (!def.optional) {
                 // Auto-instantiate collection/Schema defaults when none is provided.
+                // `.optional()` opts out — field starts as undefined.
                 const rawType: any = def.type;
                 if (rawType && typeof rawType === "object") {
                     if (rawType.array !== undefined) {
@@ -759,6 +793,13 @@ export function schema<
         }
     }
 
+    if (optionalFields.length > 0) {
+        const metadata = (klass as any)[Symbol.metadata] as Metadata;
+        for (const fieldName of optionalFields) {
+            metadata[metadata[fieldName]].optional = true;
+        }
+    }
+
     if (name) {
         Object.defineProperty(klass, "name", { value: name });
     }

package/src/index.ts

@@ -71,7 +71,7 @@ export { t, FieldBuilder, isBuilder, type BuilderDefinition, type ChildType } fr
 export { TypeContext } from "./types/TypeContext.js";
 
 // Helper types for type inference
-export type { InferValueType, InferSchemaInstanceType, AssignableProps } from "./types/HelperTypes.js";
+export type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderInitProps } from "./types/HelperTypes.js";
 
 export { getDecoderStateCallbacks, type CallbackProxy, type SchemaCallback, type CollectionCallback, type SchemaCallbackProxy } from "./decoder/strategy/getDecoderStateCallbacks.js";
 export { Callbacks, StateCallbackStrategy } from "./decoder/strategy/Callbacks.js";

package/src/types/HelperTypes.ts

@@ -80,12 +80,25 @@ export type InferValueType<T> =
 
     : never;
 
+// Keys whose FieldBuilder generic admits `undefined` (i.e. `.optional()` was chained).
+type OptionalBuilderKeys<T> = {
+    [K in keyof T]: T[K] extends FieldBuilder<infer V>
+        ? (undefined extends V ? K : never)
+        : never
+}[keyof T];
+
+type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
+
 export type InferSchemaInstanceType<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<any>
+    [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any>
         ? InferValueType<T[K]>
         : T[K] extends (...args: any[]) => any
             ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K])
             : InferValueType<T[K]>
+} & {
+    [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V>
+        ? V
+        : never
 } & Schema;
 
 export type NonFunctionProps<T> = Omit<T, {
@@ -107,16 +120,28 @@ export type NonFunctionNonPrimitivePropNames<T> = {
 // Helper to recursively convert Schema instances to their JSON representation
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
 
-export type ToJSON<T> = NonFunctionProps<{
-    [K in keyof T]:
-        T[K] extends MapSchema<infer U> ? Record<string, ToJSONValue<U>>
-        : T[K] extends Map<string, infer U> ? Record<string, ToJSONValue<U>>
-        : T[K] extends ArraySchema<infer U> ? ToJSONValue<U>[]
-        : T[K] extends SetSchema<infer U> ? ToJSONValue<U>[]
-        : T[K] extends CollectionSchema<infer U> ? ToJSONValue<U>[]
-        : T[K] extends Schema ? ToJSON<T[K]>
-        : T[K]
-}>;
+type ToJSONField<X> =
+    X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>>
+    : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>>
+    : X extends ArraySchema<infer U> ? ToJSONValue<U>[]
+    : X extends SetSchema<infer U> ? ToJSONValue<U>[]
+    : X extends CollectionSchema<infer U> ? ToJSONValue<U>[]
+    : X extends Schema ? ToJSON<X>
+    : X;
+
+// Keys whose value type admits `undefined` — runtime `toJSON()` omits those,
+// so they surface as `?:` on the JSON shape.
+type ToJSONRequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K
+}[keyof T];
+type ToJSONOptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never
+}[keyof T];
+
+export type ToJSON<T> = NonFunctionProps<
+    & { [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]> }
+    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> }
+>;
 
 // Helper type to check if T is exactly 'never' (meaning no InitProps was provided)
 export type IsNever<T> = [T] extends [never] ? true : false;
@@ -128,15 +153,75 @@ export type IsNever<T> = [T] extends [never] ? true : false;
  * - Collections can be assigned from their JSON representations
  */
 export type AssignableProps<T> = {
-    [K in NonFunctionPropNames<T>]?: T[K] extends MapSchema<infer U>
+    [K in NonFunctionPropNames<T>]?: AssignableValue<T[K]>
+};
+
+/**
+ * Value-level assignment shape shared by `AssignableProps` and
+ * `BuilderInitProps`. Captures the "you can pass the real instance, or the
+ * plain-object / array shape" pattern.
+ */
+export type AssignableValue<V> =
+    V extends MapSchema<infer U>
         ? MapSchema<U> | Record<string, U extends Schema ? (U | AssignableProps<U>) : U>
-        : T[K] extends ArraySchema<infer U>
+        : V extends ArraySchema<infer U>
             ? ArraySchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[])
-            : T[K] extends SetSchema<infer U>
+            : V extends SetSchema<infer U>
                 ? SetSchema<U> | Set<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[])
-                : T[K] extends CollectionSchema<infer U>
+                : V extends CollectionSchema<infer U>
                     ? CollectionSchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[])
-                    : T[K] extends Schema
-                        ? T[K] | AssignableProps<T[K]>
-                        : T[K]
-};
+                    : V extends Schema
+                        ? V | AssignableProps<V>
+                        : V;
+
+// ---------------------------------------------------------------------------
+// BuilderInitProps<T> — init-props shape derived from a schema() fields map.
+// Unlike AssignableProps (fully partial, for `.assign()` updates), this type
+// enforces required vs optional based on per-field `HasDefault` + `undefined`.
+// ---------------------------------------------------------------------------
+
+// Compile-time analogue of schema()'s Schema-ref auto-default rule:
+// if the ref has no `initialize`, or a zero-arg `initialize`, schema()
+// auto-instantiates it — so the field is omittable at construction.
+export type RefHasDefault<C> =
+    C extends { prototype: { initialize(...args: infer P): any } }
+        ? (P extends readonly [] ? true : false)
+        : true;
+
+// Resolve a fields-map entry to its runtime value type.
+type FieldValue<F> =
+    F extends FieldBuilder<infer V, boolean, boolean> ? V
+    : F extends new (...args: any[]) => infer I ? (I extends Schema ? I : never)
+    : never;
+
+// Classify each key of a fields map as "required" / "optional" / "none"
+// (methods). Both `HasDefault = true` and the explicit `.optional()` brand
+// `IsOptional = true` mark the field omittable at construction. The brand
+// sidesteps a TypeScript quirk where `undefined extends V` returned `true`
+// for non-undefined V when V was inferred from a class with T in
+// contravariant + covariant positions.
+type KeyClass<T, K extends keyof T> =
+    T[K] extends FieldBuilder<unknown, infer D extends boolean, infer O extends boolean>
+        ? (D extends true
+            ? "optional"
+            : O extends true ? "optional" : "required")
+        : T[K] extends new (...args: any[]) => Schema
+            ? (RefHasDefault<T[K]> extends true ? "optional" : "required")
+            : "none";
+
+export type BuilderRequiredKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "required" ? K : never
+}[keyof T];
+
+export type BuilderOptionalKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "optional" ? K : never
+}[keyof T];
+
+/**
+ * Constructor/init-props type for a schema() fields map. Required fields
+ * (primitives without `.default()` or `.optional()`, and Schema refs with
+ * non-zero-arg `initialize()`) are `:`; everything else is `?:`.
+ */
+export type BuilderInitProps<T> =
+    & { [K in BuilderRequiredKeys<T>]: AssignableValue<FieldValue<T[K]>> }
+    & { [K in BuilderOptionalKeys<T>]?: AssignableValue<Exclude<FieldValue<T[K]>, undefined>> };