@colyseus/schema 4.0.19 → 5.0.0

package/src/codegen/parser.ts

@@ -8,7 +8,54 @@ let currentProperty: Property;
 
 let globalContext: Context;
 
+const BUILDER_COLLECTION_KINDS = new Set(["array", "map", "set", "collection"]);
+
+/**
+ * For a t.*().chain().calls() expression, walk down to the base `t.X(...)`
+ * call and return its method name and first argument. Returns null if the
+ * node does not look like a builder chain.
+ */
+function extractBuilderBase(node: ts.CallExpression): { methodName: string, firstArg?: ts.Expression } | null {
+    let current: ts.CallExpression = node;
+    while (true) {
+        const expr = current.expression;
+        if (!ts.isPropertyAccessExpression(expr)) {
+            return null;
+        }
+        if (ts.isCallExpression(expr.expression)) {
+            // Chained modifier, e.g. .default() / .view() — walk deeper.
+            current = expr.expression;
+            continue;
+        }
+        return {
+            methodName: expr.name.text,
+            firstArg: current.arguments[0],
+        };
+    }
+}
+
 function defineProperty(property: Property, initializer: any) {
+    // Builder-style: t.number(), t.array(Item), t.map(Item).view(), etc.
+    if (ts.isCallExpression(initializer)) {
+        const base = extractBuilderBase(initializer);
+        if (base) {
+            if (BUILDER_COLLECTION_KINDS.has(base.methodName)) {
+                property.type = base.methodName;
+                if (base.firstArg) {
+                    property.childType = (base.firstArg as any).text ?? base.firstArg.getText();
+                }
+            } else if (base.methodName === "ref") {
+                property.type = "ref";
+                if (base.firstArg) {
+                    property.childType = (base.firstArg as any).text ?? base.firstArg.getText();
+                }
+            } else {
+                property.type = base.methodName;
+            }
+            return;
+        }
+    }
+
     if (ts.isIdentifier(initializer)) {
         property.type = "ref";
         property.childType = initializer.text;
@@ -207,39 +254,6 @@ 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()`
-                 */
-                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;
-                }
-
-                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) {
@@ -252,58 +266,66 @@ function inspectNode(node: ts.Node, context: Context, decoratorName: string) {
 
         case ts.SyntaxKind.CallExpression:
             /**
-             * Defining schema via `schema.schema({ ... })`
-             * - schema.schema({})
-             * - schema({})
-             * - ClassName.extends({})
+             * Defining schema via:
+             * - schema({ ... })
+             * - schema({ ... }, 'Name')
+             * - schema.schema({ ... }, 'Name')
+             * - ParentClass.extend({ ... }, 'Name')
              */
-            if (
-                (
-                    (
-                        (node as ts.CallExpression).expression?.getText() === "schema.schema" ||
-                        (node as ts.CallExpression).expression?.getText() === "schema"
-                    ) ||
-                    (
-                        (node as ts.CallExpression).expression?.getText().indexOf(".extends") !== -1
-                    )
-                ) &&
-                (node as ts.CallExpression).arguments[0].kind === ts.SyntaxKind.ObjectLiteralExpression
-            ) {
+            {
                 const callExpression = node as ts.CallExpression;
+                const callee = callExpression.expression?.getText?.();
+                if (!callee) break;
+
+                const isSchemaCall = callee === "schema" || callee === "schema.schema";
+                const isExtendCall = callee.indexOf(".extend") !== -1 && !callee.endsWith(".extends");
+                if (!isSchemaCall && !isExtendCall) break;
+
+                // Signature: (fields, name?)
+                const fieldsArg = callExpression.arguments[0];
+                const nameArg = callExpression.arguments[1];
+                if (!fieldsArg || fieldsArg.kind !== ts.SyntaxKind.ObjectLiteralExpression) {
+                    break;
+                }
 
-                let className = callExpression.arguments[1]?.getText();
+                let className: string | undefined;
+                if (nameArg) {
+                    if (nameArg.kind === ts.SyntaxKind.StringLiteral) {
+                        className = (nameArg as ts.StringLiteral).text;
+                    } else {
+                        className = nameArg.getText();
+                    }
+                }
 
                 if (!className && callExpression.parent.kind === ts.SyntaxKind.VariableDeclaration) {
                     className = (callExpression.parent as ts.VariableDeclaration).name?.getText();
                 }
 
-                // skip if no className is provided
-                if (!className) { break; }
+                if (!className) break;
 
                 if (currentStructure?.name !== className) {
                     currentStructure = new Class();
                     context.addStructure(currentStructure);
                 }
 
-                if ((node as ts.CallExpression).expression?.getText().indexOf(".extends") !== -1) {
-                    // if it's using `.extends({})`
+                if (isExtendCall) {
                     const extendsClass = (node as any).expression?.expression?.escapedText;
-
-                    // skip if no extendsClass is provided
-                    if (!extendsClass) { break; }
+                    if (!extendsClass) break;
                     (currentStructure as Class).extends = extendsClass;
-
                 } else {
-                    // if it's using `schema({})`
-                    (currentStructure as Class).extends = "Schema"; // force extends to Schema
+                    (currentStructure as Class).extends = "Schema";
                 }
 
                 currentStructure.name = className;
 
-                const types = callExpression.arguments[0] as any;
+                const types = fieldsArg as any;
                 for (let i = 0; i < types.properties.length; i++) {
                     const prop = types.properties[i];
 
+                    // Skip methods declared inside the fields object.
+                    if (prop.kind === ts.SyntaxKind.MethodDeclaration) continue;
+                    if (!prop.initializer) continue;
+
                     const property = currentProperty || new Property();
                     property.name = prop.name.escapedText;
 

package/src/decoder/DecodeOperation.ts

@@ -4,7 +4,7 @@ import { Schema } from "../Schema.js";
 import type { IRef, Ref } from "../encoder/ChangeTree.js";
 import type { Decoder } from "./Decoder.js";
 import { Iterator, decode } from "../encoding/decode.js";
-import { $childType, $deleteByIndex, $getByIndex, $refId } from "../types/symbols.js";
+import { $childType, $deleteByIndex, $getByIndex, $proxyTarget, $refId } from "../types/symbols.js";
 
 import type { ArraySchema } from "../types/custom/ArraySchema.js";
 
@@ -15,7 +15,8 @@ export interface DataChange<T = any, F = string> {
     ref: IRef,
     refId: number,
     op: OPERATION,
-    field: F;
+    /** Set for Schema field changes; omitted for collection item changes (which carry a `dynamicIndex` instead). */
+    field?: F;
     dynamicIndex?: number | string;
     value: T;
     previousValue: T;
@@ -23,26 +24,73 @@ export interface DataChange<T = any, F = string> {
 
 export const DEFINITION_MISMATCH = -1;
 
+/**
+ * When no `triggerChanges` subscriber is attached, `Decoder.decode` passes
+ * `null` so the per-field change objects are never allocated. Every push
+ * site uses `allChanges?.push(...)` — optional chaining also short-circuits
+ * the object literal, so there's nothing to collect and nothing to throw
+ * away.
+ */
 export type DecodeOperation<T extends Schema = any> = (
     decoder: Decoder<T>,
     bytes: Uint8Array,
     it: Iterator,
     ref: IRef,
-    allChanges: DataChange[],
+    allChanges: DataChange[] | null,
 ) => number | void;
 
+/**
+ * Collection-kind discriminator declared on each collection class as
+ * `static COLLECTION_KIND = CollectionKind.X`. The decoder's key/value
+ * dispatch used to make three back-to-back `typeof(ref.method) ===
+ * "function"` checks per entry; those collapse into one switch on the
+ * target's class tag. Missing / `undefined` on a ref hits the switch's
+ * `default` branch and logs a warning — a guard for future collection
+ * types that land without a tag.
+ *
+ * Declared as a `const` object (not a TS `enum`) so the codegen parser —
+ * which picks up every `EnumDeclaration` in the lib source via transitive
+ * imports — doesn't emit a generated .cs file for it.
+ */
+export const CollectionKind = {
+    Map: 1,
+    Array: 2,
+    Set: 3,
+    Collection: 4,
+    Stream: 5,
+} as const;
+export type CollectionKind = typeof CollectionKind[keyof typeof CollectionKind];
+
+/**
+ * Structural type for any class that participates in the `decodeKeyValue-
+ * Operation` dispatch. Lets the hot-path read `tgt.constructor.COLLECTION_KIND`
+ * without an `any` cast.
+ */
+export interface CollectionCtor {
+    readonly COLLECTION_KIND: CollectionKind;
+}
+
+/**
+ * Decode the next wire value for `ref[index]`. Returns the decoded value.
+ *
+ * Callers pass `previousValue` explicitly — it's the current value at the
+ * slot before decoding and is needed for ref-count bookkeeping (on DELETE)
+ * and for the DELETE_AND_ADD self-reassign case. Keeping it as a parameter
+ * lets this function return a single primitive instead of a pair, so the
+ * hot call path allocates nothing.
+ */
 export function decodeValue<T extends Ref>(
     decoder: Decoder,
     operation: OPERATION,
     ref: T,
     index: number,
+    previousValue: any,
     type: any,
     bytes: Uint8Array,
     it: Iterator,
-    allChanges: DataChange[],
-) {
+    allChanges: DataChange[] | null,
+): any {
     const $root = decoder.root;
-    const previousValue = (ref as any)[$getByIndex](index) as T;
 
     let value: any;
 
@@ -56,7 +104,7 @@ export function decodeValue<T extends Ref>(
         // Delete operations
         //
         if (operation !== OPERATION.DELETE_AND_ADD) {
-            (ref as any)[$deleteByIndex](index);
+            ref[$deleteByIndex](index);
         }
 
         value = undefined;
@@ -67,6 +115,15 @@ export function decodeValue<T extends Ref>(
         // Don't do anything
         //
 
+    } else if (typeof (type) === "string") {
+        //
+        // Primitive value (number, string, boolean, …). Hot-path first
+        // because steady-state ticks are dominated by primitive field
+        // updates — moves us past a cheap typeof check instead of a
+        // Symbol-metadata lookup via `Schema.is`.
+        //
+        value = (decode as any)[type](bytes, it);
+
     } else if (Schema.is(type)) {
         const refId = decode.number(bytes, it);
         value = $root.refs.get(refId);
@@ -87,19 +144,17 @@ export function decodeValue<T extends Ref>(
             );
         }
 
-    } else if (typeof(type) === "string") {
-        //
-        // primitive value (number, string, boolean, etc)
-        //
-        value = (decode as any)[type](bytes, it);
-
     } else {
         const typeDef = getType(Object.keys(type)[0]);
         const refId = decode.number(bytes, it);
 
+        // `initializeForDecoder` is a static on every registered collection
+        // class — it does `Object.create(Class.prototype)` + the class-
+        // field init + assigns an untracked `$changes` directly. Keeps
+        // the decoder free of collection-type internals.
         const valueRef: Ref = ($root.refs.has(refId))
             ? previousValue || $root.refs.get(refId)
-            : new typeDef.constructor();
+            : (typeDef.constructor as any).initializeForDecoder();
 
         value = valueRef.clone(true);
         value[$childType] = Object.values(type)[0]; // cache childType for ArraySchema and MapSchema
@@ -122,7 +177,7 @@ export function decodeValue<T extends Ref>(
                         $root.removeRef(previousRefId);
                     }
 
-                    allChanges.push({
+                    allChanges?.push({
                         ref: previousValue,
                         refId: previousRefId,
                         op: OPERATION.DELETE,
@@ -141,7 +196,7 @@ export function decodeValue<T extends Ref>(
         ));
     }
 
-    return { value, previousValue };
+    return value;
 }
 
 export const decodeSchemaOperation: DecodeOperation = function <T extends Schema>(
@@ -149,7 +204,7 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
     bytes: Uint8Array,
     it: Iterator,
     ref: T,
-    allChanges: DataChange[],
+    allChanges: DataChange[] | null,
 ) {
     const first_byte = bytes[it.offset++];
     const metadata: Metadata = (ref.constructor as typeof Schema)[Symbol.metadata];
@@ -165,11 +220,13 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
         return DEFINITION_MISMATCH;
     }
 
-    const { value, previousValue } = decodeValue(
+    const previousValue = ref[$getByIndex](index);
+    const value = decodeValue(
         decoder,
         operation,
         ref,
         index,
+        previousValue,
         field.type,
         bytes,
         it,
@@ -177,12 +234,19 @@ export const decodeSchemaOperation: DecodeOperation = function <T extends Schema
     );
 
     if (value !== null && value !== undefined) {
+        // Write via the generated setter. Bypass to `(ref as any)[$values][index]`
+        // was attempted but only works for @type-decorated classes (which
+        // install accessor descriptors reading from `$values`). Reflection-
+        // decoded classes install a plain data-property descriptor instead,
+        // so their value lives as an own property on the instance — direct
+        // `$values[index]` writes are invisible to the getter on that path.
+        // Two-mode dispatch would cost more than the ~3% it'd save.
         ref[field.name as keyof T] = value;
     }
 
     // add change
     if (previousValue !== value) {
-        allChanges.push({
+        allChanges?.push({
             ref,
             refId: decoder.currentRefId,
             op: operation,
@@ -198,8 +262,14 @@ export const decodeKeyValueOperation: DecodeOperation = function (
     bytes: Uint8Array,
     it: Iterator,
     ref: Ref,
-    allChanges: DataChange[]
+    allChanges: DataChange[] | null,
 ) {
+    // Unwrap ArraySchema Proxy once so subsequent property reads skip the
+    // `get` trap. `$proxyTarget` is a self-reference on the target; on
+    // non-proxied collections (Map/Set/Collection/Stream) the lookup is
+    // undefined and we fall back to `ref`.
+    const tgt: any = (ref as any)[$proxyTarget] ?? ref;
+
     // "uncompressed" index + operation (array/map items)
     const operation = bytes[it.offset++];
 
@@ -209,34 +279,38 @@ export const decodeKeyValueOperation: DecodeOperation = function (
         // - enqueue items for DELETE callback.
         // - flag child items for garbage collection.
         //
-        decoder.removeChildRefs(ref as unknown as Collection, allChanges);
+        decoder.removeChildRefs(tgt as Collection, allChanges);
 
-        (ref as any).clear();
+        tgt.clear();
         return;
     }
 
     const index = decode.number(bytes, it);
-    const type = (ref as any)[$childType];
+    const type = tgt[$childType];
+    // One constructor lookup, one integer read → switch. Replaces three
+    // `typeof(ref.method) === "function"` dispatches per entry.
+    const kind: CollectionKind = (tgt.constructor as CollectionCtor).COLLECTION_KIND;
 
     let dynamicIndex: number | string;
 
     if ((operation & OPERATION.ADD) === OPERATION.ADD) { // ADD or DELETE_AND_ADD
-        if (typeof((ref as any)['set']) === "function") {
-            dynamicIndex = decode.string(bytes, it); // MapSchema
-            (ref as any)['setIndex'](index, dynamicIndex);
+        if (kind === CollectionKind.Map) {
+            dynamicIndex = decode.string(bytes, it); // MapSchema uses a wire-delivered string key
+            tgt.setIndex(index, dynamicIndex);
         } else {
-            dynamicIndex = index; // ArraySchema
+            dynamicIndex = index;
         }
     } else {
-        // get dynamic index from "ref"
-        dynamicIndex = (ref as any)['getIndex'](index);
+        dynamicIndex = tgt.getIndex(index);
     }
 
-    const { value, previousValue } = decodeValue(
+    const previousValue = tgt[$getByIndex](index);
+    const value = decodeValue(
         decoder,
         operation,
         ref,
         index,
+        previousValue,
         type,
         bytes,
         it,
@@ -244,31 +318,57 @@ export const decodeKeyValueOperation: DecodeOperation = function (
     );
 
     if (value !== null && value !== undefined) {
-        if (typeof((ref as any)['set']) === "function") {
-            // MapSchema
-            (ref as any)['$items'].set(dynamicIndex as string, value);
-
-        } else if (typeof((ref as any)['$setAt']) === "function") {
-            // ArraySchema
-            (ref as any)['$setAt'](index, value, operation);
-
-        } else if (typeof((ref as any)['add']) === "function") {
-            // CollectionSchema && SetSchema
-            const index = (ref as any).add(value);
-
-            if (typeof(index) === "number") {
-                (ref as any)['setIndex'](index, index);
-            }
+        switch (kind) {
+            case CollectionKind.Map:
+                tgt.$items.set(dynamicIndex as string, value);
+                break;
+
+            case CollectionKind.Array:
+                tgt.$setAt(index, value, operation);
+                break;
+
+            // SetSchema / CollectionSchema / StreamSchema — use the wire-
+            // index we decoded above so server/client `$items` stay in sync
+            // regardless of duplicate emission (e.g. a bootstrap that walks
+            // both `encodeAll` and the shared recorder emits the same ADD
+            // op twice). Previous implementation called `ref.add(value)`
+            // and let the decoder-side `$refId++` allocate a new index per
+            // call — which for CollectionSchema (no value-dedup) turned
+            // duplicate wire ADDs into duplicate client-side entries.
+            case CollectionKind.Set:
+            case CollectionKind.Collection:
+            case CollectionKind.Stream:
+                if (!tgt.$items.has(index)) {
+                    tgt.$items.set(index, value);
+                    // Keep the decoder's monotonic counter ahead of any
+                    // wire-index we've seen so future server-side `.add()`
+                    // allocations don't collide with ones already decoded.
+                    // (StreamSchema has no `$refId` counter — `typeof`
+                    // guards the Set/Collection path.)
+                    if (typeof tgt.$refId === "number" && index >= tgt.$refId) {
+                        tgt.$refId = index + 1;
+                    }
+                }
+                break;
+
+            default:
+                // A future collection type landed without a COLLECTION_KIND
+                // tag. Surface it loudly instead of silently dropping the
+                // value — the missing entry here is the only place the new
+                // type's item-storage semantics need to be wired up.
+                console.warn(
+                    `@colyseus/schema: missing COLLECTION_KIND on ${tgt.constructor?.name} — item at index ${index} was not stored.`
+                );
+                break;
         }
     }
 
     // add change
     if (previousValue !== value) {
-        allChanges.push({
+        allChanges?.push({
             ref,
             refId: decoder.currentRefId,
             op: operation,
-            field: "", // FIXME: remove this
             dynamicIndex,
             value,
             previousValue,
@@ -281,8 +381,11 @@ export const decodeArray: DecodeOperation = function (
     bytes: Uint8Array,
     it: Iterator,
     ref: ArraySchema,
-    allChanges: DataChange[]
+    allChanges: DataChange[] | null,
 ) {
+    // Unwrap the Proxy once — ref is always an ArraySchema here.
+    const tgt: any = (ref as any)[$proxyTarget] ?? ref;
+
     // "uncompressed" index + operation (array/map items)
     let operation = bytes[it.offset++];
     let index: number;
@@ -293,25 +396,24 @@ export const decodeArray: DecodeOperation = function (
         // - enqueue items for DELETE callback.
         // - flag child items for garbage collection.
         //
-        decoder.removeChildRefs(ref as unknown as Collection, allChanges);
-        (ref as ArraySchema).clear();
+        decoder.removeChildRefs(tgt as Collection, allChanges);
+        tgt.clear();
         return;
 
     } else if (operation === OPERATION.REVERSE) {
-        (ref as ArraySchema).reverse();
+        tgt.reverse();
         return;
 
     } else if (operation === OPERATION.DELETE_BY_REFID) {
         // TODO: refactor here, try to follow same flow as below
         const refId = decode.number(bytes, it);
         const previousValue = decoder.root.refs.get(refId);
-        index = ref.findIndex((value) => value === previousValue);
-        ref[$deleteByIndex](index);
-        allChanges.push({
+        index = tgt.findIndex((value: any) => value === previousValue);
+        tgt[$deleteByIndex](index);
+        allChanges?.push({
             ref,
             refId: decoder.currentRefId,
             op: OPERATION.DELETE,
-            field: "", // FIXME: remove this
             dynamicIndex: index,
             value: undefined,
             previousValue,
@@ -325,27 +427,32 @@ export const decodeArray: DecodeOperation = function (
 
         // if item already exists, use existing index
         if (itemByRefId) {
-            index = ref.findIndex((value) => value === itemByRefId);
+            index = tgt.findIndex((value: any) => value === itemByRefId);
         }
 
         // fallback to use last index
         if (index === -1 || index === undefined) {
-            index = ref.length;
+            index = tgt.length;
         }
 
     } else {
         index = decode.number(bytes, it);
     }
 
-    const type = ref[$childType];
+    const type = tgt[$childType];
 
     let dynamicIndex: number | string = index;
 
-    const { value, previousValue } = decodeValue(
+    // Direct `items[index]` read — ArraySchema's `$getByIndex` is encoder-only
+    // (it consults `tmpItems`/`deletedIndexes`, which the decoder doesn't
+    // maintain). The decoder's authoritative state is `items`.
+    const previousValue = tgt.items[index];
+    const value = decodeValue(
         decoder,
         operation,
         ref,
         index,
+        previousValue,
         type,
         bytes,
         it,
@@ -356,17 +463,15 @@ export const decodeArray: DecodeOperation = function (
         value !== null && value !== undefined &&
         value !== previousValue // avoid setting same value twice (if index === 0 it will result in a "unshift" for ArraySchema)
     ) {
-        // ArraySchema
-        (ref as ArraySchema)['$setAt'](index, value, operation);
+        tgt.$setAt(index, value, operation);
     }
 
     // add change
     if (previousValue !== value) {
-        allChanges.push({
+        allChanges?.push({
             ref,
             refId: decoder.currentRefId,
             op: operation,
-            field: "", // FIXME: remove this
             dynamicIndex,
             value,
             previousValue,