@colyseus/schema 4.0.20 → 5.0.1

package/README.md

@@ -260,6 +260,8 @@ up-to-date version of the schema definitions.
 ## Limitations and best practices
 
 - Each `Schema` structure can hold up to `64` fields. If you need more fields, use nested structures.
+- Fields tagged with `@view`, `@unreliable`, or `@static` at field indexes `≥ 32` use a slower per-mutation classification path (linear scan over the tagged-field list instead of a single bitwise op). For schemas with more than 32 fields, declare frequently-mutated tagged fields earlier so they fall in the bitmask fast path.
+- Schemas with `≤ 8` fields store per-field operation bytes inline in two numbers (no allocation per instance). Schemas with `> 8` fields allocate a small `Uint8Array` per instance for op storage. The difference is only material when allocating thousands of instances per tick — prefer narrower nested structures in that regime.
 - `NaN` or `null` numbers are encoded as `0`
 - `null` strings are encoded as `""`
 - `Infinity` numbers are encoded as `Number.MAX_SAFE_INTEGER`

package/build/Metadata.d.ts

@@ -1,12 +1,18 @@
 import { DefinitionType } from "./annotations.js";
-import { $descriptors, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
+import { TypeDefinition } from "./types/registry.js";
+import { $descriptors, $encoders, $fieldIndexesByViewTag, $numFields, $refTypeFieldIndexes, $staticFieldIndexes, $streamFieldIndexes, $streamPriorities, $transientFieldIndexes, $unreliableFieldIndexes, $viewFieldIndexes } from "./types/symbols.js";
 export type MetadataField = {
     type: DefinitionType;
     name: string;
     index: number;
     tag?: number;
     unreliable?: boolean;
+    transient?: boolean;
     deprecated?: boolean;
+    owned?: boolean;
+    static?: boolean;
+    stream?: boolean;
+    optional?: boolean;
 };
 export type Metadata = {
     [$numFields]: number;
@@ -22,6 +28,26 @@ export type Metadata = {
 {
     [$refTypeFieldIndexes]: number[];
 } & // all field indexes containing Ref types (Schema, ArraySchema, MapSchema, etc)
+{
+    [$unreliableFieldIndexes]: number[];
+} & // all field indexes tagged with @unreliable
+{
+    [$transientFieldIndexes]: number[];
+} & // all field indexes tagged with @transient (not persisted to snapshots)
+{
+    [$staticFieldIndexes]: number[];
+} & // all field indexes tagged with @static (not tracked after assignment)
+{
+    [$streamFieldIndexes]: number[];
+} & // all field indexes holding a t.stream(...) collection
+{
+    [$streamPriorities]: {
+        [field: number]: (view: any, element: any) => number;
+    };
+} & // per-stream-field priority callback declared at schema definition time
+{
+    [$encoders]: Array<(bytes: Uint8Array, value: any, it: any) => void>;
+} & // pre-computed encoder fn per primitive field
 {
     [field: number]: MetadataField;
 } & // index => field name
@@ -33,17 +59,45 @@ export type Metadata = {
         [field: string]: PropertyDescriptor;
     };
 };
+/**
+ * Given a normalized field type (`"number"`, `{ map: Foo }`, `Player`,
+ * etc.), split into the collection-type descriptor (`{ constructor:
+ * MapSchema, ... }`) if applicable and the inner child type. Shared by
+ * `@type()` decoration and `Metadata.setFields` — both need to build a
+ * property accessor that knows whether the slot holds a collection.
+ */
+export declare function resolveFieldType(type: any): {
+    complexTypeKlass: TypeDefinition | false;
+    childType: any;
+};
 export declare function getNormalizedType(type: any): DefinitionType;
 export declare const Metadata: {
     addField(metadata: any, index: number, name: string, type: DefinitionType, descriptor?: PropertyDescriptor): void;
     setTag(metadata: Metadata, fieldName: string, tag: number): void;
+    setUnreliable(metadata: Metadata, fieldName: string): void;
+    setTransient(metadata: Metadata, fieldName: string): void;
+    setStatic(metadata: Metadata, fieldName: string): void;
+    setStream(metadata: Metadata, fieldName: string): void;
+    /**
+     * Attach a declaration-scope priority callback to a stream field.
+     * Called at schema definition time (via `t.stream(X).priority(fn)` or
+     * `@type({ stream: X, priority: fn })`), looked up at stream-attach
+     * time to seed the instance's `_stream.priority` slot. The callback
+     * signature is `(view: StateView, element: V) => number` — only fires
+     * during `encodeView`, broadcast mode emits FIFO regardless.
+     */
+    setStreamPriority(metadata: Metadata, fieldName: string, fn: (view: any, element: any) => number): void;
+    getStreamPriority(metadata: Metadata | undefined, index: number): (view: any, element: any) => number;
     setFields<T extends {
         new (...args: any[]): InstanceType<T>;
     } = any>(target: T, fields: { [field in keyof InstanceType<T>]?: DefinitionType; }): T;
     isDeprecated(metadata: any, field: string): boolean;
-    init(klass: any): void;
     initialize(constructor: any): Metadata;
     isValidInstance(klass: any): boolean;
     getFields(klass: any): any;
     hasViewTagAtIndex(metadata: Metadata, index: number): boolean;
+    hasUnreliableAtIndex(metadata: Metadata, index: number): boolean;
+    hasTransientAtIndex(metadata: Metadata, index: number): boolean;
+    hasStaticAtIndex(metadata: Metadata, index: number): boolean;
+    hasStreamAtIndex(metadata: Metadata, index: number): boolean;
 };

package/build/Reflection.d.ts

@@ -3,6 +3,8 @@ import { Iterator } from "./encoding/decode.js";
 import { Encoder } from "./encoder/Encoder.js";
 import { Decoder } from "./decoder/Decoder.js";
 import { Schema } from "./Schema.js";
+import { FieldBuilder } from "./types/builder.js";
+import { ArraySchema } from "./types/custom/ArraySchema.js";
 /**
  * Static methods available on Reflection
  */
@@ -28,44 +30,36 @@ interface ReflectionStatic {
  * Reflection
  */
 export declare const ReflectionField: import("./annotations.js").SchemaWithExtendsConstructor<{
-    name: "string";
-    type: "string";
-    referencedType: "number";
-}, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-    name: "string";
-    type: "string";
-    referencedType: "number";
-}>>, typeof Schema>;
+    name: FieldBuilder<string, false, false>;
+    type: FieldBuilder<string, false, false>;
+    referencedType: FieldBuilder<number, false, false>;
+}, import("./types/HelperTypes.js").BuilderInitProps<{
+    name: FieldBuilder<string, false, false>;
+    type: FieldBuilder<string, false, false>;
+    referencedType: FieldBuilder<number, false, false>;
+}>, typeof Schema>;
 export type ReflectionField = SchemaType<typeof ReflectionField>;
 export declare const ReflectionType: import("./annotations.js").SchemaWithExtendsConstructor<{
-    id: "number";
-    extendsId: "number";
-    fields: import("./annotations.js").SchemaWithExtendsConstructor<{
-        name: "string";
-        type: "string";
-        referencedType: "number";
-    }, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-        name: "string";
-        type: "string";
-        referencedType: "number";
-    }>>, typeof Schema>[];
-}, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-    id: "number";
-    extendsId: "number";
-    fields: import("./annotations.js").SchemaWithExtendsConstructor<{
-        name: "string";
-        type: "string";
-        referencedType: "number";
-    }, import("./index.js").AssignableProps<import("./index.js").InferSchemaInstanceType<{
-        name: "string";
-        type: "string";
-        referencedType: "number";
-    }>>, typeof Schema>[];
-}>>, typeof Schema>;
+    id: FieldBuilder<number, false, false>;
+    extendsId: FieldBuilder<number, false, false>;
+    fields: FieldBuilder<ArraySchema<{} & {
+        name?: string;
+        type?: string;
+        referencedType?: number;
+    } & Schema<any> & Schema<unknown>>, true, false>;
+}, import("./types/HelperTypes.js").BuilderInitProps<{
+    id: FieldBuilder<number, false, false>;
+    extendsId: FieldBuilder<number, false, false>;
+    fields: FieldBuilder<ArraySchema<{} & {
+        name?: string;
+        type?: string;
+        referencedType?: number;
+    } & Schema<any> & Schema<unknown>>, true, false>;
+}>, typeof Schema>;
 export type ReflectionType = SchemaType<typeof ReflectionType>;
 export declare const Reflection: ReturnType<typeof schema<{
-    types: [typeof ReflectionType];
-    rootType: "number";
+    types: FieldBuilder<ArraySchema<ReflectionType>, true, false>;
+    rootType: FieldBuilder<number, false, false>;
 }>> & ReflectionStatic;
 export type Reflection = SchemaType<typeof Reflection>;
 export {};

package/build/Schema.d.ts

@@ -1,8 +1,8 @@
 import { OPERATION } from './encoding/spec.js';
 import { type DefinitionType } from "./annotations.js";
 import { AssignableProps, NonFunctionPropNames, ToJSON } from './types/HelperTypes.js';
-import { ChangeSetName, ChangeTree, IRef, Ref } from './encoder/ChangeTree.js';
-import { $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $refId, $track } from './types/symbols.js';
+import { ChangeTree, IRef, Ref } from './encoder/ChangeTree.js';
+import { $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $refId, $track, $values } from './types/symbols.js';
 import { StateView } from './encoder/StateView.js';
 import type { Decoder } from './decoder/Decoder.js';
 import type { Metadata } from './Metadata.js';
@@ -14,21 +14,58 @@ export declare class Schema<C = any> implements IRef {
     static [$encoder]: import("./encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("./decoder/DecodeOperation.js").DecodeOperation<any>;
     [$refId]?: number;
+    [$values]: any[];
     /**
-     * Assign the property descriptors required to track changes on this instance.
-     * @param instance
+     * Initialize change tracking on this instance.
+     * Field accessor descriptors (getter/setter) live on the prototype,
+     * installed once at class-definition time. Per-instance work is limited
+     * to allocating a ChangeTree and a values array.
      */
     static initialize(instance: any): void;
+    /**
+     * Decoder-side factory. Skips the user subclass ctor entirely —
+     * decoder-built instances are passive mirrors of server state, so any
+     * field initializer / ctor body work would be overwritten by the
+     * decoded ADDs immediately after. Assignment order matches
+     * {@link Schema.initialize} so V8 assigns the same hidden class
+     * ($changes, then $values), keeping decode-path ICs monomorphic even
+     * when tracked and untracked instances coexist.
+     *
+     * The `this:` constraint pins the return type to the concrete subclass
+     * when called as `Player.initializeForDecoder()`, not the base Schema.
+     */
+    static initializeForDecoder<T extends Schema = Schema>(this: {
+        prototype: T;
+    } & typeof Schema): T;
+    /**
+     * Check whether `type` describes a Schema *class* (a subclass
+     * constructor carrying `Symbol.metadata`, as installed by `@type`).
+     * Returns false for primitive type strings like `"number"`, descriptor
+     * objects like `{ map: Player }`, and Schema *instances*.
+     *
+     * For the instance-level check — "is this value a Schema instance?" —
+     * see {@link Schema.isSchema}.
+     */
     static is(type: DefinitionType): boolean;
     /**
-     * Check if a value is an instance of Schema.
-     * This method uses duck-typing to avoid issues with multiple @colyseus/schema versions.
+     * Check if a value is an *instance* of Schema. Uses duck-typing on
+     * `.assign` to work across multiple `@colyseus/schema` versions that
+     * may be loaded in the same process (e.g. bundled server types vs.
+     * client types in a p2p setup).
+     *
+     * For the class-level check — "is this type a Schema subclass?" —
+     * see {@link Schema.is}.
+     *
      * @param obj Value to check
      * @returns true if the value is a Schema instance
      */
     static isSchema(obj: any): obj is Schema;
     /**
-     * Track property changes
+     * Track property changes. Exposed as an override point so downstream
+     * tools (debuggers, transparent proxies, custom instrumentation) can
+     * intercept per-field writes. Hot-path code in `annotations.ts` calls
+     * `(this.constructor as typeof Schema)[$track](...)` rather than
+     * `changeTree.change(...)` directly so any subclass override wins.
      */
     static [$track](changeTree: ChangeTree, index: number, operation?: OPERATION): void;
     /**
@@ -48,6 +85,12 @@ export declare class Schema<C = any> implements IRef {
      * @returns
      */
     assign<T extends Partial<this>>(props: AssignableProps<T>): this;
+    /**
+     * Metadata-driven property assignment.
+     * Reads tracked fields via property access (works with prototype accessors),
+     * then copies any remaining own properties for non-tracked fields.
+     */
+    protected static assignProps(target: any, source: any): void;
     /**
      * Restore the instance from JSON data.
      * @param jsonData JSON data to restore the instance from
@@ -61,6 +104,17 @@ export declare class Schema<C = any> implements IRef {
      * @param operation OPERATION to perform (detected automatically)
      */
     setDirty<K extends NonFunctionPropNames<this>>(property: K | number, operation?: OPERATION): void;
+    /** Stop recording mutations until resumeTracking() is called. */
+    pauseTracking(): void;
+    /** Re-enable automatic change tracking. */
+    resumeTracking(): void;
+    /**
+     * Run `fn` with change tracking paused, then resume.
+     * Returns the function's return value. Safe to nest.
+     */
+    untracked<T>(fn: () => T): T;
+    /** True while tracking is paused. */
+    get isTrackingPaused(): boolean;
     clone(): this;
     toJSON(this: any): ToJSON<this>;
     /**
@@ -78,7 +132,15 @@ export declare class Schema<C = any> implements IRef {
      * @returns
      */
     static debugRefIds<T extends Schema>(ref: T, showContents?: boolean, level?: number, decoder?: Decoder, keyPrefix?: string): string;
-    static debugRefIdEncodingOrder<T extends Ref>(ref: T, changeSet?: ChangeSetName): number[];
+    /**
+     * @param changeSet
+     *  - "changes": iterate the current-tick dirty queue (per-tick encode order)
+     *  - "allChanges" / "allFilteredChanges" (legacy): structurally walk the
+     *    tree in DFS preorder (matches the order in which full-sync emits
+     *    trees). The two legacy modes differ by which side of the filter
+     *    split they include.
+     */
+    static debugRefIdEncodingOrder<T extends Ref>(ref: T, changeSet?: "changes" | "allChanges" | "allFilteredChanges"): number[];
     static debugRefIdsFromDecoder(decoder: Decoder): string;
     /**
      * Return a string representation of the changes on a Schema instance.
@@ -89,5 +151,4 @@ export declare class Schema<C = any> implements IRef {
      * @returns
      */
     static debugChanges<T extends Ref>(instance: T, isEncodeAll?: boolean): string;
-    static debugChangesDeep<T extends Schema>(ref: T, changeSetName?: "changes" | "allChanges" | "allFilteredChanges" | "filteredChanges"): string;
 }

package/build/annotations.d.ts

@@ -3,10 +3,11 @@ import { Schema } from './Schema.js';
 import { ArraySchema } from './types/custom/ArraySchema.js';
 import { MapSchema } from './types/custom/MapSchema.js';
 import { TypeDefinition } from "./types/registry.js";
-import { OPERATION } from "./encoding/spec.js";
-import type { InferValueType, InferSchemaInstanceType, AssignableProps } from "./types/HelperTypes.js";
+import type { InferValueType, InferSchemaInstanceType, BuilderInitProps } from "./types/HelperTypes.js";
 import { CollectionSchema } from "./types/custom/CollectionSchema.js";
 import { SetSchema } from "./types/custom/SetSchema.js";
+import { StreamSchema } from "./types/custom/StreamSchema.js";
+import { FieldBuilder } from "./types/builder.js";
 export type RawPrimitiveType = "string" | "number" | "boolean" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" | "bigint64" | "biguint64";
 export type PrimitiveType = RawPrimitiveType | typeof Schema | object;
 export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T | T[] | {
@@ -14,26 +15,38 @@ export type DefinitionType<T extends PrimitiveType = PrimitiveType> = T | T[] |
     default?: InferValueType<T>;
     view?: boolean | number;
     sync?: boolean;
+    owned?: boolean;
 } | {
     array: T;
     default?: ArraySchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
+    owned?: boolean;
 } | {
     map: T;
     default?: MapSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
+    owned?: boolean;
 } | {
     collection: T;
     default?: CollectionSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
+    owned?: boolean;
 } | {
     set: T;
     default?: SetSchema<InferValueType<T>>;
     view?: boolean | number;
     sync?: boolean;
+    owned?: boolean;
+} | {
+    stream: T;
+    default?: StreamSchema<InferValueType<T>>;
+    view?: boolean | number;
+    sync?: boolean;
+    owned?: boolean;
+    priority?: (view: any, element: InferValueType<T>) => number;
 };
 export type Definition = {
     [field: string]: DefinitionType;
@@ -60,10 +73,20 @@ export declare function entity(constructor: any): any;
  * ```
  */
 export declare function view<T>(tag?: number): (target: T, fieldName: string) => void;
+export declare function owned<T>(target: T, field: string): void;
 export declare function unreliable<T>(target: T, field: string): void;
+/**
+ * @transient — mark a field as not persisted to snapshots (encodeAll /
+ * encodeAllView). Transient fields are still emitted on per-tick patches
+ * (reliable or unreliable), but late-joining clients won't see them until
+ * the next mutation.
+ *
+ * Orthogonal to @unreliable: a field can be either, both, or neither.
+ */
+export declare function transient<T>(target: T, field: string): void;
 export declare function type(type: DefinitionType, options?: TypeOptions): PropertyDecorator;
-export declare function getPropertyDescriptor(fieldCached: string, fieldIndex: number, type: DefinitionType, complexTypeKlass: TypeDefinition): {
-    get: (this: Schema) => number | ((index: number) => any) | ((index: number) => void) | (() => Schema<any>) | (<T extends Partial<Schema<any>>>(props: AssignableProps<T>) => Schema<any>) | ((jsonData: import("./index.js").ToJSON<Schema<any>>) => Schema<any>) | (<K extends "~refId">(property: number | K, operation?: OPERATION) => void) | ((this: any) => import("./index.js").ToJSON<Schema<any>>) | (() => void);
+export declare function getPropertyDescriptor(fieldName: string, fieldIndex: number, type: DefinitionType, complexTypeKlass: TypeDefinition | false): {
+    get: (this: Schema) => any;
     set: (this: Schema, value: any) => void;
     enumerable: boolean;
     configurable: boolean;
@@ -73,37 +96,61 @@ export declare function getPropertyDescriptor(fieldCached: string, fieldIndex: n
  * The previous `@type()` annotation should remain along with this one.
  */
 export declare function deprecated(throws?: boolean): PropertyDecorator;
-export declare function defineTypes(target: typeof Schema, fields: Definition, options?: TypeOptions): typeof Schema;
 type ExtractInitProps<T> = T extends {
     initialize: (...args: infer P) => void;
-} ? P extends readonly [] ? never : P extends readonly [infer First] ? First extends object ? First : P : P : T extends Definition ? AssignableProps<InferSchemaInstanceType<T>> : never;
+} ? P extends readonly [] ? never : P extends readonly [infer First] ? First extends object ? First : P : P : BuilderInitProps<T>;
+type HasRequiredKeys<X> = {} extends X ? false : true;
 type IsInitPropsRequired<T> = T extends {
-    initialize: (props: any) => void;
-} ? true : T extends {
+    initialize: (...args: infer P) => void;
+} ? P extends readonly [] ? false : true : HasRequiredKeys<BuilderInitProps<T>>;
+type HasExplicitInit<T> = T extends {
     initialize: (...args: infer P) => void;
 } ? P extends readonly [] ? false : true : false;
-export interface SchemaWithExtends<T extends Definition, P extends typeof Schema> {
-    extends: <T2 extends Definition = Definition>(fields: T2 & ThisType<InferSchemaInstanceType<T & T2>>, name?: string) => SchemaWithExtendsConstructor<T & T2, ExtractInitProps<T2>, P>;
+/**
+ * A `schema()` field definition accepts a FieldBuilder, a Schema subclass
+ * (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>;
+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>;
 }
 /**
- * Get the type of the schema defined via `schema({...})` method.
+ * Get the type of the schema defined via `schema('Name', {...})` method.
  *
  * @example
- * const Entity = schema({
- *     x: "number",
- *     y: "number",
+ * const Entity = schema('Entity', {
+ *     x: t.number(),
+ *     y: t.number(),
  * });
  * type Entity = SchemaType<typeof Entity>;
  */
 export type SchemaType<T extends {
     '~type': any;
 }> = T['~type'];
-export interface SchemaWithExtendsConstructor<T extends Definition, InitProps, P extends typeof Schema> extends SchemaWithExtends<T, P> {
+export interface SchemaWithExtendsConstructor<T, InitProps, P extends typeof Schema> extends SchemaWithExtends<T, P> {
     '~type': InferSchemaInstanceType<T>;
-    new (...args: [InitProps] extends [never] ? [] : InitProps extends readonly any[] ? InitProps : IsInitPropsRequired<T> extends true ? [InitProps] : [InitProps?]): InferSchemaInstanceType<T> & InstanceType<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;
     };
 }
-export declare function schema<T extends Record<string, DefinitionType>, P extends typeof Schema = typeof Schema>(fieldsAndMethods: T & ThisType<InferSchemaInstanceType<T>>, name?: string, inherits?: P): SchemaWithExtendsConstructor<T, ExtractInitProps<T>, P>;
+/**
+ * Define a Schema class declaratively.
+ *
+ * @example
+ * import { schema, t } from '@colyseus/schema';
+ *
+ * const Player = schema({
+ *   hp: t.uint8().default(100),
+ *   name: t.string().view(),
+ *   takeDamage(n: number) { this.hp -= n; },
+ * }, 'Player');
+ *
+ * const Warrior = Player.extend({
+ *   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 {};