@colyseus/schema 5.0.6 → 5.0.9

package/build/Reflection.d.ts

@@ -45,14 +45,53 @@ interface ReflectionStatic {
 /**
  * Reflection
  */
+/**
+ * `t.quantized()` field descriptor as it rides the reflection handshake —
+ * schema-typed (bit-exact float64 bounds), NOT a string grammar, so every
+ * language port decodes it with the schema decoder it already has.
+ */
+export declare const QuantizedDescriptor: import("./annotations.js").SchemaWithExtendsConstructor<{
+    min: FieldBuilder<number, false, false>;
+    max: FieldBuilder<number, false, false>;
+    bits: FieldBuilder<number, false, false>;
+    mode: FieldBuilder<number, false, false>;
+}, import("./index.js").BuilderInitProps<{
+    min: FieldBuilder<number, false, false>;
+    max: FieldBuilder<number, false, false>;
+    bits: FieldBuilder<number, false, false>;
+    mode: FieldBuilder<number, false, false>;
+}>, typeof Schema>;
+export type QuantizedDescriptor = SchemaType<typeof QuantizedDescriptor>;
 export declare const ReflectionField: import("./annotations.js").SchemaWithExtendsConstructor<{
     name: FieldBuilder<string, false, false>;
     type: FieldBuilder<string, false, false>;
     referencedType: FieldBuilder<number, false, false>;
+    /** Primitive child of a collection (`array`/`map`/... of "string" etc.) —
+     *  its own slot, replacing the legacy `"array:string"` colon packing. */
+    childPrimitive: FieldBuilder<string, false, false>;
+    /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
+     *  default; its absence is the "not quantized" signal on decode). */
+    quantized: FieldBuilder<{} & {
+        min?: number;
+        max?: number;
+        bits?: number;
+        mode?: number;
+    } & Schema<any> & Schema<unknown>, false, true>;
 }, import("./index.js").BuilderInitProps<{
     name: FieldBuilder<string, false, false>;
     type: FieldBuilder<string, false, false>;
     referencedType: FieldBuilder<number, false, false>;
+    /** Primitive child of a collection (`array`/`map`/... of "string" etc.) —
+     *  its own slot, replacing the legacy `"array:string"` colon packing. */
+    childPrimitive: FieldBuilder<string, false, false>;
+    /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
+     *  default; its absence is the "not quantized" signal on decode). */
+    quantized: FieldBuilder<{} & {
+        min?: number;
+        max?: number;
+        bits?: number;
+        mode?: number;
+    } & Schema<any> & Schema<unknown>, false, true>;
 }>, typeof Schema>;
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 export declare const ReflectionType: import("./annotations.js").SchemaWithExtendsConstructor<{
@@ -61,7 +100,14 @@ export declare const ReflectionType: import("./annotations.js").SchemaWithExtend
     fields: FieldBuilder<ArraySchema<{} & {
         name?: string;
         type?: string;
+        quantized?: {} & {
+            min?: number;
+            max?: number;
+            bits?: number;
+            mode?: number;
+        } & Schema<any> & Schema<unknown>;
         referencedType?: number;
+        childPrimitive?: string;
     } & Schema<any> & Schema<unknown>>, true, false>;
 }, import("./index.js").BuilderInitProps<{
     id: FieldBuilder<number, false, false>;
@@ -69,7 +115,14 @@ export declare const ReflectionType: import("./annotations.js").SchemaWithExtend
     fields: FieldBuilder<ArraySchema<{} & {
         name?: string;
         type?: string;
+        quantized?: {} & {
+            min?: number;
+            max?: number;
+            bits?: number;
+            mode?: number;
+        } & Schema<any> & Schema<unknown>;
         referencedType?: number;
+        childPrimitive?: string;
     } & Schema<any> & Schema<unknown>>, true, false>;
 }>, typeof Schema>;
 export type ReflectionType = SchemaType<typeof ReflectionType>;

package/build/Schema.d.ts

@@ -2,7 +2,7 @@ import { OPERATION } from './encoding/spec.js';
 import { type DefinitionType } from "./annotations.js";
 import { AssignableProps, NonFunctionPropNames, ToJSON } from './types/HelperTypes.js';
 import { ChangeTree, IRef, Ref } from './encoder/ChangeTree.js';
-import { $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $refId, $track, $values } from './types/symbols.js';
+import { $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $refId, $reset, $track, $values } from './types/symbols.js';
 import { StateView } from './encoder/StateView.js';
 import type { Decoder } from './decoder/Decoder.js';
 import type { Metadata } from './Metadata.js';
@@ -37,6 +37,31 @@ export declare class Schema<C = any> implements IRef {
     static initializeForDecoder<T extends Schema = Schema>(this: {
         prototype: T;
     } & typeof Schema): T;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Check whether `type` describes a Schema *class* (a subclass
      * constructor carrying `Symbol.metadata`, as installed by `@type`).

package/build/annotations.d.ts

@@ -55,7 +55,14 @@ export interface TypeOptions {
     manual?: boolean;
 }
 export declare const DEFAULT_VIEW_TAG = -1;
-export declare function entity(constructor: any): any;
+/**
+ * Class decorator that registers a `@type`-style Schema class with the
+ * TypeContext (required for reflection / cross-language codegen).
+ *
+ *     @entity
+ *     class Player extends Schema { ... }
+ */
+export declare function entity<T extends Function>(constructor: T): T;
 /**
  * [See documentation](https://docs.colyseus.io/state/schema/)
  *
@@ -96,6 +103,14 @@ export declare function getPropertyDescriptor(fieldName: string, fieldIndex: num
  * The previous `@type()` annotation should remain along with this one.
  */
 export declare function deprecated(throws?: boolean): PropertyDecorator;
+/**
+ * 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 declare function defineTypes(target: typeof Schema, fields: Definition, options?: TypeOptions): typeof Schema;
 type ExtractInitProps<T> = T extends {
     initialize: (...args: infer P) => void;
 } ? P extends readonly [] ? never : P extends readonly [infer First] ? First extends object ? First : P : P : BuilderInitProps<T>;

package/build/codegen/cli.cjs

@@ -84,21 +84,11 @@ class Context {
     interfaces = [];
     enums = [];
     getStructures() {
+        // `isSchemaClass` already walks the full ancestor chain, so a class is
+        // emitted iff it (or any ancestor) descends from Schema — no need to
+        // re-walk parents here.
         return {
-            classes: this.classes.filter(klass => {
-                if (this.isSchemaClass(klass)) {
-                    return true;
-                }
-                else {
-                    let parentClass = klass;
-                    while (parentClass = this.getParentClass(parentClass)) {
-                        if (this.isSchemaClass(parentClass)) {
-                            return true;
-                        }
-                    }
-                }
-                return false;
-            }),
+            classes: this.classes.filter(klass => this.isSchemaClass(klass)),
             interfaces: this.interfaces,
             enums: this.enums,
         };
@@ -118,30 +108,25 @@ class Context {
             this.enums.push(structure);
         }
     }
-    getParentClass(klass) {
-        return this.classes.find(c => c.name === klass.extends);
-    }
     isSchemaClass(klass) {
-        let isSchema = false;
-        let currentClass = klass;
-        while (!isSchema && currentClass) {
-            //
-            // TODO: ideally we should check for actual @colyseus/schema module
-            // reference rather than arbitrary strings.
-            //
-            isSchema = (currentClass.extends === "Schema" ||
-                currentClass.extends === "schema.Schema" ||
-                currentClass.extends === "Schema.Schema");
-            //
-            // When extending from `schema.Schema`, it is required to
-            // normalize as "Schema" for code generation.
-            //
-            if (currentClass === klass && isSchema) {
-                klass.extends = "Schema";
+        // True if `klass` or any ancestor extends Schema (directly or via the
+        // `schema.Schema` / `Schema.Schema` aliases).
+        //
+        // TODO: ideally we should check for the actual @colyseus/schema module
+        // reference rather than arbitrary strings.
+        for (const current of [klass, ...eachAncestor(klass, this.classes)]) {
+            const isSchema = (current.extends === "Schema" ||
+                current.extends === "schema.Schema" ||
+                current.extends === "Schema.Schema");
+            if (isSchema) {
+                // Normalize a `schema.Schema`-style base on the queried class itself.
+                if (current === klass) {
+                    klass.extends = "Schema";
+                }
+                return true;
             }
-            currentClass = this.getParentClass(currentClass);
         }
-        return isSchema;
+        return false;
     }
 }
 class Interface {
@@ -170,14 +155,11 @@ class Class {
         this.properties.push(property);
     }
     postProcessing() {
-        /**
-         * Ensure the proprierties `index` are correct using inheritance
-         */
-        let parentKlass = this;
-        while (parentKlass &&
-            (parentKlass = this.context.classes.find(k => k.name === parentKlass.extends))) {
+        // Offset each property's `index` by the field count of every ancestor,
+        // so indexes stay correct across inheritance.
+        for (const parent of eachAncestor(this, this.context.classes)) {
             this.properties.forEach(prop => {
-                prop.index += parentKlass.properties.length;
+                prop.index += parent.properties.length;
             });
         }
     }
@@ -197,22 +179,37 @@ class Property {
     childType;
     deprecated;
 }
-function getInheritanceTree(klass, allClasses, includeSelf = true) {
-    let currentClass = klass;
-    let inheritanceTree = [];
-    if (includeSelf) {
-        inheritanceTree.push(currentClass);
-    }
-    while (currentClass.extends !== "Schema") {
-        currentClass = allClasses.find(klass => klass.name == currentClass.extends);
-        inheritanceTree.push(currentClass);
+/**
+ * Walk `klass`'s `extends` chain, parent-first, yielding each ancestor class
+ * (not `klass` itself). The single safe ancestor traversal every inheritance
+ * query is built on: it stops at the Schema root, an unresolved base, or a
+ * cycle — so a malformed class graph can never spin forever. This is why the
+ * `seen` cycle-guard lives here and nowhere else.
+ */
+function* eachAncestor(klass, allClasses) {
+    const seen = new Set([klass]);
+    let current = klass;
+    while (current.extends && current.extends !== "Schema") {
+        const parent = allClasses.find(c => c.name === current.extends);
+        if (!parent || seen.has(parent)) {
+            return;
+        }
+        seen.add(parent);
+        yield parent;
+        current = parent;
     }
-    return inheritanceTree;
+}
+function getInheritanceTree(klass, allClasses, includeSelf = true) {
+    return [
+        ...(includeSelf ? [klass] : []),
+        ...eachAncestor(klass, allClasses),
+    ];
 }
 
 let currentStructure;
 let currentProperty;
 let globalContext;
+let defineTypesWarned = false;
 const BUILDER_COLLECTION_KINDS = new Set(["array", "map", "set", "collection"]);
 /**
  * For a t.*().chain().calls() expression, walk down to the base `t.X(...)`
@@ -423,6 +420,34 @@ function inspectNode(node, context, decoratorName) {
                     defineProperty(property, prop.initializer);
                 }
             }
+            else if (node.getText() === "defineTypes" &&
+                (node.parent.kind === ts__namespace.SyntaxKind.CallExpression ||
+                    node.parent.kind === ts__namespace.SyntaxKind.PropertyAccessExpression)) {
+                /**
+                 * JavaScript source file (`.js`)
+                 * Using `defineTypes()` (deprecated)
+                 */
+                const callExpression = (node.parent.kind === ts__namespace.SyntaxKind.PropertyAccessExpression)
+                    ? node.parent.parent
+                    : node.parent;
+                if (callExpression.kind !== ts__namespace.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];
+                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__namespace.SyntaxKind.ClassDeclaration) {
                 currentStructure.name = node.getText();
             }
@@ -442,7 +467,7 @@ function inspectNode(node, context, decoratorName) {
                 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?)
@@ -460,24 +485,38 @@ function inspectNode(node, context, decoratorName) {
                         className = nameArg.getText();
                     }
                 }
-                if (!className && callExpression.parent.kind === ts__namespace.SyntaxKind.VariableDeclaration) {
-                    className = callExpression.parent.name?.getText();
+                if (!className) {
+                    // No explicit name arg — infer it from the variable the
+                    // result is assigned to (`const Foo = schema({...})`).
+                    let p = callExpression.parent;
+                    while (p !== undefined && (p.kind === ts__namespace.SyntaxKind.PropertyAccessExpression ||
+                        p.kind === ts__namespace.SyntaxKind.CallExpression)) {
+                        p = p.parent;
+                    }
+                    if (p?.kind === ts__namespace.SyntaxKind.VariableDeclaration) {
+                        className = p.name?.getText();
+                    }
                 }
                 if (!className)
                     break;
-                if (currentStructure?.name !== className) {
-                    currentStructure = new Class();
-                    context.addStructure(currentStructure);
-                }
+                // 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) {
-                    const extendsClass = node.expression?.expression?.escapedText;
-                    if (!extendsClass)
+                    extendsClass = node.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;
-                    currentStructure.extends = extendsClass;
+                    }
                 }
-                else {
-                    currentStructure.extends = "Schema";
+                if (currentStructure?.name !== className) {
+                    currentStructure = new Class();
+                    context.addStructure(currentStructure);
                 }
+                currentStructure.extends = extendsClass;
                 currentStructure.name = className;
                 const types = fieldsArg;
                 for (let i = 0; i < types.properties.length; i++) {