@colyseus/schema 5.0.19 → 5.0.21

package/build/types/HelperTypes.d.ts

@@ -9,10 +9,17 @@ import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { FieldBuilder } from "./builder.js";
 export type Constructor<T = {}> = new (...args: any[]) => T;
 type PrimitiveStringToType<T> = T extends "string" ? string : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number : T extends "boolean" ? boolean : T;
-export interface Collection<K = any, V = any, IT = V> {
+/**
+ * What the decoder callbacks accept as "a collection": the public shape, which
+ * a plain array satisfies too — `@type([X]) items: X[]` is a common way to
+ * declare a field. {@link Collection} is the runtime contract on top of it.
+ */
+export interface CollectionLike<K = any, V = any, IT = V> {
     [Symbol.iterator](): IterableIterator<IT>;
     forEach(callback: Function): void;
     entries(): IterableIterator<[K, V]>;
+}
+export interface Collection<K = any, V = any, IT = V> extends CollectionLike<K, V, IT> {
     /** See {@link $resyncPrune} — every collection kind must declare its resync-sweep semantics. */
     [$resyncPrune](visited: Set<number | string>, prune: (value: V, identity: number | string) => void, keep: (value: V) => void): void;
 }
@@ -69,35 +76,39 @@ export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends
 } ? StreamSchema<InstanceType<ChildType>> : T extends {
     stream: infer ChildType;
 } ? StreamSchema<ChildType> : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
+type IsOptionalBuilderKey<T, K extends keyof T> = T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? O : false;
 type OptionalBuilderKeys<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? (O extends true ? K : never) : never;
+    [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? K : never;
+}[keyof T];
+type RequiredBuilderKeys<T> = {
+    [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? never : K;
 }[keyof T];
-type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
 export type InferSchemaInstanceType<T> = {
     [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
 } & {
     [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V> ? V : never;
 } & Schema;
-export type NonFunctionProps<T> = Omit<T, {
-    [K in keyof T]: T[K] extends Function ? K : never;
-}[keyof T]>;
+type DataKey<T, K extends keyof T> = K extends keyof Schema ? never : T[K] extends Function ? never : K;
 export type NonFunctionPropNames<T> = {
-    [K in keyof T]: T[K] extends Function ? never : K;
+    [K in keyof T]-?: DataKey<T, K>;
 }[keyof T];
 export type NonFunctionNonPrimitivePropNames<T> = {
-    [K in keyof T]: T[K] extends Function ? never : T[K] extends number | string | boolean ? never : K;
+    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : T[K] extends number | string | boolean ? never : K;
 }[keyof T];
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
 type ToJSONField<X> = X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : X extends ArraySchema<infer U> ? ToJSONValue<U>[] : X extends SetSchema<infer U> ? ToJSONValue<U>[] : X extends CollectionSchema<infer U> ? ToJSONValue<U>[] : X extends Schema ? ToJSON<X> : X;
+type IsOptionalKey<T, K extends keyof T> = undefined extends {} ? ({} extends Pick<T, K> ? true : false) : (undefined extends T[K] ? true : false);
+type ToJSONRequiredKeys<T> = {
+    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? never : K;
+}[keyof T];
 type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends {} ? ({} extends Pick<T, K> ? K : never) : (undefined extends T[K] ? K : never);
+    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? K : never;
 }[keyof T];
-type ToJSONRequiredKeys<T> = Exclude<keyof T, ToJSONOptionalKeys<T>>;
-export type ToJSON<T> = NonFunctionProps<{
+export type ToJSON<T> = {
     [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
 } & {
     [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
-}>;
+};
 /**
  * The plain DATA shape of a Schema instance type `T`: its synchronized fields
  * with all `Schema` machinery stripped (`assign`, `clone`, `toJSON`, the
@@ -116,8 +127,7 @@ export type ToJSON<T> = NonFunctionProps<{
  *
  * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
  * structural projection: nested Schema / collection fields keep their instance
- * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
- * `NonFunctionProps` pass leaves behind.
+ * types.
  */
 export type Data<T> = Omit<T, keyof Schema>;
 export type IsNever<T> = [T] extends [never] ? true : false;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.19",
-  "description": "Binary state serializer with delta encoding for games",
+  "version": "5.0.21",
+  "description": "Automatic state replication for multiplayer games. Mutate plain objects, and every client gets a live, typed mirror through delta encoding.",
   "type": "module",
   "bin": {
     "schema-codegen": "bin/schema-codegen",
@@ -14,13 +14,13 @@
     "bench:gate": "node bench/run.mjs --assert --samples 3 --filter gate",
     "profile:cpu": "node bench/profile.mjs --cpu",
     "profile:heap": "node bench/profile.mjs --heap",
-    "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
-    "watch": "tsc -p tsconfig.build.json -w",
-    "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
+    "build": "node node_modules/typescript/bin/tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
+    "watch": "node node_modules/typescript/bin/tsc -p tsconfig.build.json -w",
+    "typecheck:build": "node node_modules/typescript/bin/tsc -p tsconfig.build.json --noEmit",
     "test": "npm run test:types && tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
-    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && tsc -p tsconfig.types-nostrict.json",
+    "test:types": "node node_modules/typescript/bin/tsc -p tsconfig.build.json && node test/types/run.mjs typescript typescript-7",
     "test:exports": "node test/verify-exports.mjs",
-    "typecheck": "tsc -p tsconfig.test.json",
+    "typecheck": "node node_modules/typescript/bin/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",
@@ -94,7 +94,8 @@
     "source-map-support": "^0.5.13",
     "tslib": "^2.1.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-7": "npm:typescript@^7.0.2"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"

package/src/Metadata.ts

@@ -488,6 +488,10 @@ export 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] as DefinitionType);
             fieldIndex++;
         }

package/src/annotations.ts

@@ -626,11 +626,11 @@ export function defineTypes(
 
 // Helper type to extract InitProps from initialize method.
 // - Non-empty initialize params: use them directly.
-// - Zero-arg initialize: no args accepted (`never`) — user-supplied field
-//   values would be dropped at runtime (parent's initialize is skipped
-//   during child construction via the `new.target === klass` guard, and
-//   own-field auto-assignment happens only inside initialize).
+// - Zero-arg initialize: no args accepted (`never`) — an initialize() owns the
+//   fields, so user-supplied values would be dropped at runtime.
 // - No initialize at all: derive from fields map.
+// `T & T2` from `.extend()` carries the parent's initialize unless the child
+// redefines it, matching the runtime (the most-derived one runs).
 type ExtractInitProps<T> = T extends { initialize: (...args: infer P) => void }
     ? P extends readonly []
         ? never
@@ -668,9 +668,13 @@ type HasExplicitInit<T> = T extends { initialize: (...args: infer P) => void }
  */
 export type FieldsAndMethods = Record<string, FieldBuilder<any, boolean, boolean> | (new (...args: any[]) => Schema) | Function>;
 
+// One spelling for every site that names the instance — identical
+// instantiations compare by identity, not structurally.
+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>>,
+        fields: T2 & ThisType<SchemaInstance<T & T2, P>>,
         name?: string,
     ) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T & T2>, P>;
 }
@@ -692,7 +696,7 @@ export interface SchemaWithExtendsConstructor<
     InitProps,
     P extends typeof Schema
 > extends SchemaWithExtends<T, P> {
-    '~type': InferSchemaInstanceType<T>;
+    '~type': SchemaInstance<T, P>;
     // Constructor signature:
     //  - InitProps = never (zero-arg initialize): no args.
     //  - InitProps is a tuple (multi-arg initialize): spread it.
@@ -708,10 +712,8 @@ export interface SchemaWithExtendsConstructor<
         : 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;
-    };
+    ): SchemaInstance<T, P>;
+    prototype: SchemaInstance<T, P>;
 }
 
 /**
@@ -738,6 +740,9 @@ function makeAutoDefaultFactory(rawType: any): (() => any) | undefined {
 /**
  * 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';
  *
@@ -755,7 +760,7 @@ export function schema<
     T extends FieldsAndMethods,
     P extends typeof Schema = typeof Schema
 >(
-    fieldsAndMethods: T & ThisType<InferSchemaInstanceType<T>>,
+    fieldsAndMethods: T & ThisType<SchemaInstance<T, P>>,
     name?: string,
     inherits: P = Schema as P,
 ): SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P> {
@@ -906,9 +911,12 @@ export function schema<
     };
 
     const hasInitialize = typeof methods.initialize === "function";
+    // 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 as any)._initialize;
 
-    /** @codegen-ignore */
-    const klass = Metadata.setFields<any>(class extends (inherits as any) {
+    const klass = class extends (inherits as any) {
         constructor(...args: any[]) {
             const props = args[0];
             if (props === undefined) {
@@ -922,14 +930,22 @@ export function 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) as unknown as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
+    } as unknown as SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
+
+    // named before setFields so a duplicate-field error can say which class
+    if (name) {
+        Object.defineProperty(klass, "name", { value: name });
+    }
+    /** @codegen-ignore */
+    Metadata.setFields<any>(klass, fields);
 
     (klass as any)._getDefaultValues = getDefaultValues;
+    (klass as any)._initialize = initialize;
 
     Object.assign(klass.prototype, methods);
 
@@ -966,10 +982,6 @@ export function schema<
         }
     }
 
-    if (name) {
-        Object.defineProperty(klass, "name", { value: name });
-    }
-
     (klass as any).extend = <T2 extends FieldsAndMethods = FieldsAndMethods>(
         childFields: T2,
         childName?: string,

package/src/decoder/strategy/Callbacks.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../../Metadata.js";
-import { Collection, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { Collection, NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import type { IRef, Ref } from "../../encoder/ChangeTree.js";
 import { Decoder } from "../Decoder.js";
 import { DataChange } from "../DecodeOperation.js";
@@ -25,25 +25,24 @@ 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
-type PublicPropNames<T> = Exclude<NonFunctionPropNames<T>, typeof $refId> & string;
+type PublicPropNames<T> = NonFunctionPropNames<T> & string;
 
 // Extract only properties that extend Collection
-type CollectionPropNames<T> = Exclude<{
-    [K in keyof T]: T[K] extends Collection<any, any> ? K : never
-}[keyof T] & string, typeof $refId>;
+type CollectionPropNames<T> = {
+    [K in keyof T]: T[K] extends CollectionLike<any, any> ? K : never
+}[keyof T] & string;
 
 // Infer the value type of a collection property
 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;
+    T[K] extends CollectionLike<any, infer V, any> ? V : never;
 
 // Infer the key type of a collection property
 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;
+    T[K] extends CollectionLike<infer Key, any, any> ? Key : never;
 
 export class StateCallbackStrategy<TState extends IRef> {
     protected decoder: Decoder<TState>;

package/src/decoder/strategy/getDecoderStateCallbacks.ts

@@ -1,5 +1,5 @@
 import { Metadata } from "../../Metadata.js";
-import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames } from "../../types/HelperTypes.js";
+import { Collection, NonFunctionNonPrimitivePropNames, NonFunctionPropNames, CollectionLike } from "../../types/HelperTypes.js";
 import { IRef, Ref } from "../../encoder/ChangeTree.js";
 import { Decoder } from "../Decoder.js";
 import { DataChange } from "../DecodeOperation.js";
@@ -30,7 +30,7 @@ export type GetCallbackProxy = SchemaCallbackProxy<any>; // workaround for compa
 
 export type CallbackProxy<T> = unknown extends T // is "any"?
     ? SchemaCallback<T> & CollectionCallback<any, any>
-    : T extends Collection<infer K, infer V, infer _>
+    : T extends CollectionLike<infer K, infer V, infer _>
         ? CollectionCallback<K, V>
         : SchemaCallback<T>;
 

package/src/types/HelperTypes.ts

@@ -17,10 +17,18 @@ type PrimitiveStringToType<T> =
     : T extends "boolean" ? boolean
     : T;
 
-export interface Collection<K = any, V = any, IT = V> {
+/**
+ * What the decoder callbacks accept as "a collection": the public shape, which
+ * a plain array satisfies too — `@type([X]) items: X[]` is a common way to
+ * declare a field. {@link Collection} is the runtime contract on top of it.
+ */
+export interface CollectionLike<K = any, V = any, IT = V> {
     [Symbol.iterator](): IterableIterator<IT>;
     forEach(callback: Function): void;
     entries(): IterableIterator<[K, V]>;
+}
+
+export interface Collection<K = any, V = any, IT = V> extends CollectionLike<K, V, IT> {
     /** See {@link $resyncPrune} — every collection kind must declare its resync-sweep semantics. */
     [$resyncPrune](
         visited: Set<number | string>,
@@ -90,13 +98,13 @@ export type InferValueType<T> =
 // Keys whose builder carries the `.optional()` brand. Reads the brand rather
 // than `undefined extends V`: the latter is true for EVERY V when the consumer
 // compiles with `strictNullChecks: false`, flipping all fields optional.
-type OptionalBuilderKeys<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean>
-        ? (O extends true ? K : never)
-        : never
-}[keyof T];
+type IsOptionalBuilderKey<T, K extends keyof T> =
+    T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? O : false;
 
-type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
+// Per key, like `DataKey` below — an `Exclude<keyof T, …>` split defers every
+// key once one field is typed by a bare type parameter.
+type OptionalBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? K : never }[keyof T];
+type RequiredBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? never : K }[keyof T];
 
 export type InferSchemaInstanceType<T> = {
     [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any>
@@ -110,20 +118,20 @@ export type InferSchemaInstanceType<T> = {
         : never
 } & Schema;
 
-export type NonFunctionProps<T> = Omit<T, {
-    [K in keyof T]: T[K] extends Function ? K : never;
-}[keyof T]>;
+// Per-key filter, never `Omit`/`Exclude` over the union of method names: with
+// one field typed by a bare type parameter that union defers EVERY key, and a
+// mapped type with no resolvable keys has no members to relate — which is what
+// stopped `SpecialNode<E>` from satisfying `extends NodeBase`.
+// `keyof Schema` is dropped so `restore({ ... })` takes a plain literal.
+type DataKey<T, K extends keyof T> =
+    K extends keyof Schema ? never
+    : T[K] extends Function ? never
+    : K;
 
-export type NonFunctionPropNames<T> = {
-    [K in keyof T]: T[K] extends Function ? never : K
-}[keyof T];
+export type NonFunctionPropNames<T> = { [K in keyof T]-?: DataKey<T, K> }[keyof T];
 
 export type NonFunctionNonPrimitivePropNames<T> = {
-    [K in keyof T]: T[K] extends Function
-        ? never
-        : T[K] extends number | string | boolean
-            ? never
-            : K
+    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : T[K] extends number | string | boolean ? never : K
 }[keyof T];
 
 // Helper to recursively convert Schema instances to their JSON representation
@@ -138,21 +146,23 @@ type ToJSONField<X> =
     : X extends Schema ? ToJSON<X>
     : X;
 
-// Keys whose value admits `undefined` — runtime `toJSON()` omits those, so
-// they surface as `?:` on the JSON shape. Under `strictNullChecks: false`
-// (`undefined extends {}` detects it) `undefined extends T[K]` is true for
-// every key, so only the `?` modifier can signal optionality there.
-type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends {}
-        ? ({} extends Pick<T, K> ? K : never)
-        : (undefined extends T[K] ? K : never)
-}[keyof T];
-type ToJSONRequiredKeys<T> = Exclude<keyof T, ToJSONOptionalKeys<T>>;
-
-export type ToJSON<T> = NonFunctionProps<
+// Runtime `toJSON()` omits `undefined` values, so those keys surface as `?:`.
+// Under `strictNullChecks: false` (`undefined extends {}` detects it)
+// `undefined extends T[K]` is true for every key, so only the `?` modifier
+// can signal optionality there.
+type IsOptionalKey<T, K extends keyof T> = undefined extends {}
+    ? ({} extends Pick<T, K> ? true : false)
+    : (undefined extends T[K] ? true : false);
+
+// `DataKey` first: machinery and method keys drop before the optionality probe.
+type ToJSONRequiredKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? never : K }[keyof T];
+type ToJSONOptionalKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? K : never }[keyof T];
+
+// Keys are filtered before mapping: `ToJSONField` over the `this`-typed methods
+// exceeds TypeScript 7's instantiation depth.
+export type ToJSON<T> =
     & { [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]> }
-    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> }
->;
+    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> };
 
 /**
  * The plain DATA shape of a Schema instance type `T`: its synchronized fields
@@ -172,8 +182,7 @@ export type ToJSON<T> = NonFunctionProps<
  *
  * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
  * structural projection: nested Schema / collection fields keep their instance
- * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
- * `NonFunctionProps` pass leaves behind.
+ * types.
  */
 export type Data<T> = Omit<T, keyof Schema>;