@colyseus/schema 5.0.20 → 5.0.22

package/build/types/HelperTypes.d.ts

@@ -8,7 +8,7 @@ import type { SetSchema } from "./custom/SetSchema.js";
 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;
+type PrimitiveStringToType<T> = T extends "string" ? string : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number : T extends "bigint64" | "biguint64" ? bigint : T extends "boolean" ? boolean : T;
 /**
  * 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
@@ -23,7 +23,7 @@ export interface Collection<K = any, V = any, IT = V> extends CollectionLike<K,
     /** 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;
 }
-export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "boolean" ? boolean : T extends {
+export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "bigint64" ? bigint : T extends "biguint64" ? bigint : T extends "boolean" ? boolean : T extends {
     type: infer ChildType extends PrimitiveType;
 } ? InferValueType<ChildType> : T extends {
     type: infer ChildType extends Constructor;
@@ -76,6 +76,18 @@ 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;
+/**
+ * Codecs that can carry a `T` — {@link InferValueType} run backwards, derived
+ * from it so the two can't drift. Constrains the element refinement in
+ * `t.array<Mark>("uint8")`; `never` (an uncallable overload) when no codec
+ * decodes into `T`.
+ *
+ * `[T] extends [...]` is deliberate: a distributive check would let a mixed
+ * union like `string | number` match on either half.
+ */
+export type CodecFor<T> = {
+    [K in RawPrimitiveType]: [T] extends [InferValueType<K>] ? K : never;
+}[RawPrimitiveType];
 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]-?: IsOptionalBuilderKey<T, K> extends true ? K : never;

package/build/types/builder.d.ts

@@ -5,7 +5,7 @@ import type { CollectionSchema } from "./custom/CollectionSchema.js";
 import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { Schema } from "../Schema.js";
 import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
-import type { InferValueType, Constructor } from "./HelperTypes.js";
+import type { InferValueType, Constructor, CodecFor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
 import { type QuantizeOptions } from "./quantize.js";
 /**
@@ -217,18 +217,22 @@ export type ChildType = RawPrimitiveType | Constructor<Schema>;
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<ArraySchema<T>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<MapSchema<T>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<SetSchema<T>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<CollectionSchema<T>, true, false>;
 }
 interface StreamFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>, true, false>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.20",
+  "version": "5.0.22",
   "description": "Automatic state replication for multiplayer games. Mutate plain objects, and every client gets a live, typed mirror through delta encoding.",
   "type": "module",
   "bin": {

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
@@ -713,9 +713,7 @@ export interface SchemaWithExtendsConstructor<
         : IsInitPropsRequired<T> extends true ? ([] | [InitProps])
         : [InitProps?]
     ): SchemaInstance<T, P>;
-    prototype: SchemaInstance<T, P> & {
-        initialize(...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : [InitProps]): void;
-    };
+    prototype: SchemaInstance<T, P>;
 }
 
 /**
@@ -742,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';
  *
@@ -910,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) {
@@ -926,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);
 
@@ -970,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/types/HelperTypes.ts

@@ -14,6 +14,7 @@ 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 "bigint64" | "biguint64" ? bigint
     : T extends "boolean" ? boolean
     : T;
 
@@ -53,6 +54,8 @@ export type InferValueType<T> =
     : T extends "uint64" ? number
     : T extends "float32" ? number
     : T extends "float64" ? number
+    : T extends "bigint64" ? bigint
+    : T extends "biguint64" ? bigint
     : T extends "boolean" ? boolean
 
     // Handle { type: ... } patterns
@@ -95,6 +98,19 @@ export type InferValueType<T> =
 
     : never;
 
+/**
+ * Codecs that can carry a `T` — {@link InferValueType} run backwards, derived
+ * from it so the two can't drift. Constrains the element refinement in
+ * `t.array<Mark>("uint8")`; `never` (an uncallable overload) when no codec
+ * decodes into `T`.
+ *
+ * `[T] extends [...]` is deliberate: a distributive check would let a mixed
+ * union like `string | number` match on either half.
+ */
+export type CodecFor<T> = {
+    [K in RawPrimitiveType]: [T] extends [InferValueType<K>] ? K : never
+}[RawPrimitiveType];
+
 // 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.

package/src/types/builder.ts

@@ -5,7 +5,7 @@ import type { CollectionSchema } from "./custom/CollectionSchema.js";
 import type { StreamSchema } from "./custom/StreamSchema.js";
 import type { Schema } from "../Schema.js";
 import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
-import type { InferValueType, Constructor } from "./HelperTypes.js";
+import type { InferValueType, Constructor, CodecFor } from "./HelperTypes.js";
 import { $builder } from "./symbols.js";
 import { ARRAY_STREAM_NOT_SUPPORTED } from "../encoder/streaming.js";
 import { resolveQuantize, type QuantizeOptions } from "./quantize.js";
@@ -337,21 +337,28 @@ function resolveChild(child: ChildType): DefinitionType {
 // overloads narrow the return type for Schema/primitive children.
 // All collection factories tag `HasDefault = true` because schema() auto-
 // instantiates an empty collection when no explicit default is given.
+//
+// The third overload refines the ELEMENT type (`t.map<V>` — the value, never
+// the key), with the same type-level-only caveat as `PrimitiveFactory` above.
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<ArraySchema<T>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<MapSchema<T>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<SetSchema<T>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <T>(child: CodecFor<T>): FieldBuilder<CollectionSchema<T>, true, false>;
 }
 // t.stream(Entity) — priority-batched collection of Schema instances.
 // Element type is restricted to Schema subclasses (no primitives) because