@colyseus/schema 4.0.20 → 5.0.0

package/build/types/symbols.d.ts

@@ -1,4 +1,4 @@
-export declare const $refId = "~refId";
+export declare const $refId: unique symbol;
 export declare const $track = "~track";
 export declare const $encoder = "~encoder";
 export declare const $decoder = "~decoder";
@@ -6,14 +6,24 @@ export declare const $filter = "~filter";
 export declare const $getByIndex = "~getByIndex";
 export declare const $deleteByIndex = "~deleteByIndex";
 /**
- * Used to hold ChangeTree instances whitin the structures
+ * Used to hold ChangeTree instances whitin the structures.
+ *
+ * Real JS Symbol — see the `$values` comment for rationale.
  */
-export declare const $changes = "~changes";
+export declare const $changes: unique symbol;
 /**
  * Used to keep track of the type of the child elements of a collection
- * (MapSchema, ArraySchema, etc.)
+ * (MapSchema, ArraySchema, etc.). Real Symbol — same rationale as $values.
  */
-export declare const $childType = "~childType";
+export declare const $childType: unique symbol;
+/**
+ * Self-reference an instance sets on `this` so its own methods can recover
+ * the underlying object even when `this` is a Proxy wrapper. Used by
+ * ArraySchema (whose public API is a Proxy) to grab the underlying instance
+ * once at the top of hot methods and then access fields directly without
+ * paying the Proxy.get cost on every read.
+ */
+export declare const $proxyTarget: unique symbol;
 /**
  * Optional "discard" method for custom types (ArraySchema)
  * (Discards changes for next serialization)
@@ -23,11 +33,44 @@ export declare const $onEncodeEnd = "~onEncodeEnd";
  * When decoding, this method is called after the instance is fully decoded
  */
 export declare const $onDecodeEnd = "~onDecodeEnd";
+/**
+ * Per-instance dense array holding field values by index.
+ * Replaces per-field _fieldName shadow properties.
+ *
+ * Real JS Symbol (not "~"-prefixed string) so plain assignment is safe —
+ * symbols are non-enumerable to Object.keys / JSON.stringify / for-in,
+ * which means we can drop Object.defineProperty(...{ enumerable: false })
+ * and avoid the slow-path / dictionary-mode hazards that come with it.
+ */
+export declare const $values: unique symbol;
+/**
+ * Brand for FieldBuilder instances so schema() can detect them.
+ */
+export declare const $builder = "~builder";
 /**
  * Metadata
  */
 export declare const $descriptors = "~descriptors";
+/**
+ * Per-class bitmask: bit i set iff field i carries a @view tag.
+ * Lazily computed from $viewFieldIndexes on first encode pass.
+ * Skips the per-field metadata[i].tag property chase in the hot encode loop.
+ */
+export declare const $filterBitmask = "~__filterBitmask";
+/**
+ * Cached per-class encode descriptor: bundles encoder fn, filter fn,
+ * metadata, isSchema flag, and filterBitmask into one object stashed on
+ * the constructor. Replaces 5 separate per-tree property chases /
+ * function calls in the encode loop with a single property load.
+ */
+export declare const $encodeDescriptor = "~__encodeDescriptor";
+export declare const $encoders = "~encoders";
 export declare const $numFields = "~__numFields";
 export declare const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
 export declare const $viewFieldIndexes = "~__viewFieldIndexes";
 export declare const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
+export declare const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
+export declare const $transientFieldIndexes = "~__transientFieldIndexes";
+export declare const $staticFieldIndexes = "~__staticFieldIndexes";
+export declare const $streamFieldIndexes = "~__streamFieldIndexes";
+export declare const $streamPriorities = "~__streamPriorities";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "4.0.20",
+  "version": "5.0.0",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -10,8 +10,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
     "watch": "tsc -p tsconfig.build.json -w",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "test": "tsx --tsconfig tsconfig.test.json ./node_modules/.bin/mocha test/*.test.ts test/**/*.test.ts",
-    "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",
     "generate-test-1": "bin/schema-codegen test-external/PrimitiveTypes.ts --namespace SchemaTest.PrimitiveTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/PrimitiveTypes",
     "generate-test-2": "bin/schema-codegen test-external/ChildSchemaTypes.ts --namespace SchemaTest.ChildSchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ChildSchemaTypes",
@@ -42,6 +42,12 @@
       "import": "./build/index.mjs",
       "require": "./build/index.cjs",
       "types": "./build/index.d.ts"
+    },
+    "./input": {
+      "browser": "./build/input/index.mjs",
+      "import": "./build/input/index.mjs",
+      "require": "./build/input/index.cjs",
+      "types": "./build/input/index.d.ts"
     }
   },
   "repository": {
@@ -82,7 +88,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0 || ^6.0.0"
+    "typescript": "^5.9.3"
   },
   "c8": {
     "include": [

package/src/Metadata.ts

@@ -1,7 +1,9 @@
 import { DefinitionType, getPropertyDescriptor } from "./annotations.js";
 import { Schema } from "./Schema.js";
-import { getType, registeredTypes } from "./types/registry.js";
-import { $decoder, $descriptors, $encoder, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $track, $viewFieldIndexes } from "./types/symbols.js";
+import { getType, registeredTypes, TypeDefinition } from "./types/registry.js";
+import { $decoder, $descriptors, $encoder, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $staticFieldIndexes, $streamFieldIndexes, $streamPriorities, $track, $transientFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { ARRAY_STREAM_NOT_SUPPORTED } from "./encoder/streaming.js";
+import { encode } from "./encoding/encode.js";
 import { TypeContext } from "./types/TypeContext.js";
 
 export type MetadataField = {
@@ -10,7 +12,11 @@ export type MetadataField = {
     index: number,
     tag?: number,
     unreliable?: boolean,
+    transient?: boolean,
     deprecated?: boolean,
+    owned?: boolean,
+    static?: boolean,
+    stream?: boolean,
 };
 
 export type Metadata =
@@ -18,10 +24,31 @@ export type Metadata =
     { [$viewFieldIndexes]: number[]; } & // all field indexes with "view" tag
     { [$fieldIndexesByViewTag]: {[tag: number]: number[]}; } & // field indexes by "view" tag
     { [$refTypeFieldIndexes]: number[]; } & // all field indexes containing Ref types (Schema, ArraySchema, MapSchema, etc)
+    { [$unreliableFieldIndexes]: number[]; } & // all field indexes tagged with @unreliable
+    { [$transientFieldIndexes]: number[]; } & // all field indexes tagged with @transient (not persisted to snapshots)
+    { [$staticFieldIndexes]: number[]; } & // all field indexes tagged with @static (not tracked after assignment)
+    { [$streamFieldIndexes]: number[]; } & // all field indexes holding a t.stream(...) collection
+    { [$streamPriorities]: { [field: number]: (view: any, element: any) => number }; } & // per-stream-field priority callback declared at schema definition time
+    { [$encoders]: Array<(bytes: Uint8Array, value: any, it: any) => void>; } & // pre-computed encoder fn per primitive field
     { [field: number]: MetadataField; } & // index => field name
     { [field: string]: number; } & // field name => field metadata
     { [$descriptors]: { [field: string]: PropertyDescriptor } }  // property descriptors
 
+/**
+ * Given a normalized field type (`"number"`, `{ map: Foo }`, `Player`,
+ * etc.), split into the collection-type descriptor (`{ constructor:
+ * MapSchema, ... }`) if applicable and the inner child type. Shared by
+ * `@type()` decoration and `Metadata.setFields` — both need to build a
+ * property accessor that knows whether the slot holds a collection.
+ */
+export function resolveFieldType(type: any): { complexTypeKlass: TypeDefinition | false, childType: any } {
+    const complexTypeKlass = typeof (Object.keys(type)[0]) === "string" && getType(Object.keys(type)[0]);
+    return {
+        complexTypeKlass,
+        childType: complexTypeKlass ? Object.values(type)[0] : type,
+    };
+}
+
 export function getNormalizedType(type: any): DefinitionType  {
     if (Array.isArray(type)) {
         return { array: getNormalizedType(type[0]) };
@@ -91,16 +118,11 @@ export const Metadata = {
         });
 
         if (descriptor) {
-            // for encoder
+            // Accessor descriptor for the public field name.
+            // Installed on the prototype at class-definition time.
             metadata[$descriptors][name] = descriptor;
-            metadata[$descriptors][`_${name}`] = {
-                value: undefined,
-                writable: true,
-                enumerable: false,
-                configurable: true,
-            };
         } else {
-            // for decoder
+            // For decoder: simple writable slot, also on prototype.
             metadata[$descriptors][name] = {
                 value: undefined,
                 writable: true,
@@ -134,6 +156,38 @@ export const Metadata = {
             }
             metadata[$refTypeFieldIndexes].push(index);
         }
+
+        // `{ stream: ... }` collections are always view-scoped (priority-
+        // batched emit). Auto-flag here so both `@type({stream: ...})` and
+        // the `t.stream(...)` builder route into the same filter / encoder
+        // dispatch without the caller needing an extra setStream() call.
+        const t = metadata[index].type;
+        if (t && typeof t === "object" && (t as any)["stream"] !== undefined) {
+            // Reject the combined shorthand `@type({ array: X, stream:
+            // true })` at decoration time — same diagnostic as the
+            // builder chainable throws for `t.array(X).stream()`.
+            if ((t as any).array !== undefined) {
+                throw new Error(ARRAY_STREAM_NOT_SUPPORTED);
+            }
+            metadata[index].stream = true;
+            if (!metadata[$streamFieldIndexes]) {
+                Object.defineProperty(metadata, $streamFieldIndexes, {
+                    value: [],
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            if (!metadata[$streamFieldIndexes].includes(index)) {
+                metadata[$streamFieldIndexes].push(index);
+            }
+            // Pick up the declaration-scope priority callback if present in
+            // the `@type({ stream: X, priority: fn })` shorthand.
+            const priorityFn = (type as any)?.priority;
+            if (typeof priorityFn === "function") {
+                Metadata.setStreamPriority(metadata as any, name, priorityFn);
+            }
+        }
     },
 
     setTag(metadata: Metadata, fieldName: string, tag: number) {
@@ -168,6 +222,112 @@ export const Metadata = {
         metadata[$fieldIndexesByViewTag][tag].push(index);
     },
 
+    setUnreliable(metadata: Metadata, fieldName: string) {
+        const index = metadata[fieldName];
+        const fieldType = metadata[index].type;
+        // `@unreliable` is only valid on primitive fields. Ref-type fields
+        // (Schema sub-classes, MapSchema, ArraySchema, SetSchema,
+        // CollectionSchema) carry refIds whose ADD/DELETE must arrive
+        // on the reliable channel — otherwise a dropped unreliable packet
+        // would leave the decoder unable to interpret subsequent packets
+        // referencing the orphan refId. Primitive types are encoded as
+        // strings ("number", "string", "int32", ...); anything else is a
+        // ref. Reject at decoration time so the bug surfaces in dev, not
+        // under packet loss in prod.
+        if (typeof fieldType !== "string") {
+            throw new Error(
+                `@unreliable cannot be applied to ref-type field "${fieldName}". ` +
+                `For ref-type fields, mark each primitive sub-field with @unreliable instead. ` +
+                `See README "Limitations and best practices".`
+            );
+        }
+        metadata[index].unreliable = true;
+
+        if (!metadata[$unreliableFieldIndexes]) {
+            Object.defineProperty(metadata, $unreliableFieldIndexes, {
+                value: [],
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        metadata[$unreliableFieldIndexes].push(index);
+    },
+
+    setTransient(metadata: Metadata, fieldName: string) {
+        const index = metadata[fieldName];
+        metadata[index].transient = true;
+
+        if (!metadata[$transientFieldIndexes]) {
+            Object.defineProperty(metadata, $transientFieldIndexes, {
+                value: [],
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        metadata[$transientFieldIndexes].push(index);
+    },
+
+    setStatic(metadata: Metadata, fieldName: string) {
+        const index = metadata[fieldName];
+        metadata[index].static = true;
+
+        if (!metadata[$staticFieldIndexes]) {
+            Object.defineProperty(metadata, $staticFieldIndexes, {
+                value: [],
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        metadata[$staticFieldIndexes].push(index);
+    },
+
+    setStream(metadata: Metadata, fieldName: string) {
+        const index = metadata[fieldName];
+        metadata[index].stream = true;
+
+        if (!metadata[$streamFieldIndexes]) {
+            Object.defineProperty(metadata, $streamFieldIndexes, {
+                value: [],
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        metadata[$streamFieldIndexes].push(index);
+    },
+
+    /**
+     * Attach a declaration-scope priority callback to a stream field.
+     * Called at schema definition time (via `t.stream(X).priority(fn)` or
+     * `@type({ stream: X, priority: fn })`), looked up at stream-attach
+     * time to seed the instance's `_stream.priority` slot. The callback
+     * signature is `(view: StateView, element: V) => number` — only fires
+     * during `encodeView`, broadcast mode emits FIFO regardless.
+     */
+    setStreamPriority(
+        metadata: Metadata,
+        fieldName: string,
+        fn: (view: any, element: any) => number,
+    ) {
+        const index = metadata[fieldName];
+        if (!metadata[$streamPriorities]) {
+            Object.defineProperty(metadata, $streamPriorities, {
+                value: {},
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        metadata[$streamPriorities][index] = fn;
+    },
+
+    getStreamPriority(metadata: Metadata | undefined, index: number) {
+        return metadata?.[$streamPriorities]?.[index];
+    },
+
     setFields<T extends { new (...args: any[]): InstanceType<T> } = any>(target: T, fields: { [field in keyof InstanceType<T>]?: DefinitionType }) {
         // for inheritance support
         const constructor = target.prototype.constructor;
@@ -192,24 +352,39 @@ export const Metadata = {
 
         fieldIndex++;
 
+        // Pre-computed encoder function table: metadata[$encoders][fieldIndex] = encode.uint8 etc.
+        if (!metadata[$encoders]) {
+            Object.defineProperty(metadata, $encoders, {
+                value: parentMetadata?.[$encoders] ? [...parentMetadata[$encoders]] : [],
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+
         for (const field in fields) {
             const type = getNormalizedType(fields[field]);
 
-            // FIXME: this code is duplicated from @type() annotation
-            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)
             );
 
+            // Install accessor descriptor on the prototype (once per class field).
+            if (metadata[$descriptors][field]) {
+                Object.defineProperty(target.prototype, field, metadata[$descriptors][field]);
+            }
+
+            // Pre-compute encoder function for primitive types.
+            if (typeof type === "string") {
+                metadata[$encoders][fieldIndex] = (encode as any)[type];
+            }
+
             fieldIndex++;
         }
 
@@ -220,20 +395,6 @@ export const Metadata = {
         return metadata[field].deprecated === true;
     },
 
-    init(klass: any) {
-        //
-        // Used only to initialize an empty Schema (Encoder#constructor)
-        // TODO: remove/refactor this...
-        //
-        const metadata = {};
-        klass[Symbol.metadata] = metadata;
-        Object.defineProperty(metadata, $numFields, {
-            value: 0,
-            enumerable: false,
-            configurable: true,
-        });
-    },
-
     initialize(constructor: any) {
         const parentClass = Object.getPrototypeOf(constructor);
         const parentMetadata: Metadata = parentClass[Symbol.metadata];
@@ -284,6 +445,46 @@ export const Metadata = {
                     });
                 }
 
+                // $unreliableFieldIndexes
+                if (parentMetadata[$unreliableFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $unreliableFieldIndexes, {
+                        value: [...parentMetadata[$unreliableFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
+                // $transientFieldIndexes
+                if (parentMetadata[$transientFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $transientFieldIndexes, {
+                        value: [...parentMetadata[$transientFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
+                // $staticFieldIndexes
+                if (parentMetadata[$staticFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $staticFieldIndexes, {
+                        value: [...parentMetadata[$staticFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
+                // $streamFieldIndexes
+                if (parentMetadata[$streamFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $streamFieldIndexes, {
+                        value: [...parentMetadata[$streamFieldIndexes]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
+
                 // $descriptors
                 Object.defineProperty(metadata, $descriptors, {
                     value: { ...parentMetadata[$descriptors] },
@@ -291,6 +492,16 @@ export const Metadata = {
                     configurable: true,
                     writable: true,
                 });
+
+                // $encoders
+                if (parentMetadata[$encoders] !== undefined) {
+                    Object.defineProperty(metadata, $encoders, {
+                        value: [...parentMetadata[$encoders]],
+                        enumerable: false,
+                        configurable: true,
+                        writable: true,
+                    });
+                }
             }
         }
 
@@ -321,5 +532,21 @@ export const Metadata = {
 
     hasViewTagAtIndex(metadata: Metadata, index: number) {
         return metadata?.[$viewFieldIndexes]?.includes(index);
+    },
+
+    hasUnreliableAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$unreliableFieldIndexes]?.includes(index);
+    },
+
+    hasTransientAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$transientFieldIndexes]?.includes(index);
+    },
+
+    hasStaticAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$staticFieldIndexes]?.includes(index);
+    },
+
+    hasStreamAtIndex(metadata: Metadata, index: number) {
+        return metadata?.[$streamFieldIndexes]?.includes(index);
     }
 }

package/src/Reflection.ts

@@ -5,6 +5,8 @@ import { Iterator } from "./encoding/decode.js";
 import { Encoder } from "./encoder/Encoder.js";
 import { Decoder } from "./decoder/Decoder.js";
 import { Schema } from "./Schema.js";
+import { t, FieldBuilder } from "./types/builder.js";
+import { ArraySchema } from "./types/custom/ArraySchema.js";
 
 /**
  * Static methods available on Reflection
@@ -33,25 +35,25 @@ interface ReflectionStatic {
  * Reflection
  */
 export const ReflectionField = schema({
-    name: "string",
-    type: "string",
-    referencedType: "number",
-})
+    name: t.string(),
+    type: t.string(),
+    referencedType: t.number(),
+}, "ReflectionField");
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 
 export const ReflectionType = schema({
-    id: "number",
-    extendsId: "number",
-    fields: [ ReflectionField ],
-})
+    id: t.number(),
+    extendsId: t.number(),
+    fields: t.array(ReflectionField),
+}, "ReflectionType");
 export type ReflectionType = SchemaType<typeof ReflectionType>;
 
 export const Reflection = schema({
-    types: [ ReflectionType ],
-    rootType: "number",
-}) as ReturnType<typeof schema<{
-    types: [typeof ReflectionType];
-    rootType: "number";
+    types: t.array(ReflectionType),
+    rootType: t.number(),
+}, "Reflection") as ReturnType<typeof schema<{
+    types: FieldBuilder<ArraySchema<ReflectionType>>;
+    rootType: FieldBuilder<number>;
 }>> & ReflectionStatic;
 
 export type Reflection = SchemaType<typeof Reflection>;