@colyseus/schema 5.0.6 → 5.0.9

package/src/Schema.ts

@@ -4,7 +4,7 @@ import { DEFAULT_VIEW_TAG, type DefinitionType } from "./annotations.js";
 import { AssignableProps, NonFunctionPropNames, ToJSON } from './types/HelperTypes.js';
 
 import { ChangeTree, installUntrackedChangeTree, IRef, Ref } from './encoder/ChangeTree.js';
-import { $changes, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $numFields, $refId, $track, $values } from './types/symbols.js';
+import { $changes, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $numFields, $refId, $refTypeFieldIndexes, $reset, $track, $values } from './types/symbols.js';
 import { StateView } from './encoder/StateView.js';
 
 import { encodeSchemaOperation } from './encoder/EncodeOperation.js';
@@ -66,6 +66,67 @@ export class Schema<C = any> implements IRef {
         return inst;
     }
 
+    /**
+     * Reset a DETACHED instance to construction defaults so it can be returned
+     * to a {@link SchemaPool} and reused, avoiding the cost of `new`. Recurses
+     * into ref-type fields (child Schemas / collections).
+     *
+     * Preconditions (enforced):
+     * - The instance must be tracked (encoder-side), not a decoder mirror.
+     * - The instance must NOT be shared across multiple parents.
+     * - The instance must already be removed from its parent collection/field
+     *   (so the encoder detached it: `root === undefined`).
+     *
+     * NOTE: primitive field values are NOT reset to class defaults — re-assign
+     * the fields you care about when you reuse the instance (standard
+     * object-pool discipline).
+     */
+    static reset(instance: Schema): void {
+        const changeTree: ChangeTree = (instance as any)?.[$changes];
+
+        // Only tracked (encoder-side) instances are poolable. Decoder-side
+        // instances carry an UntrackedChangeTree, which has no recycle().
+        if (changeTree === undefined || typeof (changeTree as any).recycle !== "function") {
+            throw new Error(`@colyseus/schema: Schema.reset() requires a tracked (encoder-side) instance.`);
+        }
+
+        // Instances reachable through more than one parent are unsafe to pool:
+        // another owner may still hold this instance.
+        if (changeTree.extraParents !== undefined) {
+            throw new Error(`@colyseus/schema: cannot reset a shared instance (${instance.constructor.name}) with multiple parents.`);
+        }
+
+        (instance as any)[$reset]();
+    }
+
+    /**
+     * Per-instance reset primitive (the recursive worker behind
+     * {@link Schema.reset}). Resets ref-type children first (depth-first),
+     * then recycles this instance's ChangeTree and drops its `$refId` so a
+     * re-add is assigned a fresh refId exactly like a freshly constructed
+     * instance. Dropping `$refId` is what makes instance reuse
+     * wire-format-identical to `new T()`.
+     */
+    [$reset](): void {
+        const metadata: Metadata = (this.constructor as typeof Schema)[Symbol.metadata];
+        const refIndexes = (metadata?.[$refTypeFieldIndexes] as number[]) ?? [];
+        const values = this[$values];
+
+        for (let i = 0; i < refIndexes.length; i++) {
+            const child = values[refIndexes[i]];
+            // ref fields hold a child Schema or collection (both implement
+            // [$reset]); skip undefined/null. Optional-chain is a cheap guard.
+            child?.[$reset]?.();
+        }
+
+        this[$changes].recycle();
+        // Clear the refId by ASSIGNMENT (not `delete`): `delete` would force the
+        // instance into V8 dictionary mode, making release() as expensive as the
+        // construction it saves. `=== undefined` in Root.add still assigns a fresh
+        // refId exactly like a freshly-constructed instance.
+        this[$refId] = undefined;
+    }
+
     /**
      * Check whether `type` describes a Schema *class* (a subclass
      * constructor carrying `Symbol.metadata`, as installed by `@type`).
@@ -132,7 +193,8 @@ export class Schema<C = any> implements IRef {
             return view.isChangeTreeVisible(ref[$changes]);
 
         } else {
-            // view pass: custom tag
+            // view pass: custom tag (bitmask) — field's stored mask matches
+            // if it shares any bit with a tag this view was add()ed with.
             return view.hasTagOnTree(ref[$changes], tag);
         }
     }

package/src/annotations.ts

@@ -13,7 +13,8 @@ import type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderI
 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";
+import { FieldBuilder, isBuilder, type BuilderDefinition } from "./types/builder.js";
+import { dequantize, isQuantizedType, makeQuantizedEncoder, quantize, type QuantizeDescriptor } from "./types/quantize.js";
 
 export type RawPrimitiveType = "string" |
     "number" |
@@ -51,8 +52,15 @@ export interface TypeOptions {
 
 export const DEFAULT_VIEW_TAG = -1;
 
-export function entity(constructor: any): any {
-    TypeContext.register(constructor as typeof Schema);
+/**
+ * Class decorator that registers a `@type`-style Schema class with the
+ * TypeContext (required for reflection / cross-language codegen).
+ *
+ *     @entity
+ *     class Player extends Schema { ... }
+ */
+export function entity<T extends Function>(constructor: T): T {
+    TypeContext.register(constructor as unknown as typeof Schema);
     return constructor;
 }
 
@@ -336,8 +344,8 @@ export function type (
             Object.defineProperty(target, field, metadata[$descriptors][field]);
         }
 
-        // Pre-compute encoder function for primitive types.
-        if (typeof type === "string") {
+        // Pre-compute encoder function for primitive + quantized types.
+        if (typeof type === "string" || isQuantizedType(type)) {
             if (!metadata[$encoders]) {
                 Object.defineProperty(metadata, $encoders, {
                     value: [],
@@ -346,7 +354,9 @@ export function type (
                     writable: true,
                 });
             }
-            metadata[$encoders][fieldIndex] = (encode as any)[type];
+            metadata[$encoders][fieldIndex] = (typeof type === "string")
+                ? (encode as any)[type]
+                : makeQuantizedEncoder((type as any).quantized);
         }
     }
 }
@@ -474,6 +484,38 @@ function makeCollectionSetter(
     };
 }
 
+/**
+ * Setter for a `t.quantized()` field. SNAPS the assigned float to the wire-exact
+ * value (`dequant(quant(x))`) on write, so the stored value — and every read,
+ * including the reconciler's live step off the staged input — is identical to
+ * what the server decodes off the wire. This is the half that kills the
+ * predict-from-the-wrong-value footgun; the encoder re-quantizes the snapped
+ * value at send (a lossless round-trip). Change tracking keys on the SNAPPED
+ * value, so a sub-step jitter that quantizes to the same integer emits no delta.
+ */
+function makeQuantizedSetter(fieldName: string, fieldIndex: number, desc: QuantizeDescriptor) {
+    return function (this: Schema, value: any) {
+        const values = this[$values];
+        const previousValue = values[fieldIndex];
+        if (value !== undefined && value !== null) {
+            if (typeof value !== "number") {
+                throw new EncodeSchemaError(
+                    `a 'number' was expected, but '${JSON.stringify(value)}' was provided in ${this.constructor.name}#${fieldName}`
+                );
+            }
+            value = dequantize(desc, quantize(desc, value)); // snap to wire-exact
+            if (value === previousValue) return;
+            (this.constructor as typeof Schema)[$track](this[$changes], fieldIndex, OPERATION.ADD);
+        } else {
+            if (value === previousValue) return; // undefined === undefined
+            if (previousValue !== undefined && previousValue !== null) {
+                this[$changes].delete(fieldIndex);
+            }
+        }
+        values[fieldIndex] = value;
+    };
+}
+
 export function getPropertyDescriptor(
     fieldName: string,
     fieldIndex: number,
@@ -485,10 +527,14 @@ export function getPropertyDescriptor(
         setter = makeCollectionSetter(fieldName, fieldIndex, type, complexTypeKlass);
     } else if (typeof type === "string") {
         setter = makePrimitiveSetter(fieldName, fieldIndex, type);
+    } else if (isQuantizedType(type)) {
+        setter = makeQuantizedSetter(fieldName, fieldIndex, type.quantized);
     } else {
         setter = makeSchemaRefSetter(fieldName, fieldIndex, type as typeof Schema);
     }
     return {
+        // Quantized stores the already-snapped float, so the getter is the plain
+        // $values read — the field yields dequant(q) with no per-read math.
         get: function (this: Schema) { return this[$values][fieldIndex]; },
         set: setter,
         enumerable: true,
@@ -529,6 +575,30 @@ export function deprecated(throws: boolean = true): PropertyDecorator {
     }
 }
 
+let defineTypesWarned = false;
+
+/**
+ * Adds synchronizable fields to an existing `Schema` subclass — the pre-5.0
+ * helper for plain JavaScript users.
+ *
+ * @deprecated Use `schema()` with `t.*` field builders instead:
+ * https://docs.colyseus.io/state/schema
+ */
+export function defineTypes(
+    target: typeof Schema,
+    fields: Definition,
+    options?: TypeOptions
+) {
+    if (!defineTypesWarned) {
+        defineTypesWarned = true;
+        console.warn("@colyseus/schema: defineTypes() is deprecated and will be removed in a future release. Use schema() with t.* field builders instead → https://docs.colyseus.io/state/schema");
+    }
+    for (let field in fields) {
+        type(fields[field], options)(target.prototype, field);
+    }
+    return target;
+}
+
 // 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
@@ -620,20 +690,21 @@ export interface SchemaWithExtendsConstructor<
 }
 
 /**
- * Produce the auto-instantiated construction default for a builder type
- * (empty collection or zero-arg Schema ref), or `undefined` when the type
- * has no auto-default. Shared by synced and `.noSync()` field handling.
+ * Build a per-construction factory for a builder type's auto-instantiated
+ * default (empty collection or zero-arg Schema ref), or `undefined` when the
+ * type has no auto-default. Returning a factory lets each construction `new` a
+ * fresh value directly instead of cloning a shared prototype instance.
  */
-function autoInstantiateDefault(rawType: any): any {
+function makeAutoDefaultFactory(rawType: any): (() => any) | undefined {
     if (rawType && typeof rawType === "object") {
-        if (rawType.array !== undefined) { return new ArraySchema(); }
-        if (rawType.map !== undefined) { return new MapSchema(); }
-        if (rawType.set !== undefined) { return new SetSchema(); }
-        if (rawType.collection !== undefined) { return new CollectionSchema(); }
-        if (rawType.stream !== undefined) { return new StreamSchema(); }
+        if (rawType.array !== undefined) { return () => new ArraySchema(); }
+        if (rawType.map !== undefined) { return () => new MapSchema(); }
+        if (rawType.set !== undefined) { return () => new SetSchema(); }
+        if (rawType.collection !== undefined) { return () => new CollectionSchema(); }
+        if (rawType.stream !== undefined) { return () => new StreamSchema(); }
     } else if (typeof rawType === "function" && Schema.is(rawType)) {
         if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
-            return new rawType();
+            return () => new rawType();
         }
     }
     return undefined;
@@ -669,7 +740,37 @@ export function schema<
 
     const fields: any = {};
     const methods: any = {};
+    // Two buckets, both keyed by field name and applied at construction:
+    //  - `defaultValues`: static values copied as-is (shared reference).
+    //  - `defaultFactories`: invoked per construction for a fresh value —
+    //    `.default(fn)`, clone-able defaults, and auto-instantiated collections/refs.
     const defaultValues: any = {};
+    const defaultFactories: { [field: string]: () => any } = {};
+
+    // Decide once (at definition time) how each `.default(v)` materializes per
+    // construction: a function is a factory; a clone-able value clones fresh;
+    // anything else is a shared static value.
+    const assignDefault = (field: string, value: any) => {
+        if (typeof value === "function") {
+            defaultFactories[field] = value;
+        } else if (value && typeof value.clone === "function") {
+            defaultFactories[field] = () => value.clone();
+        } else {
+            defaultValues[field] = value;
+        }
+    };
+
+    // Seed a field's construction default: explicit `.default(v)`, else the
+    // auto-instantiated empty collection / zero-arg ref (skipped for `.optional()`).
+    const seedDefault = (field: string, def: BuilderDefinition) => {
+        if (def.hasDefault) {
+            assignDefault(field, def.default);
+        } else if (!def.optional) {
+            const factory = makeAutoDefaultFactory(def.type);
+            if (factory) { defaultFactories[field] = factory; }
+        }
+    };
+
     const viewTagFields: { [field: string]: number } = {};
     const ownedFields: string[] = [];
     const unreliableFields: string[] = [];
@@ -698,18 +799,19 @@ export function schema<
                         `A local-only field cannot be synchronized.`
                     );
                 }
-                if (def.hasDefault) {
-                    defaultValues[fieldName] = def.default;
-                } else if (!def.optional) {
-                    const autoDefault = autoInstantiateDefault(def.type);
-                    if (autoDefault !== undefined) {
-                        defaultValues[fieldName] = autoDefault;
-                    }
-                }
+                seedDefault(fieldName, def);
                 continue;
             }
 
-            fields[fieldName] = getNormalizedType(def.type);
+            const normalizedType = getNormalizedType(def.type);
+            // A synced ref must be encodable (a Schema, or Metadata.setFields()'d) — reject a bare class.
+            if (typeof normalizedType === "function" && !Schema.is(normalizedType)) {
+                throw new Error(
+                    `schema(${name ? `'${name}'` : ""}): field '${fieldName}' is a synced ref to non-Schema ` +
+                    `class '${normalizedType.name || "(anonymous)"}' — use .noSync(), or Metadata.setFields().`
+                );
+            }
+            fields[fieldName] = normalizedType;
 
             if (def.view !== undefined) { viewTagFields[fieldName] = def.view; }
             if (def.owned) { ownedFields.push(fieldName); }
@@ -721,23 +823,14 @@ export function schema<
             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 autoDefault = autoInstantiateDefault(def.type);
-                if (autoDefault !== undefined) {
-                    defaultValues[fieldName] = autoDefault;
-                }
-            }
+            seedDefault(fieldName, def);
 
         } else if (typeof value === "function") {
             if (Schema.is(value)) {
                 // Convenience: allow a bare Schema subclass (equivalent to `t.ref(Class)`).
                 fields[fieldName] = getNormalizedType(value);
                 if (!value.prototype.initialize || value.prototype.initialize.length === 0) {
-                    defaultValues[fieldName] = new value();
+                    defaultFactories[fieldName] = () => new (value as any)();
                 }
             } else {
                 methods[fieldName] = value;
@@ -751,16 +844,20 @@ export function schema<
         }
     }
 
-    const getDefaultValues = () => {
-        const defaults: any = {};
+    // Write construction defaults onto `target` — either the instance directly
+    // (no-args fast path) or a throwaway object that gets merged with props.
+    const applyDefaults = (target: any) => {
         for (const fieldName in defaultValues) {
-            const defaultValue = defaultValues[fieldName];
-            if (defaultValue && typeof defaultValue.clone === "function") {
-                defaults[fieldName] = defaultValue.clone();
-            } else {
-                defaults[fieldName] = defaultValue;
-            }
+            target[fieldName] = defaultValues[fieldName];
+        }
+        for (const fieldName in defaultFactories) {
+            target[fieldName] = defaultFactories[fieldName]();
         }
+    };
+
+    const getDefaultValues = () => {
+        const defaults: any = {};
+        applyDefaults(defaults);
         return defaults;
     };
 
@@ -775,17 +872,26 @@ export function schema<
         return parentProps;
     };
 
+    const hasInitialize = typeof methods.initialize === "function";
+
     /** @codegen-ignore */
     const klass = Metadata.setFields<any>(class extends (inherits as any) {
         constructor(...args: any[]) {
-            if (methods.initialize && typeof methods.initialize === "function") {
-                super(Object.assign({}, getDefaultValues(), getParentProps(args[0] || {})));
-                // Only call initialize() on the exact target class, not parents.
-                if (new.target === klass) {
-                    methods.initialize.apply(this, args);
-                }
+            const props = args[0];
+            if (props === undefined) {
+                // No-args: write defaults straight onto the instance — skips the
+                // throwaway defaults object + Object.assign + assignProps walk.
+                super();
+                applyDefaults(this);
             } else {
-                super(Object.assign({}, getDefaultValues(), args[0] || {}));
+                // With props: merge into the fresh defaults object in place (no
+                // extra `{}` target); the super chain runs assignProps once. An
+                // `initialize()` owns the schema fields, so only parent props flow up.
+                super(Object.assign(getDefaultValues(), hasInitialize ? getParentProps(props) : props));
+            }
+            // Only call initialize() on the exact target class, not parents.
+            if (hasInitialize && new.target === klass) {
+                methods.initialize.apply(this, args);
             }
         }
     }, fields) as unknown as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;

package/src/bench_churn.ts

@@ -0,0 +1,121 @@
+/**
+ * Benchmark: entity churn (spawn → despawn → respawn) with and without the
+ * native SchemaPool. Existing benches (bench_encode/bench_bloat) are
+ * monotonic-growth and never return instances to a pool, so they can't show
+ * pooling ROI — this one models the ECS/projectile/bot workload the pool
+ * targets.
+ *
+ * Usage:  npx tsx --tsconfig tsconfig.test.json src/bench_churn.ts
+ */
+import v8 from "node:v8";
+import vm from "node:vm";
+import { Schema, type, MapSchema, Encoder, createPool, type SchemaPool } from "./index";
+
+// gc() handle (works under the tsx CLI, where `node --expose-gc` doesn't reach
+// the forked child).
+v8.setFlagsFromString("--expose-gc");
+const gc = (globalThis.gc as undefined | (() => void)) ?? (vm.runInNewContext("gc") as () => void);
+
+class Vector extends Schema {
+    @type("number") x: number = 0;
+    @type("number") y: number = 0;
+    @type("number") z: number = 0;
+}
+// A nested entity: Entity + 2 child Vectors = 3 Schema instances per spawn,
+// matching the miniplex profiling scenario.
+class Entity extends Schema {
+    @type("string") name: string = "";
+    @type(Vector) position = new Vector();
+    @type(Vector) velocity = new Vector();
+}
+class State extends Schema {
+    @type({ map: Entity }) entities = new MapSchema<Entity>();
+}
+
+Encoder.BUFFER_SIZE = 4096 * 4096;
+
+const N = 2_000;     // entities alive per tick
+const TICKS = 200;   // churn cycles
+const WARMUP = 10;
+const INSTANCES_PER_ENTITY = 3; // Entity + position + velocity
+const spawns = N * TICKS;
+
+const heap = () => {
+    gc?.();
+    gc?.();
+    return process.memoryUsage().heapUsed;
+};
+
+function runChurn(usePool: boolean) {
+    const state = new State();
+    const encoder = new Encoder(state);
+    encoder.encode();
+    encoder.discardChanges();
+
+    const pool: SchemaPool<Entity> | undefined = usePool ? createPool(Entity, { preallocate: N }) : undefined;
+    const live: Entity[] = new Array(N);
+
+    const spawnTick = (timeConstruct: boolean): number => {
+        // CONSTRUCTION phase (the differentiator): new vs acquire
+        const c0 = performance.now();
+        for (let i = 0; i < N; i++) {
+            live[i] = pool ? pool.acquire() : new Entity();
+        }
+        const c1 = performance.now();
+
+        // init + attach + encode
+        for (let i = 0; i < N; i++) {
+            const e = live[i];
+            e.name = "e" + i;
+            e.position.x = i; e.position.y = i; e.position.z = i;
+            e.velocity.x = 1;
+            state.entities.set(String(i), e);
+        }
+        encoder.encode();
+        encoder.discardChanges();
+
+        // despawn + release
+        for (let i = 0; i < N; i++) state.entities.delete(String(i));
+        encoder.encode();
+        encoder.discardChanges();
+        if (pool) for (let i = 0; i < N; i++) pool.release(live[i]);
+
+        return timeConstruct ? c1 - c0 : 0;
+    };
+
+    for (let t = 0; t < WARMUP; t++) spawnTick(false);
+
+    const before = heap();
+    let constructMs = 0;
+    const t0 = performance.now();
+    for (let t = 0; t < TICKS; t++) constructMs += spawnTick(true);
+    const t1 = performance.now();
+    const after = heap();
+
+    return {
+        cycleMs: t1 - t0,
+        constructMs,
+        constructNsPerEntity: (constructMs * 1e6) / spawns,
+        heapDelta: after - before,
+        poolSize: pool?.size ?? 0
+    };
+}
+
+console.log(`\nEntity churn benchmark — ${N} entities × ${TICKS} ticks = ${spawns.toLocaleString("en-US")} spawns`);
+console.log(`(each entity = ${INSTANCES_PER_ENTITY} Schema instances; gc=${gc ? "on" : "off"})\n`);
+
+const noPool = runChurn(false);
+const pooled = runChurn(true);
+
+const row = (label: string, r: ReturnType<typeof runChurn>) => {
+    console.log(`${label.padEnd(14)} construct: ${r.constructMs.toFixed(1).padStart(8)} ms  ` +
+        `${r.constructNsPerEntity.toFixed(0).padStart(6)} ns/entity   ` +
+        `full cycle: ${r.cycleMs.toFixed(1).padStart(8)} ms   ` +
+        `heapΔ: ${(r.heapDelta / 1024 / 1024).toFixed(1).padStart(7)} MB`);
+};
+
+row("new Entity()", noPool);
+row("pool.acquire()", pooled);
+console.log(`\nConstruction speedup: ${(noPool.constructNsPerEntity / pooled.constructNsPerEntity).toFixed(1)}x faster` +
+    `   (full-cycle: ${(noPool.cycleMs / pooled.cycleMs).toFixed(2)}x — diluted by identical encode/decode cost)`);
+console.log(`Pool retained ${pooled.poolSize} instances after the run.\n`);

package/src/codegen/languages/haxe.ts

@@ -67,22 +67,6 @@ ${classBodies.join("\n\n")}
     return { name: fileName, content };
 }
 
-function getInheritanceTree(klass: Class, allClasses: Class[], includeSelf: boolean = true) {
-    let currentClass = klass;
-    let inheritanceTree: Class[] = [];
-
-    if (includeSelf) {
-        inheritanceTree.push(currentClass);
-    }
-
-    while (currentClass.extends !== "Schema") {
-        currentClass = allClasses.find(klass => klass.name == currentClass.extends);
-        inheritanceTree.push(currentClass);
-    }
-
-    return inheritanceTree;
-}
-
 /**
  * Generate just the class body (without package/imports) for bundling
  */

package/src/codegen/parser.ts

@@ -8,6 +8,8 @@ let currentProperty: Property;
 
 let globalContext: Context;
 
+let defineTypesWarned = false;
+
 const BUILDER_COLLECTION_KINDS = new Set(["array", "map", "set", "collection"]);
 
 /**
@@ -254,6 +256,44 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
                     defineProperty(property, prop.initializer);
                 }
 
+            } else if (
+                node.getText() === "defineTypes" &&
+                (
+                    node.parent.kind === ts.SyntaxKind.CallExpression ||
+                    node.parent.kind === ts.SyntaxKind.PropertyAccessExpression
+                )
+            ) {
+                /**
+                 * JavaScript source file (`.js`)
+                 * Using `defineTypes()` (deprecated)
+                 */
+                const callExpression = (node.parent.kind === ts.SyntaxKind.PropertyAccessExpression)
+                    ? node.parent.parent as ts.CallExpression
+                    : node.parent as ts.CallExpression;
+
+                if (callExpression.kind !== ts.SyntaxKind.CallExpression) {
+                    break;
+                }
+
+                if (!defineTypesWarned) {
+                    defineTypesWarned = true;
+                    console.warn("schema-codegen: defineTypes() is deprecated and will be removed in a future release. Use schema() with t.* field builders instead → https://docs.colyseus.io/state/schema");
+                }
+
+                const className = callExpression.arguments[0].getText()
+                currentStructure.name = className;
+
+                const types = callExpression.arguments[1] as any;
+                for (let i = 0; i < types.properties.length; i++) {
+                    const prop = types.properties[i];
+
+                    const property = currentProperty || new Property();
+                    property.name = prop.name.escapedText;
+                    currentStructure.addProperty(property);
+
+                    defineProperty(property, prop.initializer);
+                }
+
             }
 
             if (node.parent.kind === ts.SyntaxKind.ClassDeclaration) {
@@ -278,7 +318,7 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
                 if (!callee) break;
 
                 const isSchemaCall = callee === "schema" || callee === "schema.schema";
-                const isExtendCall = callee.indexOf(".extend") !== -1 && !callee.endsWith(".extends");
+                const isExtendCall = callee.endsWith(".extend");
                 if (!isSchemaCall && !isExtendCall) break;
 
                 // Signature: (fields, name?)
@@ -297,25 +337,43 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
                     }
                 }
 
-                if (!className && callExpression.parent.kind === ts.SyntaxKind.VariableDeclaration) {
-                    className = (callExpression.parent as ts.VariableDeclaration).name?.getText();
+                if (!className) {
+                    // No explicit name arg — infer it from the variable the
+                    // result is assigned to (`const Foo = schema({...})`).
+                    let p: ts.Node = callExpression.parent;
+                    while (p !== undefined && (
+                        p.kind === ts.SyntaxKind.PropertyAccessExpression ||
+                        p.kind === ts.SyntaxKind.CallExpression
+                    )) {
+                        p = p.parent;
+                    }
+                    if (p?.kind === ts.SyntaxKind.VariableDeclaration) {
+                        className = (p as ts.VariableDeclaration).name?.getText();
+                    }
                 }
 
                 if (!className) break;
 
+                // Resolve the base class BEFORE registering a structure. A
+                // chained `schema({...}).extend({...})` has a call expression
+                // (not an identifier) as its `.extend` base, which can't be
+                // statically named — bail here rather than leave a half-formed,
+                // nameless Class in the context (which corrupts inheritance walks).
+                let extendsClass = "Schema";
+                if (isExtendCall) {
+                    extendsClass = (node as any).expression?.expression?.escapedText;
+                    if (!extendsClass) {
+                        console.warn(`schema-codegen: cannot resolve the base class of a chained .extend() for '${className}' — fields from that .extend({...}) are omitted.`);
+                        break;
+                    }
+                }
+
                 if (currentStructure?.name !== className) {
                     currentStructure = new Class();
                     context.addStructure(currentStructure);
                 }
 
-                if (isExtendCall) {
-                    const extendsClass = (node as any).expression?.expression?.escapedText;
-                    if (!extendsClass) break;
-                    (currentStructure as Class).extends = extendsClass;
-                } else {
-                    (currentStructure as Class).extends = "Schema";
-                }
-
+                (currentStructure as Class).extends = extendsClass;
                 currentStructure.name = className;
 
                 const types = fieldsArg as any;