@colyseus/schema 4.0.20 → 5.0.0

package/src/encoder/EncodeDescriptor.ts

@@ -0,0 +1,213 @@
+/**
+ * EncodeDescriptor — per-class snapshot of the values the encode loop needs
+ * from a Ref's constructor. Lazily computed once per class (the first time
+ * a tree of that class is constructed) and stashed on the constructor via
+ * `$encodeDescriptor`. Each ChangeTree caches a reference to its class's
+ * descriptor at construction time, so the encode loop reads a single
+ * property from the tree instead of chasing 5 separate per-tree lookups:
+ *
+ *   ctor[$encoder]
+ *   ctor[$filter]
+ *   ctor[Symbol.metadata]
+ *   Metadata.isValidInstance(ref)
+ *   getFilterBitmask(metadata)
+ *
+ * Lives in its own file to break the Encoder.ts ↔ ChangeTree.ts import
+ * cycle (ChangeTree caches descriptors at construction; Encoder reads them
+ * during encode).
+ */
+import { Metadata } from "../Metadata.js";
+import { $encodeDescriptor, $encoder, $encoders, $filter, $filterBitmask, $numFields, $staticFieldIndexes, $streamFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "../types/symbols.js";
+import type { StateView } from "./StateView.js";
+import type { EncodeOperation } from "./EncodeOperation.js";
+
+export interface EncodeDescriptor {
+    encoder: EncodeOperation;
+    filter: ((ref: any, index: number, view?: StateView) => boolean) | undefined;
+    metadata: any;
+    isSchema: boolean;
+    /**
+     * Bit i set iff field i has a @view tag. 0 for collection trees.
+     * Lets `encodeChangeCb` do a single bitwise op instead of a
+     * per-field metadata[i]?.tag chase.
+     */
+    filterBitmask: number;
+
+    /**
+     * Class-level "any field has the flag" booleans + per-field bitmasks.
+     * Hot path: per-mutation `_routeAndRecord` calls `isFieldStatic` and
+     * `isFieldUnreliable`. The common case is "no static/unreliable fields
+     * anywhere on this class" (booleans short-circuit before the symbol-keyed
+     * metadata lookup); the secondary common case is "this class has some
+     * such fields and we need to know if THIS field is one" — the bitmask
+     * answers in one bitwise op instead of an `Array.includes` linear scan.
+     *
+     * Bitmasks cover fields 0–31 only (matches the `filterBitmask` limitation).
+     * Fields ≥32 fall back to `Metadata.hasXAtIndex` — same handling as the
+     * filter-bitmask path.
+     */
+    hasAnyStatic: boolean;
+    hasAnyUnreliable: boolean;
+    hasAnyStream: boolean;
+    /**
+     * Class-level "any field carries a `@view` tag" — covers fields both
+     * within and beyond index 31 (unlike `filterBitmask`, which only
+     * captures the low 32). Read by `ChangeTree.hasFilteredFields` to
+     * decide whether a parent tree must be included in a view's bootstrap.
+     */
+    hasAnyView: boolean;
+    staticBitmask: number;
+    unreliableBitmask: number;
+    /**
+     * Bit i set iff field i holds a `t.stream(...)` collection. Hot encode
+     * path reads this to dispatch stream fields into the priority/budget
+     * gate instead of the normal recorder iteration.
+     */
+    streamBitmask: number;
+
+    /**
+     * Per-field parallel arrays — Schemas only (empty arrays for
+     * collections). Replaces hot-path `metadata[i].name` / `metadata[i].type`
+     * / `metadata[i].tag` chains with direct array indexing on a small
+     * fixed-shape object.
+     *
+     * Sparse where natural: `tags[i]` is undefined unless field i carries
+     * a @view tag; readers should null-check before comparing.
+     *
+     * `encoders[i]` mirrors `metadata[$encoders]` — the pre-computed
+     * encoder fn for primitive-typed fields. Cached here so encode loops
+     * skip a `metadata[$encoders]?.[i]` symbol-chain per emission.
+     */
+    names: string[];
+    types: any[];
+    tags: (number | undefined)[];
+    encoders: (((bytes: Uint8Array, value: any, it: any) => void) | undefined)[];
+}
+
+function computeFilterBitmask(metadata: any): number {
+    if (metadata === undefined) return 0;
+    let bm: number | undefined = metadata[$filterBitmask];
+    if (bm !== undefined) return bm;
+    bm = 0;
+    const tagged = metadata[$viewFieldIndexes];
+    if (tagged !== undefined) {
+        for (let i = 0, len = tagged.length; i < len; i++) bm |= (1 << tagged[i]);
+    }
+    // Non-enumerable so `for (const k in metadata)` iteration in TypeContext
+    // and elsewhere doesn't mistake this cache for a real field index.
+    Object.defineProperty(metadata, $filterBitmask, {
+        value: bm,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return bm;
+}
+
+/**
+ * Bitmask of field indexes 0–31 in `indexes`. For fields ≥32 callers must
+ * fall back to the array lookup (same as `filterBitmask`).
+ */
+function indexesToBitmask(indexes: number[] | undefined): number {
+    if (indexes === undefined) return 0;
+    let bm = 0;
+    for (let i = 0, len = indexes.length; i < len; i++) {
+        const idx = indexes[i];
+        if (idx < 32) bm |= (1 << idx);
+    }
+    return bm;
+}
+
+/**
+ * Build the per-field parallel arrays once at descriptor construction.
+ * For collection trees (no metadata or no $numFields) this returns empty
+ * arrays — readers branch on `isSchema` before touching them anyway.
+ */
+function buildFieldArrays(metadata: any): {
+    names: string[];
+    types: any[];
+    tags: (number | undefined)[];
+    encoders: (((bytes: Uint8Array, value: any, it: any) => void) | undefined)[];
+} {
+    const names: string[] = [];
+    const types: any[] = [];
+    const tags: (number | undefined)[] = [];
+    const encoders: (((bytes: Uint8Array, value: any, it: any) => void) | undefined)[] = [];
+
+    if (metadata === undefined) return { names, types, tags, encoders };
+
+    const numFields = metadata[$numFields];
+    if (numFields === undefined) return { names, types, tags, encoders };
+
+    const srcEncoders = metadata[$encoders];
+    for (let i = 0; i <= numFields; i++) {
+        const field = metadata[i];
+        if (field === undefined) {
+            // Holes are normal — inheritance can leave gaps. Fill with
+            // undefined so indexing is valid.
+            names[i] = undefined!;
+            types[i] = undefined;
+            tags[i] = undefined;
+            encoders[i] = undefined;
+            continue;
+        }
+        names[i] = field.name;
+        types[i] = field.type;
+        tags[i] = field.tag;
+        encoders[i] = srcEncoders?.[i];
+    }
+    return { names, types, tags, encoders };
+}
+
+export function getEncodeDescriptor(ref: any): EncodeDescriptor {
+    const ctor = ref.constructor;
+
+    // Use hasOwn — Object.defineProperty on a parent class would otherwise
+    // be inherited by every subclass via the prototype chain, and a
+    // subclass's instance would read the parent's metadata/encoder. See
+    // "should encode the correct class inside an array" for the regression.
+    if (Object.prototype.hasOwnProperty.call(ctor, $encodeDescriptor)) {
+        return ctor[$encodeDescriptor];
+    }
+
+    const metadata = ctor[Symbol.metadata];
+    const isSchema = Metadata.isValidInstance(ref);
+    const hasAnyView = (metadata?.[$viewFieldIndexes]?.length ?? 0) > 0;
+    const arrays = buildFieldArrays(metadata);
+    // For Schema classes with no `@view`-tagged fields, the per-field
+    // `ctx.filter(ref, index, view)` call on the encode hot path is a
+    // provable no-op: `Schema[$filter]` does `metadata[index]?.tag === undefined`
+    // which is always true when no field carries a tag. Setting filter to
+    // `undefined` here lets the `ctx.filter !== undefined && …` short-circuit
+    // in `encodeChangeCb` skip the call entirely — the metadata lookup +
+    // comparison adds up across 10k+ field encodes/tick.
+    // Collection classes keep their filter — their `[$filter]` does
+    // instance-level `ref[$childType]` / view-visibility checks that can't
+    // be decided class-wide.
+    const filter = (isSchema && !hasAnyView) ? undefined : ctor[$filter];
+    const desc: EncodeDescriptor = {
+        encoder: ctor[$encoder],
+        filter,
+        metadata,
+        isSchema,
+        filterBitmask: isSchema ? computeFilterBitmask(metadata) : 0,
+        hasAnyStatic: (metadata?.[$staticFieldIndexes]?.length ?? 0) > 0,
+        hasAnyUnreliable: (metadata?.[$unreliableFieldIndexes]?.length ?? 0) > 0,
+        hasAnyStream: (metadata?.[$streamFieldIndexes]?.length ?? 0) > 0,
+        hasAnyView,
+        staticBitmask: indexesToBitmask(metadata?.[$staticFieldIndexes]),
+        unreliableBitmask: indexesToBitmask(metadata?.[$unreliableFieldIndexes]),
+        streamBitmask: indexesToBitmask(metadata?.[$streamFieldIndexes]),
+        names: arrays.names,
+        types: arrays.types,
+        tags: arrays.tags,
+        encoders: arrays.encoders,
+    };
+    Object.defineProperty(ctor, $encodeDescriptor, {
+        value: desc,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return desc;
+}

package/src/encoder/EncodeOperation.ts

@@ -1,5 +1,5 @@
 import { OPERATION } from "../encoding/spec.js";
-import { $changes, $childType, $getByIndex, $refId } from "../types/symbols.js";
+import { $changes, $childType, $encoders, $getByIndex, $refId, $values } from "../types/symbols.js";
 
 import { encode } from "../encoding/encode.js";
 
@@ -30,8 +30,14 @@ export function encodeValue(
     value: any,
     operation: OPERATION,
     it: Iterator,
+    encoderFn?: (bytes: Uint8Array, value: any, it: Iterator) => void,
 ) {
-    if (typeof (type) === "string") {
+    if (encoderFn !== undefined) {
+        // Fast path: pre-computed encoder for primitive types.
+        encoderFn(bytes, value, it);
+
+    } else if (typeof (type) === "string") {
+        // Fallback for types not pre-computed (e.g. runtime-constructed).
         (encode as any)[type]?.(bytes, value, it);
 
     } else if (type[Symbol.metadata] !== undefined) {
@@ -68,7 +74,6 @@ export const encodeSchemaOperation: EncodeOperation = function <T extends Schema
     it: Iterator,
     _: any,
     __: any,
-    metadata: Metadata,
 ) {
     // "compress" field index + operation
     bytes[it.offset++] = (index | operation) & 255;
@@ -78,25 +83,37 @@ export const encodeSchemaOperation: EncodeOperation = function <T extends Schema
         return;
     }
 
-    const ref = changeTree.ref;
-    const field = metadata[index];
+    // Read field info from the per-class descriptor's parallel arrays —
+    // replaces `metadata[index]` (returns a per-field obj) + `.name` /
+    // `.type` chains. The `encoders` array is also pre-baked here so we
+    // skip a `metadata[$encoders]?.[index]` symbol-keyed lookup per call.
+    const desc = changeTree.encDescriptor;
+    const ref = changeTree.ref as any;
+
+    // Direct $values[index] read — bypasses prototype getter + metadata name lookup.
+    // Falls back to named property for manual fields (which don't use $values).
+    const value = ref[$values][index] ?? ref[desc.names[index]];
 
-    // TODO: inline this function call small performance gain
     encodeValue(
         encoder,
         bytes,
-        metadata[index].type,
-        ref[field.name as keyof T],
+        desc.types[index],
+        value,
         operation,
-        it
+        it,
+        desc.encoders[index],
     );
 }
 
 /**
- * Used for collections (MapSchema, CollectionSchema, SetSchema)
+ * Encode a single MapSchema entry. Splits the legacy
+ * `encodeKeyValueOperation` so the per-emission `typeof ref['set']` check
+ * is gone — MapSchema instances are routed here via their `[$encoder]`
+ * static, the dynamic-key string emission is unconditional on ADD.
+ *
  * @private
  */
-export const encodeKeyValueOperation: EncodeOperation = function (
+export const encodeMapEntry: EncodeOperation = function (
     encoder: Encoder,
     bytes: Uint8Array,
     changeTree: ChangeTree,
@@ -104,59 +121,88 @@ export const encodeKeyValueOperation: EncodeOperation = function (
     operation: OPERATION,
     it: Iterator,
 ) {
-    // encode operation
     bytes[it.offset++] = operation & 255;
-
-    // encode index
     encode.number(bytes, index, it);
 
-    // Do not encode value for DELETE operations
-    if (operation === OPERATION.DELETE) {
-        return;
-    }
+    if (operation === OPERATION.DELETE) return;
 
     const ref = changeTree.ref;
 
-    //
-    // encode "alias" for dynamic fields (maps)
-    //
-    if ((operation & OPERATION.ADD) === OPERATION.ADD) { // ADD or DELETE_AND_ADD
-        if (typeof(ref['set']) === "function") {
-            //
-            // MapSchema dynamic key
-            //
-            const dynamicIndex = changeTree.ref['$indexes'].get(index);
-            encode.string(bytes, dynamicIndex, it);
-        }
+    // ADD or DELETE_AND_ADD: emit the user-facing string key for dynamic
+    // map fields. SetSchema/CollectionSchema use a different encoder and
+    // skip this entirely (no dynamic key).
+    if ((operation & OPERATION.ADD) === OPERATION.ADD) {
+        const dynamicIndex = (ref as any)['$indexes'].get(index);
+        encode.string(bytes, dynamicIndex, it);
     }
 
-    const type = ref[$childType];
-    const value = ref[$getByIndex](index);
-
-    // try { throw new Error(); } catch (e) {
-    //     // only print if not coming from Reflection.ts
-    //     if (!e.stack.includes("src/Reflection.ts")) {
-    //         console.log("encodeKeyValueOperation -> ", {
-    //             ref: changeTree.ref.constructor.name,
-    //             field,
-    //             operation: OPERATION[operation],
-    //             value: value?.toJSON(),
-    //             items: ref.toJSON(),
-    //         });
-    //     }
-    // }
-
-    // TODO: inline this function call small performance gain
     encodeValue(
         encoder,
         bytes,
-        type,
-        value,
+        (ref as any)[$childType],
+        ref[$getByIndex](index),
         operation,
-        it
+        it,
+    );
+}
+
+/**
+ * Encode a single SetSchema / CollectionSchema entry. Wire format is the
+ * same as MapSchema minus the dynamic-key string, so this path skips the
+ * legacy `typeof ref['set']` check entirely.
+ *
+ * @private
+ */
+export const encodeIndexedEntry: EncodeOperation = function (
+    encoder: Encoder,
+    bytes: Uint8Array,
+    changeTree: ChangeTree,
+    index: number,
+    operation: OPERATION,
+    it: Iterator,
+) {
+    bytes[it.offset++] = operation & 255;
+    encode.number(bytes, index, it);
+
+    if (operation === OPERATION.DELETE) return;
+
+    const ref = changeTree.ref;
+    encodeValue(
+        encoder,
+        bytes,
+        (ref as any)[$childType],
+        ref[$getByIndex](index),
+        operation,
+        it,
     );
 }
 
+/**
+ * Unified encoder kept for back-compat with external consumers that may
+ * have registered it directly via `static [$encoder] =
+ * encodeKeyValueOperation`. New code (and all internal collections)
+ * should use the split variants — `encodeMapEntry` for MapSchema and
+ * `encodeIndexedEntry` for SetSchema / CollectionSchema.
+ *
+ * The runtime `typeof ref['set']` check below is the per-emission cost
+ * the split is designed to remove.
+ */
+export const encodeKeyValueOperation: EncodeOperation = function (
+    encoder: Encoder,
+    bytes: Uint8Array,
+    changeTree: ChangeTree,
+    index: number,
+    operation: OPERATION,
+    it: Iterator,
+) {
+    const ref = changeTree.ref as any;
+    if ((operation & OPERATION.ADD) === OPERATION.ADD && typeof ref['set'] === "function") {
+        encodeMapEntry(encoder, bytes, changeTree, index, operation, it, false, false);
+    } else {
+        encodeIndexedEntry(encoder, bytes, changeTree, index, operation, it, false, false);
+    }
+}
+
 /**
  * Used for collections (MapSchema, ArraySchema, etc.)
  * @private
@@ -171,13 +217,19 @@ export const encodeArray: EncodeOperation = function (
     isEncodeAll: boolean,
     hasView: boolean,
 ) {
-    const ref = changeTree.ref;
-    const useOperationByRefId = hasView && changeTree.isFiltered && (typeof (changeTree.getType(field)) !== "string");
+    // Read through `refTarget` so every property access below skips the
+    // ArraySchema Proxy `get` trap. `refTarget` points at the raw backing
+    // instance; `ref` (the Proxy) stays the user-facing identity.
+    const ref = changeTree.refTarget as any;
+    // ArraySchema stores its per-instance child type at `$childType`.
+    // This encoder is array-only — there's no Schema fallback to consider.
+    const type = ref[$childType];
+    const useOperationByRefId = hasView && changeTree.isFiltered && typeof type !== "string";
 
     let refOrIndex: number;
 
     if (useOperationByRefId) {
-        const item = ref['tmpItems'][field];
+        const item = ref.tmpItems[field];
 
         // Skip encoding if item is undefined (e.g. when clear() is called)
         if (!item) { return; }
@@ -206,20 +258,10 @@ export const encodeArray: EncodeOperation = function (
         return;
     }
 
-    const type = changeTree.getType(field);
-    const value = changeTree.getValue(field, isEncodeAll);
-
-    // console.log({ type, field, value });
-
-    // console.log("encodeArray -> ", {
-    //     ref: changeTree.ref.constructor.name,
-    //     field,
-    //     operation: OPERATION[operation],
-    //     value: value?.toJSON(),
-    //     items: ref.toJSON(),
-    // });
+    // `type` was already read above. Direct $getByIndex call — skips
+    // ChangeTree.getValue's pass-through wrapper.
+    const value = ref[$getByIndex](field, isEncodeAll);
 
-    // TODO: inline this function call small performance gain
     encodeValue(
         encoder,
         bytes,