@colyseus/schema 4.0.20 → 5.0.1

package/src/annotations.ts

@@ -2,15 +2,18 @@ import "./symbol.shim.js";
 import { Schema } from './Schema.js';
 import { ArraySchema } from './types/custom/ArraySchema.js';
 import { MapSchema } from './types/custom/MapSchema.js';
-import { getNormalizedType, Metadata } from "./Metadata.js";
-import { $changes, $childType, $descriptors, $numFields, $track } from "./types/symbols.js";
+import { getNormalizedType, Metadata, resolveFieldType } from "./Metadata.js";
+import { $changes, $childType, $descriptors, $encoders, $numFields, $track, $values } from "./types/symbols.js";
+import { encode } from "./encoding/encode.js";
 import { TypeDefinition, getType } from "./types/registry.js";
 import { OPERATION } from "./encoding/spec.js";
 import { TypeContext } from "./types/TypeContext.js";
-import { assertInstanceType, assertType } from "./encoding/assert.js";
-import type { InferValueType, InferSchemaInstanceType, AssignableProps, IsNever } from "./types/HelperTypes.js";
+import { assertInstanceType, assertType, EncodeSchemaError } from "./encoding/assert.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";
+import { FieldBuilder, isBuilder } from "./types/builder.js";
 
 export type RawPrimitiveType = "string" |
     "number" |
@@ -33,11 +36,12 @@ export type PrimitiveType = RawPrimitiveType | typeof Schema | object;
 // TODO: infer "default" value type correctly.
 export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T
     | T[]
-    | { type: T, default?: InferValueType<T>, view?: boolean | number, sync?: boolean }
-    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
-    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
-    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean }
-    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean };
+    | { type: T, default?: InferValueType<T>, view?: boolean | number, sync?: boolean, owned?: boolean }
+    | { array: T, default?: ArraySchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
+    | { map: T, default?: MapSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
+    | { collection: T, default?: CollectionSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
+    | { set: T, default?: SetSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean }
+    | { stream: T, default?: StreamSchema<InferValueType<T>>, view?: boolean | number, sync?: boolean, owned?: boolean, priority?: (view: any, element: InferValueType<T>) => number };
 
 export type Definition = { [field: string]: DefinitionType };
 
@@ -220,57 +224,32 @@ export function entity(constructor: any): any {
 
 export function view<T> (tag: number = DEFAULT_VIEW_TAG) {
     return function(target: T, fieldName: string) {
-        const constructor = target.constructor as typeof Schema;
-
-        const parentClass = Object.getPrototypeOf(constructor);
-        const parentMetadata = parentClass[Symbol.metadata];
-
-        // TODO: use Metadata.initialize()
-        const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
-        // const fieldIndex = metadata[fieldName];
-
-        // if (!metadata[fieldIndex]) {
-        //     //
-        //     // detect index for this field, considering inheritance
-        //     //
-        //     metadata[fieldIndex] = {
-        //         type: undefined,
-        //         index: (metadata[$numFields] // current structure already has fields defined
-        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-        //             ?? -1) + 1 // no fields defined
-        //     }
-        // }
-
+        const metadata = Metadata.initialize(target.constructor as typeof Schema);
         Metadata.setTag(metadata, fieldName, tag);
     }
 }
 
+export function owned<T> (target: T, field: string) {
+    const metadata = Metadata.initialize(target.constructor as typeof Schema);
+    metadata[metadata[field]].owned = true;
+}
+
 export function unreliable<T> (target: T, field: string) {
-    //
-    // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
-    //
-    const constructor = target.constructor as typeof Schema;
-
-    const parentClass = Object.getPrototypeOf(constructor);
-    const parentMetadata = parentClass[Symbol.metadata];
-
-    // TODO: use Metadata.initialize()
-    const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
-
-    // if (!metadata[field]) {
-    //     //
-    //     // detect index for this field, considering inheritance
-    //     //
-    //     metadata[field] = {
-    //         type: undefined,
-    //         index: (metadata[$numFields] // current structure already has fields defined
-    //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-    //             ?? -1) + 1 // no fields defined
-    //     }
-    // }
-
-    // add owned flag to the field
-    metadata[metadata[field]].unreliable = true;
+    const metadata = Metadata.initialize(target.constructor as typeof Schema);
+    Metadata.setUnreliable(metadata, field);
+}
+
+/**
+ * @transient — mark a field as not persisted to snapshots (encodeAll /
+ * encodeAllView). Transient fields are still emitted on per-tick patches
+ * (reliable or unreliable), but late-joining clients won't see them until
+ * the next mutation.
+ *
+ * Orthogonal to @unreliable: a field can be either, both, or neither.
+ */
+export function transient<T> (target: T, field: string) {
+    const metadata = Metadata.initialize(target.constructor as typeof Schema);
+    Metadata.setTransient(metadata, field);
 }
 
 export function type (
@@ -341,97 +320,179 @@ export function type (
             );
 
         } else {
-            const complexTypeKlass = typeof(Object.keys(type)[0]) === "string" && getType(Object.keys(type)[0]);
-
-            const childType = (complexTypeKlass)
-                ? Object.values(type)[0]
-                : type;
+            const { complexTypeKlass, childType } = resolveFieldType(type);
 
             Metadata.addField(
                 metadata,
                 fieldIndex,
                 field,
                 type,
-                getPropertyDescriptor(`_${field}`, fieldIndex, childType, complexTypeKlass)
+                getPropertyDescriptor(field, fieldIndex, childType, complexTypeKlass)
             );
         }
-    }
-}
 
-export function getPropertyDescriptor(
-    fieldCached: string,
-    fieldIndex: number,
-    type: DefinitionType,
-    complexTypeKlass: TypeDefinition,
-) {
-    return {
-        get: function (this: Schema) { return this[fieldCached as keyof Schema]; },
-        set: function (this: Schema, value: any) {
-            const previousValue = this[fieldCached as keyof Schema] ?? undefined;
+        // Install accessor descriptor on the prototype (once per class field).
+        if (metadata[$descriptors][field]) {
+            Object.defineProperty(target, field, metadata[$descriptors][field]);
+        }
 
-            // skip if value is the same as cached.
-            if (value === previousValue) { return; }
+        // Pre-compute encoder function for primitive types.
+        if (typeof type === "string") {
+            if (!metadata[$encoders]) {
+                Object.defineProperty(metadata, $encoders, {
+                    value: [],
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            metadata[$encoders][fieldIndex] = (encode as any)[type];
+        }
+    }
+}
 
+// ────────────────────────────────────────────────────────────────────────
+// Per-field-shape specialized setters.
+//
+// Single shared closure used to handle all three shapes (primitive /
+// schema-ref / collection) in one body with many branches. V8's inliner
+// gave up on it because of the size + polymorphism. Splitting into three
+// dedicated factories yields smaller, monomorphic bodies that the JIT can
+// inline into hot setters like `position.x = 100`.
+// ────────────────────────────────────────────────────────────────────────
+
+/** typeof target per primitive type. Cached once, looked up O(1) at decoration. */
+const PRIMITIVE_TYPEOF: Record<string, "number" | "string" | "boolean" | "bigint"> = {
+    number: "number",
+    int8: "number", uint8: "number",
+    int16: "number", uint16: "number",
+    int32: "number", uint32: "number",
+    int64: "number", uint64: "number",
+    float32: "number", float64: "number",
+    bigint64: "bigint", biguint64: "bigint",
+    string: "string",
+    boolean: "boolean",
+};
+
+function makePrimitiveSetter(fieldName: string, fieldIndex: number, type: string) {
+    const typeofTarget = PRIMITIVE_TYPEOF[type]; // undefined for custom types
+    const allowNull = type === "string";
+    const isBool = type === "boolean";
+    return function (this: Schema, value: any) {
+        const values = this[$values];
+        const previousValue = values[fieldIndex];
+        if (value === previousValue) return;
+
+        if (value !== undefined && value !== null) {
+            // Inlined assertType primitive check.
             if (
-                value !== undefined &&
-                value !== null
+                !isBool &&
+                typeofTarget !== undefined &&
+                typeof value !== typeofTarget &&
+                !(allowNull && value === null)
             ) {
-                if (complexTypeKlass) {
-                    // automaticallty transform Array into ArraySchema
-                    if (complexTypeKlass.constructor === ArraySchema && !(value instanceof ArraySchema)) {
-                        value = new ArraySchema(...value);
-                    }
+                const ctorSuffix = (value && value.constructor) ? ` (${value.constructor.name})` : '';
+                throw new EncodeSchemaError(
+                    `a '${typeofTarget}' was expected, but '${JSON.stringify(value)}'${ctorSuffix} was provided in ${this.constructor.name}#${fieldName}`
+                );
+            }
+            (this.constructor as typeof Schema)[$track](this[$changes], fieldIndex, OPERATION.ADD);
+        } else if (previousValue !== undefined && previousValue !== null) {
+            this[$changes].delete(fieldIndex);
+        }
+        values[fieldIndex] = value;
+    };
+}
 
-                    // automaticallty transform Map into MapSchema
-                    if (complexTypeKlass.constructor === MapSchema && !(value instanceof MapSchema)) {
-                        value = new MapSchema(value);
-                    }
+function makeSchemaRefSetter(fieldName: string, fieldIndex: number, type: typeof Schema) {
+    return function (this: Schema, value: any) {
+        const values = this[$values];
+        const previousValue = values[fieldIndex];
+        if (value === previousValue) return;
 
-                    // // automaticallty transform Array into SetSchema
-                    // if (complexTypeKlass.constructor === SetSchema && !(value instanceof SetSchema)) {
-                    //     value = new SetSchema(value);
-                    // }
+        if (value !== undefined && value !== null) {
+            assertInstanceType(value, type, this, fieldName);
 
-                    value[$childType] = type;
+            const changeTree = this[$changes];
+            const ctor = this.constructor as typeof Schema;
 
-                } else if (typeof (type) !== "string") {
-                    assertInstanceType(value, type as typeof Schema, this, fieldCached.substring(1));
+            if (previousValue !== undefined && previousValue !== null && previousValue[$changes]) {
+                changeTree.root?.remove(previousValue[$changes]);
+                ctor[$track](changeTree, fieldIndex, OPERATION.DELETE_AND_ADD);
+            } else {
+                ctor[$track](changeTree, fieldIndex, OPERATION.ADD);
+            }
 
-                } else {
-                    assertType(value, type, this, fieldCached.substring(1));
-                }
+            // External Schema-like instances may not carry a ChangeTree.
+            value[$changes]?.setParent(this, changeTree.root, fieldIndex);
 
-                const changeTree = this[$changes];
+        } else if (previousValue !== undefined && previousValue !== null) {
+            this[$changes].delete(fieldIndex);
+        }
+        values[fieldIndex] = value;
+    };
+}
 
-                //
-                // Replacing existing "ref", remove it from root.
-                //
-                if (previousValue !== undefined && previousValue[$changes]) {
-                    changeTree.root?.remove(previousValue[$changes]);
-                    (this.constructor as typeof Schema)[$track](changeTree, fieldIndex, OPERATION.DELETE_AND_ADD);
+function makeCollectionSetter(
+    _fieldName: string,
+    fieldIndex: number,
+    type: DefinitionType,
+    complexTypeKlass: TypeDefinition,
+) {
+    const isArrayKlass = complexTypeKlass.constructor === ArraySchema;
+    const isMapKlass = complexTypeKlass.constructor === MapSchema;
+    return function (this: Schema, value: any) {
+        const values = this[$values];
+        const previousValue = values[fieldIndex];
+        if (value === previousValue) return;
+
+        if (value !== undefined && value !== null) {
+            // automatic Array → ArraySchema / Map → MapSchema conversion.
+            if (isArrayKlass && !(value instanceof ArraySchema)) {
+                value = new ArraySchema(...value);
+            } else if (isMapKlass && !(value instanceof MapSchema)) {
+                value = new MapSchema(value);
+            }
+            value[$childType] = type;
 
-                } else {
-                    (this.constructor as typeof Schema)[$track](changeTree, fieldIndex, OPERATION.ADD);
-                }
+            const changeTree = this[$changes];
+            const ctor = this.constructor as typeof Schema;
 
-                //
-                // call setParent() recursively for this and its child
-                // structures.
-                //
-                value[$changes]?.setParent(this, changeTree.root, fieldIndex);
-
-            } else if (previousValue !== undefined) {
-                //
-                // Setting a field to `null` or `undefined` will delete it.
-                //
-                this[$changes].delete(fieldIndex);
+            if (previousValue !== undefined && previousValue !== null && previousValue[$changes]) {
+                changeTree.root?.remove(previousValue[$changes]);
+                ctor[$track](changeTree, fieldIndex, OPERATION.DELETE_AND_ADD);
+            } else {
+                ctor[$track](changeTree, fieldIndex, OPERATION.ADD);
             }
 
-            this[fieldCached as keyof Schema] = value;
-        },
+            value[$changes]?.setParent(this, changeTree.root, fieldIndex);
 
+        } else if (previousValue !== undefined && previousValue !== null) {
+            this[$changes].delete(fieldIndex);
+        }
+        values[fieldIndex] = value;
+    };
+}
+
+export function getPropertyDescriptor(
+    fieldName: string,
+    fieldIndex: number,
+    type: DefinitionType,
+    complexTypeKlass: TypeDefinition | false,
+) {
+    let setter: (this: Schema, value: any) => void;
+    if (complexTypeKlass) {
+        setter = makeCollectionSetter(fieldName, fieldIndex, type, complexTypeKlass);
+    } else if (typeof type === "string") {
+        setter = makePrimitiveSetter(fieldName, fieldIndex, type);
+    } else {
+        setter = makeSchemaRefSetter(fieldName, fieldIndex, type as typeof Schema);
+    }
+    return {
+        get: function (this: Schema) { return this[$values][fieldIndex]; },
+        set: setter,
         enumerable: true,
-        configurable: true
+        configurable: true,
     };
 }
 
@@ -442,38 +503,21 @@ export function getPropertyDescriptor(
 
 export function deprecated(throws: boolean = true): PropertyDecorator {
     return function (klass: typeof Schema, field: string) {
-        //
-        // FIXME: the following block of code is repeated across `@type()`, `@deprecated()` and `@unreliable()` decorators.
-        //
-        const constructor = klass.constructor as typeof Schema;
-
-        const parentClass = Object.getPrototypeOf(constructor);
-        const parentMetadata = parentClass[Symbol.metadata];
-        const metadata: Metadata = (constructor[Symbol.metadata] ??= Object.assign({}, constructor[Symbol.metadata], parentMetadata ?? Object.create(null)));
+        const metadata = Metadata.initialize(klass.constructor as typeof Schema);
         const fieldIndex = metadata[field];
 
-        // if (!metadata[field]) {
-        //     //
-        //     // detect index for this field, considering inheritance
-        //     //
-        //     metadata[field] = {
-        //         type: undefined,
-        //         index: (metadata[$numFields] // current structure already has fields defined
-        //             ?? (parentMetadata && parentMetadata[$numFields]) // parent structure has fields defined
-        //             ?? -1) + 1 // no fields defined
-        //     }
-        // }
-
         metadata[fieldIndex].deprecated = true;
 
         if (throws) {
             metadata[$descriptors] ??= {};
             metadata[$descriptors][field] = {
                 get: function () { throw new Error(`${field} is deprecated.`); },
-                set: function (this: Schema, value: any) { /* throw new Error(`${field} is deprecated.`); */ },
+                set: function (this: Schema, _value: any) { /* throw new Error(`${field} is deprecated.`); */ },
                 enumerable: false,
                 configurable: true
             };
+            // Override accessor on the prototype so deprecated throws at access.
+            Object.defineProperty(klass, field, metadata[$descriptors][field]);
         }
 
         // flag metadata[field] as non-enumerable
@@ -485,20 +529,13 @@ export function deprecated(throws: boolean = true): PropertyDecorator {
     }
 }
 
-export function defineTypes(
-    target: typeof Schema,
-    fields: Definition,
-    options?: TypeOptions
-) {
-    for (let field in fields) {
-        type(fields[field], options)(target.prototype, field);
-    }
-    return target;
-}
-
-// 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
@@ -507,141 +544,190 @@ type ExtractInitProps<T> = T extends { initialize: (...args: infer P) => void }
                 ? First
                 : P
             : P
-    : T extends Definition
-        ? AssignableProps<InferSchemaInstanceType<T>>
-        : never;
-
-// 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;
-
-export interface SchemaWithExtends<T extends Definition, P extends typeof Schema, > {
-    extends: <T2 extends Definition = Definition>(
+    : BuilderInitProps<T>;
+
+// 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, 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>;
+        name?: string,
+    ) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
 }
 
 /**
- * Get the type of the schema defined via `schema({...})` method.
+ * Get the type of the schema defined via `schema('Name', {...})` method.
  *
  * @example
- * const Entity = schema({
- *     x: "number",
- *     y: "number",
+ * const Entity = schema('Entity', {
+ *     x: t.number(),
+ *     y: t.number(),
  * });
  * type Entity = SchemaType<typeof Entity>;
  */
 export type SchemaType<T extends {'~type': any}> = T['~type'];
 
 export interface SchemaWithExtendsConstructor<
-    T extends Definition,
+    T,
     InitProps,
     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;
     };
 }
 
+/**
+ * Define a Schema class declaratively.
+ *
+ * @example
+ * import { schema, t } from '@colyseus/schema';
+ *
+ * const Player = schema({
+ *   hp: t.uint8().default(100),
+ *   name: t.string().view(),
+ *   takeDamage(n: number) { this.hp -= n; },
+ * }, 'Player');
+ *
+ * const Warrior = Player.extend({
+ *   weapon: t.string(),
+ * }, 'Warrior');
+ */
 export function schema<
-    T extends Record<string, DefinitionType>,
+    T extends FieldsAndMethods,
     P extends typeof Schema = typeof Schema
 >(
     fieldsAndMethods: T & ThisType<InferSchemaInstanceType<T>>,
     name?: string,
-    inherits: P = Schema as P
+    inherits: P = Schema as P,
 ): SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P> {
+    if (fieldsAndMethods == null || typeof fieldsAndMethods !== "object") {
+        throw new Error(`schema(): first argument must be a fields object (got ${typeof fieldsAndMethods}).`);
+    }
+
     const fields: any = {};
     const methods: any = {};
-
     const defaultValues: any = {};
-    const viewTagFields: any = {};
-
-    for (let fieldName in fieldsAndMethods) {
-        const value: any = fieldsAndMethods[fieldName] as DefinitionType;
-        if (typeof (value) === "object") {
-            if (value['view'] !== undefined) {
-                viewTagFields[fieldName] = (typeof (value['view']) === "boolean")
-                    ? DEFAULT_VIEW_TAG
-                    : value['view'];
-            }
-
-            // allow to define a field as not synced
-            if (value['sync'] !== false) {
-                fields[fieldName] = getNormalizedType(value);
-            }
-
-            // If no explicit default provided, handle automatic instantiation for collection types
-            if (!Object.prototype.hasOwnProperty.call(value, 'default')) {
-                // TODO: remove Array.isArray() check. Use ['array'] !== undefined only.
-                if (Array.isArray(value) || value['array'] !== undefined) {
-                    // Collection: Array → new ArraySchema()
-                    defaultValues[fieldName] = new ArraySchema();
-
-                } else if (value['map'] !== undefined) {
-                    // Collection: Map → new MapSchema()
-                    defaultValues[fieldName] = new MapSchema();
-
-                } else if (value['collection'] !== undefined) {
-                    // Collection: Collection → new CollectionSchema()
-                    defaultValues[fieldName] = new CollectionSchema();
-
-                } else if (value['set'] !== undefined) {
-                    // Collection: Set → new SetSchema()
-                    defaultValues[fieldName] = new SetSchema();
-
-                } else if (value['type'] !== undefined && Schema.is(value['type'])) {
-                    // Direct Schema type: Type → new Type()
-                    if (!value['type'].prototype.initialize || value['type'].prototype.initialize.length === 0) {
-                        // only auto-initialize Schema instances if:
-                        // - they don't have an initialize method
-                        // - or initialize method doesn't accept any parameters
-                        defaultValues[fieldName] = new value['type']();
+    const viewTagFields: { [field: string]: number } = {};
+    const ownedFields: string[] = [];
+    const unreliableFields: string[] = [];
+    const transientFields: string[] = [];
+    const deprecatedFields: { [field: string]: boolean } = {};
+    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];
+
+        if (isBuilder(value)) {
+            const def = value.toDefinition();
+            fields[fieldName] = getNormalizedType(def.type);
+
+            if (def.view !== undefined) { viewTagFields[fieldName] = def.view; }
+            if (def.owned) { ownedFields.push(fieldName); }
+            if (def.unreliable) { unreliableFields.push(fieldName); }
+            if (def.transient) { transientFields.push(fieldName); }
+            if (def.deprecated) { deprecatedFields[fieldName] = def.deprecatedThrows; }
+            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 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) {
+                        defaultValues[fieldName] = new ArraySchema();
+                    } else if (rawType.map !== undefined) {
+                        defaultValues[fieldName] = new MapSchema();
+                    } else if (rawType.set !== undefined) {
+                        defaultValues[fieldName] = new SetSchema();
+                    } else if (rawType.collection !== undefined) {
+                        defaultValues[fieldName] = new CollectionSchema();
+                    } else if (rawType.stream !== undefined) {
+                        defaultValues[fieldName] = new StreamSchema();
+                    }
+                } else if (typeof rawType === "function" && Schema.is(rawType)) {
+                    if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
+                        defaultValues[fieldName] = new rawType();
                     }
                 }
-            } else {
-                defaultValues[fieldName] = value['default'];
             }
 
-
-        } else if (typeof (value) === "function") {
+        } else if (typeof value === "function") {
             if (Schema.is(value)) {
-                // Direct Schema type: Type → new Type()
+                // Convenience: allow a bare Schema subclass (equivalent to `t.ref(Class)`).
+                fields[fieldName] = getNormalizedType(value);
                 if (!value.prototype.initialize || value.prototype.initialize.length === 0) {
-                    // only auto-initialize Schema instances if:
-                    // - they don't have an initialize method
-                    // - or initialize method doesn't accept any parameters
                     defaultValues[fieldName] = new value();
                 }
-                fields[fieldName] = getNormalizedType(value);
             } else {
                 methods[fieldName] = value;
             }
 
         } else {
-            fields[fieldName] = getNormalizedType(value);
+            throw new Error(
+                `schema(${name ? `'${name}'` : ""}): field '${fieldName}' must be a t.* builder, ` +
+                `Schema subclass, or method (got ${typeof value}).`
+            );
         }
     }
 
     const getDefaultValues = () => {
         const defaults: any = {};
-
-        // use current class default values
         for (const fieldName in defaultValues) {
             const defaultValue = defaultValues[fieldName];
-            if (defaultValue && typeof defaultValue.clone === 'function') {
-                // complex, cloneable values, e.g. Schema, ArraySchema, MapSchema, CollectionSchema, SetSchema
+            if (defaultValue && typeof defaultValue.clone === "function") {
                 defaults[fieldName] = defaultValue.clone();
             } else {
-                // primitives and non-cloneable values
                 defaults[fieldName] = defaultValue;
             }
         }
@@ -657,44 +743,71 @@ export function schema<
             }
         }
         return parentProps;
-    }
+    };
 
     /** @codegen-ignore */
     const klass = Metadata.setFields<any>(class extends (inherits as any) {
         constructor(...args: any[]) {
-            // call initialize method
-            if (methods.initialize && typeof methods.initialize === 'function') {
+            if (methods.initialize && typeof methods.initialize === "function") {
                 super(Object.assign({}, getDefaultValues(), getParentProps(args[0] || {})));
-                /**
-                 * only call initialize() in the current class, not the parent ones.
-                 * see "should not call initialize automatically when creating an instance of inherited Schema"
-                 */
+                // Only call initialize() on the exact target class, not parents.
                 if (new.target === klass) {
                     methods.initialize.apply(this, args);
                 }
-
             } else {
                 super(Object.assign({}, getDefaultValues(), args[0] || {}));
             }
         }
-    }, fields) as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
+    }, fields) as unknown as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
 
-    // Store the getDefaultValues function on the class for inheritance
     (klass as any)._getDefaultValues = getDefaultValues;
 
-    // Add methods to the prototype
     Object.assign(klass.prototype, methods);
 
-    for (let fieldName in viewTagFields) {
+    for (const fieldName in viewTagFields) {
         view(viewTagFields[fieldName])(klass.prototype, fieldName);
     }
+    for (const fieldName of ownedFields) {
+        owned(klass.prototype, fieldName);
+    }
+    for (const fieldName of unreliableFields) {
+        unreliable(klass.prototype, fieldName);
+    }
+    for (const fieldName of transientFields) {
+        transient(klass.prototype, fieldName);
+    }
+    for (const fieldName in deprecatedFields) {
+        deprecated(deprecatedFields[fieldName])(klass.prototype, fieldName);
+    }
+
+    if (staticFields.length > 0 || streamFields.length > 0) {
+        const metadata = (klass as any)[Symbol.metadata] as Metadata;
+        for (const fieldName of staticFields) {
+            Metadata.setStatic(metadata, fieldName);
+        }
+        for (const fieldName of streamFields) {
+            Metadata.setStream(metadata, fieldName);
+        }
+        for (const fieldName in streamPriorityFields) {
+            Metadata.setStreamPriority(metadata, fieldName, streamPriorityFields[fieldName]);
+        }
+    }
+
+    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 });
     }
 
-    klass.extends = <T2 extends Definition = Definition>(fields: T2, name?: string) =>
-        schema<T2>(fields, name, klass as any) as SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T2>, P>;
+    (klass as any).extend = <T2 extends FieldsAndMethods = FieldsAndMethods>(
+        childFields: T2,
+        childName?: string,
+    ) => schema<T2>(childFields, childName, klass as any);
 
     return klass;
 }