@colyseus/schema 5.0.19 → 5.0.21

package/README.md

@@ -2,17 +2,18 @@
   <img src="logo.png?raw=true" width="50%" />
   <br>
   <p>
-    An incremental binary state serializer with delta encoding for games.<br>
+    <b>Automatic state replication for multiplayer games.</b><br>
     Made for <a href="https://github.com/colyseus/colyseus">Colyseus</a>, yet can be used standalone.
   </p>
 </div>
 
 # Features
 
-- **Incremental State Synchronization**: Send only the properties that have changed.
+- **Plain Objects, Synced**: Assign a property, `push` to an array, or `set` on a map. Change tracking, encoding and decoding happen for you.
+- **Delta Encoding**: Only the properties that changed are sent, in a compact binary format.
 - **Trigger Callbacks at Decoding**: [Bring your own](https://docs.colyseus.io/state/callbacks/custom) callback system at decoding, or use the built-in one.
 - **Instance Reference Tracking**: Share references of the same instance across the state.
-- **State Views**: Filter properties that should be sent only to specific clients.
+- **State Views**: Per-client visibility. Decide which properties and instances each client receives.
 - **Reflection**: Encode/Decode schema definitions.
 - **Schema Generation**: Generate client-side schema files for strictly typed languages.
 - **Type Safety**: Strictly typed schema definitions.

package/build/Reflection.d.ts

@@ -76,7 +76,7 @@ export declare const ReflectionField: import("./annotations.js").SchemaWithExten
         max: number;
         bits: number;
         mode: number;
-    } & {} & Schema<any> & Schema<unknown>, false, true>;
+    } & {} & Schema<any> & Schema<unknown>, true, true>;
 }, import("./index.js").BuilderInitProps<{
     name: FieldBuilder<string, false, false>;
     type: FieldBuilder<string, false, false>;
@@ -91,7 +91,7 @@ export declare const ReflectionField: import("./annotations.js").SchemaWithExten
         max: number;
         bits: number;
         mode: number;
-    } & {} & Schema<any> & Schema<unknown>, false, true>;
+    } & {} & Schema<any> & Schema<unknown>, true, true>;
 }>, typeof Schema>;
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 export declare const ReflectionType: import("./annotations.js").SchemaWithExtendsConstructor<{

package/build/annotations.d.ts

@@ -139,8 +139,9 @@ type HasExplicitInit<T> = T extends {
  * (shorthand for `t.ref(Class)`), or a method (attached to the prototype).
  */
 export type FieldsAndMethods = Record<string, FieldBuilder<any, boolean, boolean> | (new (...args: any[]) => Schema) | Function>;
+type SchemaInstance<T, P extends typeof Schema> = InferSchemaInstanceType<T> & InstanceType<P>;
 export interface SchemaWithExtends<T, P extends typeof Schema> {
-    extend: <T2 extends FieldsAndMethods = FieldsAndMethods>(fields: T2 & ThisType<InferSchemaInstanceType<T & T2>>, name?: string) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
+    extend: <T2 extends FieldsAndMethods = FieldsAndMethods>(fields: T2 & ThisType<SchemaInstance<T & T2, P>>, name?: string) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
 }
 /**
  * Get the type of the schema defined via `schema('Name', {...})` method.
@@ -156,17 +157,18 @@ export type SchemaType<T extends {
     '~type': any;
 }> = T['~type'];
 export interface SchemaWithExtendsConstructor<T, InitProps, P extends typeof Schema> extends SchemaWithExtends<T, P> {
-    '~type': InferSchemaInstanceType<T>;
+    '~type': SchemaInstance<T, P>;
     new (...args: [
         InitProps
-    ] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : HasExplicitInit<T> extends true ? [InitProps] : IsInitPropsRequired<T> extends true ? ([] | [InitProps]) : [InitProps?]): InferSchemaInstanceType<T> & InstanceType<P>;
-    prototype: InferSchemaInstanceType<T> & InstanceType<P> & {
-        initialize(...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : [InitProps]): void;
-    };
+    ] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : HasExplicitInit<T> extends true ? [InitProps] : IsInitPropsRequired<T> extends true ? ([] | [InitProps]) : [InitProps?]): SchemaInstance<T, P>;
+    prototype: SchemaInstance<T, P>;
 }
 /**
  * Define a Schema class declaratively.
  *
+ * `initialize()` acts as the constructor: a class created with `.extend()`
+ * inherits the parent's unless it defines its own.
+ *
  * @example
  * import { schema, t } from '@colyseus/schema';
  *
@@ -180,5 +182,5 @@ export interface SchemaWithExtendsConstructor<T, InitProps, P extends typeof Sch
  *   weapon: t.string(),
  * }, 'Warrior');
  */
-export declare function schema<T extends FieldsAndMethods, P extends typeof Schema = typeof Schema>(fieldsAndMethods: T & ThisType<InferSchemaInstanceType<T>>, name?: string, inherits?: P): SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
+export declare function schema<T extends FieldsAndMethods, P extends typeof Schema = typeof Schema>(fieldsAndMethods: T & ThisType<SchemaInstance<T, P>>, name?: string, inherits?: P): SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
 export {};

package/build/decoder/strategy/Callbacks.d.ts

@@ -1,10 +1,9 @@
-import { Collection, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import type { IRef, Ref } from "../../encoder/ChangeTree.js";
 import { Decoder } from "../Decoder.js";
 import { DataChange } from "../DecodeOperation.js";
 import { OPERATION } from "../../encoding/spec.js";
 import { Schema } from "../../Schema.js";
-import { $refId } from "../../types/symbols.js";
 import { MapSchema } from "../../types/custom/MapSchema.js";
 import { ArraySchema } from "../../types/custom/ArraySchema.js";
 import { type SchemaCallbackProxy } from "./getDecoderStateCallbacks.js";
@@ -12,12 +11,12 @@ 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;
-type PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;
-type CollectionPropNames<T> = Exclude<{
-    [K in keyof T]: T[K] extends Collection<any, any> ? K : never;
-}[keyof T] & string, typeof $refId>;
-type CollectionValueType<T, K extends keyof T> = T[K] extends MapSchema<infer V, any> ? V : T[K] extends ArraySchema<infer V> ? V : T[K] extends Collection<any, infer V, any> ? V : never;
-type CollectionKeyType<T, K extends keyof T> = T[K] extends MapSchema<any, infer Key> ? Key : T[K] extends ArraySchema<any> ? number : T[K] extends Collection<infer Key, any, any> ? Key : never;
+type PublicPropNames<T> = NonFunctionPropNames<T> & string;
+type CollectionPropNames<T> = {
+    [K in keyof T]: T[K] extends CollectionLike<any, any> ? K : never;
+}[keyof T] & string;
+type CollectionValueType<T, K extends keyof T> = T[K] extends MapSchema<infer V, any> ? V : T[K] extends ArraySchema<infer V> ? V : T[K] extends CollectionLike<any, infer V, any> ? V : never;
+type CollectionKeyType<T, K extends keyof T> = T[K] extends MapSchema<any, infer Key> ? Key : T[K] extends ArraySchema<any> ? number : T[K] extends CollectionLike<infer Key, any, any> ? Key : never;
 export declare class StateCallbackStrategy<TState extends IRef> {
     protected decoder: Decoder<TState>;
     protected uniqueRefIds: Set<number>;

package/build/decoder/strategy/getDecoderStateCallbacks.d.ts

@@ -1,4 +1,4 @@
-import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { NonFunctionNonPrimitivePropNames, NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import { Decoder } from "../Decoder.js";
 import { Schema } from "../../Schema.js";
 /**
@@ -10,7 +10,7 @@ import { Schema } from "../../Schema.js";
  */
 export type SchemaCallbackProxy<RoomState> = (<T>(instance: T) => CallbackProxy<T>);
 export type GetCallbackProxy = SchemaCallbackProxy<any>;
-export type CallbackProxy<T> = unknown extends T ? SchemaCallback<T> & CollectionCallback<any, any> : T extends Collection<infer K, infer V, infer _> ? CollectionCallback<K, V> : SchemaCallback<T>;
+export type CallbackProxy<T> = unknown extends T ? SchemaCallback<T> & CollectionCallback<any, any> : T extends CollectionLike<infer K, infer V, infer _> ? CollectionCallback<K, V> : SchemaCallback<T>;
 export type SchemaCallback<T> = {
     /**
      * Trigger callback when value of a property changes.

package/build/index.cjs

@@ -1411,6 +1411,10 @@ const Metadata = {
             });
         }
         for (const field in fields) {
+            // metadata inherits the parent's, so this also catches a redeclared parent field
+            if (metadata[field] !== undefined) {
+                throw new Error(`@colyseus/schema: Duplicate '${field}' definition on '${constructor.name || "(anonymous)"}'.`);
+            }
             Metadata.defineField(constructor, metadata, fieldIndex, field, fields[field]);
             fieldIndex++;
         }
@@ -7275,6 +7279,9 @@ function makeAutoDefaultFactory(rawType) {
 /**
  * Define a Schema class declaratively.
  *
+ * `initialize()` acts as the constructor: a class created with `.extend()`
+ * inherits the parent's unless it defines its own.
+ *
  * @example
  * import { schema, t } from '@colyseus/schema';
  *
@@ -7435,8 +7442,11 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
         return parentProps;
     };
     const hasInitialize = typeof methods.initialize === "function";
-    /** @codegen-ignore */
-    const klass = Metadata.setFields(class extends inherits {
+    // Like a constructor: the most-derived initialize() runs once, own or
+    // inherited from a schema() parent. A custom base's initialize() is not
+    // picked up — the constructor type only sees the fields map.
+    const initialize = methods.initialize ?? inherits._initialize;
+    const klass = class extends inherits {
         constructor(...args) {
             const props = args[0];
             if (props === undefined) {
@@ -7451,13 +7461,20 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
                 // `initialize()` owns the schema fields, so only parent props flow up.
                 super(Object.assign(getDefaultValues(), hasInitialize ? getParentProps(props) : props));
             }
-            // Only call initialize() on the exact target class, not parents.
-            if (hasInitialize && new.target === klass) {
-                methods.initialize.apply(this, args);
+            // Only on the exact target class — parents' constructors skip it.
+            if (initialize && new.target === klass) {
+                initialize.apply(this, args);
             }
         }
-    }, fields);
+    };
+    // named before setFields so a duplicate-field error can say which class
+    if (name) {
+        Object.defineProperty(klass, "name", { value: name });
+    }
+    /** @codegen-ignore */
+    Metadata.setFields(klass, fields);
     klass._getDefaultValues = getDefaultValues;
+    klass._initialize = initialize;
     Object.assign(klass.prototype, methods);
     for (const fieldName in viewTagFields) {
         view(viewTagFields[fieldName])(klass.prototype, fieldName);
@@ -7489,9 +7506,6 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             metadata[metadata[fieldName]].optional = true;
         }
     }
-    if (name) {
-        Object.defineProperty(klass, "name", { value: name });
-    }
     klass.extend = (childFields, childName) => schema(childFields, childName, klass);
     return klass;
 }