@colyseus/schema 4.0.3 → 4.0.5

package/package.json

@@ -1,31 +1,12 @@
 {
   "name": "@colyseus/schema",
-  "version": "4.0.3",
+  "version": "4.0.5",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
     "schema-codegen": "bin/schema-codegen",
     "schema-debug": "bin/schema-debug"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
-    "watch": "tsc -p tsconfig.build.json -w",
-    "test": "tsx --tsconfig tsconfig.test.json ./node_modules/.bin/mocha test/*.test.ts test/**/*.test.ts",
-    "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",
-    "generate-test-3": "bin/schema-codegen test-external/ArraySchemaTypes.ts --namespace SchemaTest.ArraySchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ArraySchemaTypes",
-    "generate-test-4": "bin/schema-codegen test-external/MapSchemaTypes.ts --namespace SchemaTest.MapSchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaTypes",
-    "generate-test-5": "bin/schema-codegen test-external/InheritedTypes.ts --namespace SchemaTest.InheritedTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/InheritedTypes",
-    "generate-test-6": "bin/schema-codegen test-external/MapSchemaInt8.ts --namespace SchemaTest.MapSchemaInt8 --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaInt8",
-    "generate-test-7": "bin/schema-codegen test-external/BackwardsForwards.ts --namespace SchemaTest.BackwardsForwards --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/BackwardsForwards",
-    "generate-test-8": "bin/schema-codegen test-external/FilteredTypes.ts --namespace SchemaTest.FilteredTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/FilteredTypes",
-    "generate-test-9": "bin/schema-codegen test-external/InstanceSharingTypes.ts --namespace SchemaTest.InstanceSharingTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/InstanceSharingTypes",
-    "generate-test-10": "bin/schema-codegen test-external/Callbacks.ts --namespace SchemaTest.Callbacks --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/Callbacks",
-    "generate-test-11": "bin/schema-codegen test-external/MapSchemaMoveNullifyType.ts --namespace SchemaTest.MapSchemaMoveNullifyType --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaMoveNullifyType",
-    "generate-test-12": "bin/schema-codegen test-external/ArraySchemaClear --namespace SchemaTest.ArraySchemaClear --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ArraySchemaClear",
-    "prepublishOnly": "npm run build"
-  },
   "files": [
     "src",
     "build",
@@ -93,5 +74,23 @@
       "text"
     ],
     "all": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
+    "watch": "tsc -p tsconfig.build.json -w",
+    "test": "tsx --tsconfig tsconfig.test.json ./node_modules/.bin/mocha test/*.test.ts test/**/*.test.ts",
+    "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",
+    "generate-test-3": "bin/schema-codegen test-external/ArraySchemaTypes.ts --namespace SchemaTest.ArraySchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ArraySchemaTypes",
+    "generate-test-4": "bin/schema-codegen test-external/MapSchemaTypes.ts --namespace SchemaTest.MapSchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaTypes",
+    "generate-test-5": "bin/schema-codegen test-external/InheritedTypes.ts --namespace SchemaTest.InheritedTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/InheritedTypes",
+    "generate-test-6": "bin/schema-codegen test-external/MapSchemaInt8.ts --namespace SchemaTest.MapSchemaInt8 --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaInt8",
+    "generate-test-7": "bin/schema-codegen test-external/BackwardsForwards.ts --namespace SchemaTest.BackwardsForwards --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/BackwardsForwards",
+    "generate-test-8": "bin/schema-codegen test-external/FilteredTypes.ts --namespace SchemaTest.FilteredTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/FilteredTypes",
+    "generate-test-9": "bin/schema-codegen test-external/InstanceSharingTypes.ts --namespace SchemaTest.InstanceSharingTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/InstanceSharingTypes",
+    "generate-test-10": "bin/schema-codegen test-external/Callbacks.ts --namespace SchemaTest.Callbacks --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/Callbacks",
+    "generate-test-11": "bin/schema-codegen test-external/MapSchemaMoveNullifyType.ts --namespace SchemaTest.MapSchemaMoveNullifyType --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaMoveNullifyType",
+    "generate-test-12": "bin/schema-codegen test-external/ArraySchemaClear --namespace SchemaTest.ArraySchemaClear --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ArraySchemaClear"
   }
-}
+}

package/src/Schema.ts

@@ -42,6 +42,16 @@ export class Schema<C = any> implements IRef {
         return typeof((type as typeof Schema)[Symbol.metadata]) === "object";
     }
 
+    /**
+     * Check if a value is an instance of Schema.
+     * This method uses duck-typing to avoid issues with multiple @colyseus/schema versions.
+     * @param obj Value to check
+     * @returns true if the value is a Schema instance
+     */
+    static isSchema(obj: any): obj is Schema {
+        return typeof obj?.assign === "function";
+    }
+
     /**
      * Track property changes
      */

package/src/decoder/strategy/Callbacks.ts

@@ -12,17 +12,17 @@ import { getDecoderStateCallbacks, type SchemaCallbackProxy } from "./getDecoder
 import { getRawChangesCallback } from "./RawChanges.js";
 
 //
-// C#-style Callbacks API
-// Matches the API from: https://docs.colyseus.io/state/callbacks
+// C#-style Callbacks API (https://docs.colyseus.io/state/callbacks)
 //
 // Key features:
 // - Uses string property names with TypeScript auto-completion
-// - Consistent parameter order (key, value) for collection callbacks
+// - Parameter order (value, key) for onAdd/onRemove callbacks
 // - Overloaded methods for nested instance callbacks
 //
 
 type PropertyChangeCallback<K> = (currentValue: K, previousValue: K) => void;
 type KeyValueCallback<K, V> = (key: K, value: V) => void;
+type ValueKeyCallback<V, K> = (value: V, key: K) => void;
 type InstanceChangeCallback = () => void;
 
 // Exclude internal properties from valid property names
@@ -45,32 +45,6 @@ type CollectionKeyType<T, K extends keyof T> =
     T[K] extends ArraySchema<any> ? number :
     T[K] extends Collection<infer Key, any, any> ? Key : never;
 
-/**
- * State Callbacks handler
- *
- * Usage:
- * ```ts
- * const $ = Callbacks.get(decoder);
- *
- * // Listen to property changes
- * $.listen("currentTurn", (currentValue, previousValue) => { ... });
- *
- * // Listen to collection additions
- * $.onAdd("entities", (sessionId, entity) => {
- *     // Nested property listening
- *     $.listen(entity, "hp", (currentHp, previousHp) => { ... });
- * });
- *
- * // Listen to collection removals
- * $.onRemove("entities", (sessionId, entity) => { ... });
- *
- * // Listen to any property change on an instance
- * $.onChange(entity, () => { ... });
- *
- * // Bind properties to another object
- * $.bindTo(player, playerVisual);
- * ```
- */
 export class StateCallbackStrategy<TState extends Schema> {
     protected decoder: Decoder<TState>;
     protected uniqueRefIds: Set<number> = new Set();
@@ -131,7 +105,7 @@ export class StateCallbackStrategy<TState extends Schema> {
 
             if (operation === OPERATION.ADD && immediate) {
                 (collection as Collection<any, any>).forEach((value: any, key: any) => {
-                    handler(key, value);
+                    handler(value, key);
                 });
             }
 
@@ -244,7 +218,7 @@ export class StateCallbackStrategy<TState extends Schema> {
      */
     onAdd<K extends CollectionPropNames<TState>>(
         property: K,
-        handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>,
+        handler: ValueKeyCallback<CollectionValueType<TState, K>, CollectionKeyType<TState, K>>,
         immediate?: boolean
     ): () => void;
 
@@ -254,7 +228,7 @@ export class StateCallbackStrategy<TState extends Schema> {
     onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(
         instance: TInstance,
         property: K,
-        handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>,
+        handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>,
         immediate?: boolean
     ): () => void;
 
@@ -285,7 +259,7 @@ export class StateCallbackStrategy<TState extends Schema> {
      */
     onRemove<K extends CollectionPropNames<TState>>(
         property: K,
-        handler: KeyValueCallback<CollectionKeyType<TState, K>, CollectionValueType<TState, K>>
+        handler: ValueKeyCallback<CollectionValueType<TState, K>, CollectionKeyType<TState, K>>
     ): () => void;
 
     /**
@@ -294,7 +268,7 @@ export class StateCallbackStrategy<TState extends Schema> {
     onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(
         instance: TInstance,
         property: K,
-        handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>
+        handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>
     ): () => void;
 
     onRemove(...args: any[]): () => void {
@@ -370,7 +344,7 @@ export class StateCallbackStrategy<TState extends Schema> {
             //
             if (
                 (change.op & OPERATION.DELETE) === OPERATION.DELETE &&
-                change.previousValue instanceof Schema
+                Schema.isSchema(change.previousValue)
             ) {
                 const childRefId = (change.previousValue as Ref)[$refId];
                 const deleteCallbacks = this.callbacks[childRefId]?.[OPERATION.DELETE];
@@ -381,7 +355,7 @@ export class StateCallbackStrategy<TState extends Schema> {
                 }
             }
 
-            if (ref instanceof Schema) {
+            if (Schema.isSchema(ref)) {
                 //
                 // Handle Schema instance
                 //
@@ -426,11 +400,11 @@ export class StateCallbackStrategy<TState extends Schema> {
                     // FIXME: `previousValue` should always be available.
                     //
                     if (change.previousValue !== undefined) {
-                        // trigger onRemove (key, value)
+                        // trigger onRemove (value, key)
                         const deleteCallbacks = $callbacks[OPERATION.DELETE];
                         if (deleteCallbacks) {
                             for (let j = deleteCallbacks.length - 1; j >= 0; j--) {
-                                deleteCallbacks[j](dynamicIndex, change.previousValue);
+                                deleteCallbacks[j](change.previousValue, dynamicIndex);
                             }
                         }
                     }
@@ -441,7 +415,7 @@ export class StateCallbackStrategy<TState extends Schema> {
                         if (addCallbacks) {
                             this.isTriggering = true;
                             for (let j = addCallbacks.length - 1; j >= 0; j--) {
-                                addCallbacks[j](dynamicIndex, change.value);
+                                addCallbacks[j](change.value, dynamicIndex);
                             }
                             this.isTriggering = false;
                         }
@@ -451,12 +425,12 @@ export class StateCallbackStrategy<TState extends Schema> {
                     (change.op & OPERATION.ADD) === OPERATION.ADD &&
                     change.previousValue !== change.value
                 ) {
-                    // trigger onAdd (key, value)
+                    // trigger onAdd (value, key)
                     const addCallbacks = $callbacks[OPERATION.ADD];
                     if (addCallbacks) {
                         this.isTriggering = true;
                         for (let j = addCallbacks.length - 1; j >= 0; j--) {
-                            addCallbacks[j](dynamicIndex, change.value);
+                            addCallbacks[j](change.value, dynamicIndex);
                         }
                         this.isTriggering = false;
                     }
@@ -493,13 +467,13 @@ export const Callbacks = {
      * callbacks.listen("currentTurn", (currentValue, previousValue) => { ... });
      *
      * // Listen to collection additions
-     * callbacks.onAdd("entities", (sessionId, entity) => {
+     * callbacks.onAdd("entities", (entity, sessionId) => {
      *     // Nested property listening
      *     callbacks.listen(entity, "hp", (currentHp, previousHp) => { ... });
      * });
      *
      * // Listen to collection removals
-     * callbacks.onRemove("entities", (sessionId, entity) => { ... });
+     * callbacks.onRemove("entities", (entity, sessionId) => { ... });
      *
      * // Listen to any property change on an instance
      * callbacks.onChange(entity, () => { ... });

package/src/decoder/strategy/getDecoderStateCallbacks.ts

@@ -137,7 +137,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
             //
             if (
                 (change.op & OPERATION.DELETE) === OPERATION.DELETE &&
-                change.previousValue instanceof Schema
+                Schema.isSchema(change.previousValue)
             ) {
                 const deleteCallbacks = callbacks[(change.previousValue as Ref)[$refId]]?.[OPERATION.DELETE];
                 for (let i = deleteCallbacks?.length - 1; i >= 0; i--) {
@@ -145,7 +145,7 @@ export function getDecoderStateCallbacks<T extends Schema>(decoder: Decoder<T>):
                 }
             }
 
-            if (ref instanceof Schema) {
+            if (Schema.isSchema(ref)) {
                 //
                 // Handle schema instance
                 //