@colyseus/schema 5.0.19 → 5.0.20

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.20",
+  "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/annotations.ts

@@ -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,8 +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> & {
+    ): SchemaInstance<T, P>;
+    prototype: SchemaInstance<T, P> & {
         initialize(...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : [InitProps]): void;
     };
 }
@@ -755,7 +759,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> {

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>;