@colyseus/schema 4.0.19 → 5.0.0

package/src/types/custom/SetSchema.ts

@@ -2,9 +2,16 @@ import { OPERATION } from "../../encoding/spec.js";
 import { registerType } from "../registry.js";
 import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
 import { Collection } from "../HelperTypes.js";
-import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
-import { encodeKeyValueOperation } from "../../encoder/EncodeOperation.js";
-import { decodeKeyValueOperation } from "../../decoder/DecodeOperation.js";
+import { ChangeTree, installUntrackedChangeTree, type IRef } from "../../encoder/ChangeTree.js";
+import { encodeIndexedEntry } from "../../encoder/EncodeOperation.js";
+import { CollectionKind, decodeKeyValueOperation } from "../../decoder/DecodeOperation.js";
+import {
+    createStreamableState,
+    streamDropView,
+    streamRouteAdd,
+    streamRouteRemove,
+    type StreamableState,
+} from "../../encoder/streaming.js";
 import type { StateView } from "../../encoder/StateView.js";
 import type { Schema } from "../../Schema.js";
 
@@ -14,14 +21,42 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
 
     protected [$childType]: string | typeof Schema;
 
+    /** The user-visible data, keyed directly by the wire-protocol index. */
     protected $items: Map<number, V> = new Map<number, V>();
-    protected $indexes: Map<number, number> = new Map<number, number>();
+
+    /** Snapshots of values that were deleted this tick (for filter visibility). */
     protected deletedItems: { [field: string]: V } = {};
 
+    /** Monotonic counter for assigning indexes to newly-added items. */
     protected $refId: number = 0;
 
-    static [$encoder] = encodeKeyValueOperation;
+    /**
+     * Streamable state — lazily allocated when the field is opted into
+     * streaming via `t.set(X).stream()`. See MapSchema for the same
+     * pattern / rationale.
+     */
+    _stream?: StreamableState;
+
+    /** Max ADD ops emitted per tick per view. Ignored outside streaming mode. */
+    get maxPerTick(): number {
+        return this._stream?.maxPerTick ?? 32;
+    }
+    set maxPerTick(n: number) {
+        (this._stream ??= createStreamableState()).maxPerTick = n;
+    }
+
+    /** Per-view priority callback — see StreamSchema / MapSchema. */
+    get priority(): ((view: any, element: V) => number) | undefined {
+        return this._stream?.priority as ((view: any, element: V) => number) | undefined;
+    }
+    set priority(fn: ((view: any, element: V) => number) | undefined) {
+        (this._stream ??= createStreamableState()).priority = fn;
+    }
+
+    static [$encoder] = encodeIndexedEntry;
     static [$decoder] = decodeKeyValueOperation;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND = CollectionKind.Set;
 
     /**
      * Determine if a property must be filtered.
@@ -36,7 +71,7 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
         return (
             !view ||
             typeof (ref[$childType]) === "string" ||
-            view.visible.has((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
+            view.isVisible((ref[$getByIndex](index) ?? ref.deletedItems[index])[$changes])
         );
     }
 
@@ -45,40 +80,60 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
     }
 
     constructor (initialValues?: Array<V>) {
-        this[$changes] = new ChangeTree(this);
-        this[$changes].indexes = {};
+        // $changes must be non-enumerable to avoid deepStrictEqual recursing
+        // into ChangeTree's circular refs.
+        Object.defineProperty(this, $changes, {
+            value: new ChangeTree(this),
+            enumerable: false,
+            writable: true,
+        });
+        this[$childType] = undefined as any;
 
         if (initialValues) {
             initialValues.forEach((v) => this.add(v));
         }
+    }
 
-        Object.defineProperty(this, $childType, {
-            value: undefined,
-            enumerable: false,
-            writable: true,
-            configurable: true,
-        });
+    /**
+     * Decoder-side factory. Skips the tracking `ChangeTree` allocation;
+     * `Object.create` also bypasses the class-field initializers, so we
+     * replicate the minimum slot init here. Must stay in sync with the
+     * class-field declarations above.
+     */
+    static initializeForDecoder<V = any>(): SetSchema<V> {
+        const self: any = Object.create(SetSchema.prototype);
+        self.$items = new Map<number, V>();
+        self.deletedItems = {};
+        self.$refId = 0;
+        self[$childType] = undefined;
+        installUntrackedChangeTree(self);
+        return self;
     }
 
     add(value: V) {
         // immediatelly return false if value already added.
         if (this.has(value)) { return false; }
 
-        // set "index" for reference.
+        // assign the next wire-protocol index
         const index = this.$refId++;
 
+        const changeTree = this[$changes];
         if ((value[$changes]) !== undefined) {
-            value[$changes].setParent(this, this[$changes].root, index);
+            value[$changes].setParent(this, changeTree.root, index);
         }
 
-        const operation = this[$changes].indexes[index]?.op ?? OPERATION.ADD;
-
-        this[$changes].indexes[index] = index;
-
-        this.$indexes.set(index, index);
         this.$items.set(index, value);
 
-        this[$changes].change(index, operation);
+        // Streaming-mode ADD: route into per-view pending or broadcast
+        // pending instead of the tree's recorder. See MapSchema.set for
+        // the same branch / rationale.
+        if (changeTree.isStreamCollection) {
+            if (changeTree.root !== undefined) {
+                streamRouteAdd(this, changeTree.root, index);
+            }
+        } else {
+            changeTree.change(index, OPERATION.ADD);
+        }
         return index;
     }
 
@@ -104,8 +159,26 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
             return false;
         }
 
-        this.deletedItems[index] = this[$changes].delete(index);
-        this.$indexes.delete(index);
+        const changeTree = this[$changes];
+
+        // Streaming-mode: route through stream's pending/sent bookkeeping
+        // — silent drop if never sent to any view, force DELETE for views
+        // that already received it. Mirror of MapSchema.delete's streaming
+        // branch.
+        if (changeTree.isStreamCollection) {
+            const root = changeTree.root;
+            const previousValue = this.$items.get(index);
+            if (root !== undefined) {
+                streamRouteRemove(this, root, (this as any)[$refId], index);
+            }
+            if ((previousValue as any)?.[$changes] !== undefined) {
+                root?.remove((previousValue as any)[$changes]);
+            }
+            this.deletedItems[index] = previousValue as V;
+            return this.$items.delete(index);
+        }
+
+        this.deletedItems[index] = changeTree.delete(index);
 
         return this.$items.delete(index);
     }
@@ -114,11 +187,7 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
         const changeTree = this[$changes];
 
         // discard previous operations.
-        changeTree.discard(true);
-        changeTree.indexes = {};
-
-        // clear previous indexes
-        this.$indexes.clear();
+        changeTree.discard();
 
         // clear items
         this.$items.clear();
@@ -155,31 +224,51 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
         return this.$items.size;
     }
 
+    // ────── Change tracking control (same API as Schema) ──────
+    pauseTracking(): void { this[$changes].pause(); }
+    resumeTracking(): void { this[$changes].resume(); }
+    untracked<T>(fn: () => T): T { return this[$changes].untracked(fn); }
+    get isTrackingPaused(): boolean { return this[$changes].paused; }
+
     /** Iterator */
     [Symbol.iterator](): IterableIterator<V> {
         return this.$items.values();
     }
 
-    protected setIndex(index: number, key: number) {
-        this.$indexes.set(index, key);
+    // ────────────────────────────────────────────────────────────────────
+    // Decoder-side index hooks. SetSchema's "key" IS the wire index, so
+    // these are identity operations. Kept for protocol symmetry with
+    // MapSchema (decoder calls them polymorphically).
+    // ────────────────────────────────────────────────────────────────────
+
+    protected setIndex(_index: number, _key: number) {
+        // no-op: indexes are identity
     }
 
-    protected getIndex(index: number) {
-        return this.$indexes.get(index);
+    protected getIndex(index: number): number {
+        return index;
     }
 
     [$getByIndex](index: number): any {
-        return this.$items.get(this.$indexes.get(index));
+        return this.$items.get(index);
     }
 
     [$deleteByIndex](index: number): void {
-        const key = this.$indexes.get(index);
-        this.$items.delete(key);
-        this.$indexes.delete(index);
+        this.$items.delete(index);
     }
 
     protected [$onEncodeEnd]() {
-        this.deletedItems = {};
+        for (const key in this.deletedItems) { delete this.deletedItems[key]; }
+    }
+
+    // ─── Streamable interface (Encoder priority / broadcast pass) ──────
+
+    _dropView(viewId: number): void {
+        streamDropView(this, viewId);
+    }
+
+    _unregister(): void {
+        // no-op — `Root.unregisterStream` handles the Set removal.
     }
 
     toArray() {
@@ -227,4 +316,4 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
 
 }
 
-registerType("set", { constructor: SetSchema });
+registerType("set", { constructor: SetSchema });

package/src/types/custom/StreamSchema.ts

@@ -0,0 +1,310 @@
+import { OPERATION } from "../../encoding/spec.js";
+import { registerType } from "../registry.js";
+import {
+    $changes,
+    $childType,
+    $decoder,
+    $deleteByIndex,
+    $encoder,
+    $filter,
+    $getByIndex,
+    $onEncodeEnd,
+    $refId,
+} from "../symbols.js";
+import { ChangeTree, installUntrackedChangeTree, type IRef } from "../../encoder/ChangeTree.js";
+import { encodeIndexedEntry } from "../../encoder/EncodeOperation.js";
+import { CollectionKind, decodeKeyValueOperation } from "../../decoder/DecodeOperation.js";
+import {
+    createStreamableState,
+    streamDropView,
+    streamRouteAdd,
+    streamRouteClear,
+    streamRouteRemove,
+    type StreamableState,
+} from "../../encoder/streaming.js";
+import type { StateView } from "../../encoder/StateView.js";
+import type { Schema } from "../../Schema.js";
+
+/**
+ * `t.stream(Entity)` — priority-batched collection of Schema instances.
+ *
+ * Designed for ECS-style use cases where many entities spawn/despawn each
+ * tick and the full set won't fit in one encode budget. Adds are queued
+ * per-client and drained in priority order (callback on StateView) up to
+ * `maxPerTick` per encode pass. Field mutations on already-sent elements
+ * propagate through the normal reliable channel without consuming the
+ * per-tick budget. Chain `.static()` on the field builder to suppress
+ * post-add mutation tracking entirely.
+ */
+export class StreamSchema<V = any> implements IRef {
+    [$changes]: ChangeTree;
+    [$refId]?: number;
+
+    protected [$childType]: string | typeof Schema;
+
+    /**
+     * Wire-keyed storage: `position → element`. Position is a monotonic
+     * counter assigned by `add()` — stable identity even when elements
+     * are removed, so pending/sent view state can keep using the same
+     * keys across ticks. Map (not Array) so `$items.keys()` / `.values()`
+     * skip removed positions without a sparse-slot check.
+     */
+    protected $items: Map<number, V> = new Map();
+
+    /** Monotonic position counter. Incremented on every `add()`. */
+    protected $nextPosition: number = 0;
+
+    /** Reverse lookup for O(1) `remove(el)`. */
+    protected _itemIndex: Map<V, number> = new Map();
+
+    /**
+     * Streamable state — holds per-view and broadcast bookkeeping. Lazily
+     * allocated when the stream is attached to a Root (or when the user
+     * touches `maxPerTick`). `undefined` on detached streams so
+     * construction is cheap.
+     */
+    _stream?: StreamableState;
+
+    /** Max element ADDs emitted per encode tick (per view, or broadcast). */
+    get maxPerTick(): number {
+        return this._stream?.maxPerTick ?? 32;
+    }
+    set maxPerTick(n: number) {
+        (this._stream ??= createStreamableState()).maxPerTick = n;
+    }
+
+    /**
+     * Per-view priority callback. Initialized from the schema declaration
+     * (`.priority(fn)` or `@type({ stream, priority })`); assigning here
+     * overrides the class-level default for this instance. Only fires
+     * during `encodeView` — broadcast mode drains FIFO.
+     */
+    get priority(): ((view: any, element: V) => number) | undefined {
+        return this._stream?.priority as ((view: any, element: V) => number) | undefined;
+    }
+    set priority(fn: ((view: any, element: V) => number) | undefined) {
+        (this._stream ??= createStreamableState()).priority = fn;
+    }
+
+    /**
+     * Brand used by Root / StateView to detect stream trees without
+     * importing this class (avoids circular deps). The `isStreamCollection`
+     * ChangeTree flag (set via `inheritedFlags`) is the preferred runtime
+     * check — this brand is kept for back-compat.
+     */
+    static readonly $isStream: true = true;
+
+    static [$encoder] = encodeIndexedEntry;
+    static [$decoder] = decodeKeyValueOperation;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND = CollectionKind.Stream;
+
+    /**
+     * Element-level visibility. Identical to SetSchema's filter: stream
+     * elements are always per-view, the filter just defers to the view's
+     * per-tree visibility bitmap.
+     */
+    static [$filter](ref: StreamSchema, index: number, view: StateView) {
+        if (!view) return true;
+        const value = (ref as any)[$getByIndex](index);
+        if (value === undefined) return false;
+        return view.isVisible(value[$changes]);
+    }
+
+    static is(type: any): boolean {
+        return type && type['stream'] !== undefined;
+    }
+
+    constructor() {
+        Object.defineProperty(this, $changes, {
+            value: new ChangeTree(this),
+            enumerable: false,
+            writable: true,
+        });
+        this[$childType] = undefined;
+        // `isFiltered` / `isStreamCollection` are set via `inheritedFlags`
+        // when this stream is attached to a parent field — no constructor-
+        // time init needed (the stream tree is inert until assignment).
+    }
+
+    /**
+     * Decoder-side factory. Skips the tracking `ChangeTree` allocation;
+     * `Object.create` also bypasses the class-field initializers, so we
+     * replicate the minimum slot init here. Must stay in sync with the
+     * class-field declarations above.
+     */
+    static initializeForDecoder<V = any>(): StreamSchema<V> {
+        const self: any = Object.create(StreamSchema.prototype);
+        self.$items = new Map<number, V>();
+        self.$nextPosition = 0;
+        self._itemIndex = new Map();
+        self[$childType] = undefined;
+        installUntrackedChangeTree(self);
+        return self;
+    }
+
+    /**
+     * Append an element to the stream. Returns the assigned position,
+     * or -1 if the element was already in the stream.
+     */
+    add(value: V): number {
+        if (this._itemIndex.has(value)) return -1;
+
+        const position = this.$nextPosition++;
+        this.$items.set(position, value);
+        this._itemIndex.set(value, position);
+
+        const tree = this[$changes];
+        const root = tree.root;
+
+        // Attach element as a child — assigns $refId and wires the parent
+        // chain so the element's own ChangeTree participates in encoding.
+        if (value[$changes] !== undefined) {
+            value[$changes].setParent(this, root, position);
+        }
+
+        if (root !== undefined) streamRouteAdd(this, root, position);
+        return position;
+    }
+
+    /**
+     * Remove an element by reference. If the element was pending (never sent
+     * to a view), the pending entry is dropped silently. If already sent,
+     * a DELETE op is forced on next `encodeView` for that view.
+     */
+    remove(value: V): boolean {
+        const position = this._itemIndex.get(value);
+        if (position === undefined) return false;
+
+        this._itemIndex.delete(value);
+        this.$items.delete(position);
+
+        const root = this[$changes].root;
+        if (root !== undefined) {
+            streamRouteRemove(this, root, (this as any)[$refId], position);
+            if (value[$changes] !== undefined) {
+                root.remove((value as any)[$changes]);
+            }
+        }
+
+        return true;
+    }
+
+    has(value: V): boolean {
+        return this._itemIndex.has(value);
+    }
+
+    /** Remove every element; queue DELETE wire ops for already-sent items. */
+    clear(): void {
+        const root = this[$changes].root;
+        if (root !== undefined) {
+            streamRouteClear(this, root, (this as any)[$refId]);
+            for (const el of this.$items.values()) {
+                if (el[$changes] !== undefined) {
+                    root.remove((el as any)[$changes]);
+                }
+            }
+        }
+        this.$items.clear();
+        this._itemIndex.clear();
+    }
+
+    forEach(callback: (value: V, index: number, collection: StreamSchema<V>) => void): void {
+        for (const [index, value] of this.$items) callback(value, index, this);
+    }
+
+    values(): IterableIterator<V> {
+        return this.$items.values();
+    }
+
+    /**
+     * Iterate `[position, value]` pairs in insertion order. Used by
+     * `setParent` recursion when the stream is reassigned to a new parent.
+     */
+    entries(): IterableIterator<[number, V]> {
+        return this.$items.entries();
+    }
+
+    [Symbol.iterator](): IterableIterator<V> {
+        return this.$items.values();
+    }
+
+    /** Live element count. */
+    get size(): number {
+        return this.$items.size;
+    }
+
+    /** Alias for `size`. */
+    get length(): number {
+        return this.$items.size;
+    }
+
+    // ────────────────────────────────────────────────────────────────────
+    // Decoder / encoder plumbing — same shape as SetSchema so
+    // {encode,decode}KeyValueOperation can route uniformly. StreamSchema
+    // keys are identity (wire index === position), so `setIndex`/`getIndex`
+    // are no-ops / identity like SetSchema.
+    // ────────────────────────────────────────────────────────────────────
+
+    protected setIndex(_index: number, _key: number): void {
+        // no-op: indexes are identity
+    }
+
+    protected getIndex(index: number): number {
+        return index;
+    }
+
+    [$getByIndex](index: number): V {
+        return this.$items.get(index) as V;
+    }
+
+    [$deleteByIndex](index: number): void {
+        const value = this.$items.get(index);
+        if (value !== undefined) {
+            this._itemIndex.delete(value);
+            this.$items.delete(index);
+        }
+    }
+
+    protected [$onEncodeEnd](): void {
+        // No per-tick cleanup: pending/sent state spans encode ticks by design.
+    }
+
+    toArray(): V[] {
+        return Array.from(this.$items.values());
+    }
+
+    toJSON(): any[] {
+        const out: any[] = [];
+        this.forEach((v: any) => {
+            out.push(typeof v?.toJSON === "function" ? v.toJSON() : v);
+        });
+        return out;
+    }
+
+    clone(isDecoding?: boolean): StreamSchema<V> {
+        if (isDecoding) {
+            const cloned = Object.assign(new StreamSchema<V>(), this);
+            return cloned;
+        }
+        const cloned = new StreamSchema<V>();
+        cloned.maxPerTick = this.maxPerTick;
+        this.forEach((v: any) => {
+            cloned.add(typeof v?.clone === "function" ? v.clone() : v);
+        });
+        return cloned;
+    }
+
+    // ─── Streamable interface (Encoder priority / broadcast pass) ──────
+
+    _dropView(viewId: number): void {
+        streamDropView(this, viewId);
+    }
+
+    /** Called by Root.remove when the stream's refcount hits zero. */
+    _unregister(): void {
+        // no-op — `Root.unregisterStream` handles the Set removal.
+    }
+}
+
+registerType("stream", { constructor: StreamSchema });

package/src/types/symbols.ts

@@ -1,4 +1,4 @@
-export const $refId = "~refId";
+export const $refId: unique symbol = Symbol("$refId");
 export const $track = "~track";
 export const $encoder = "~encoder";
 export const $decoder = "~decoder";
@@ -9,15 +9,26 @@ export const $getByIndex = "~getByIndex";
 export const $deleteByIndex = "~deleteByIndex";
 
 /**
- * Used to hold ChangeTree instances whitin the structures
+ * Used to hold ChangeTree instances whitin the structures.
+ *
+ * Real JS Symbol — see the `$values` comment for rationale.
  */
-export const $changes = '~changes';
+export const $changes: unique symbol = Symbol("$changes");
 
 /**
  * Used to keep track of the type of the child elements of a collection
- * (MapSchema, ArraySchema, etc.)
+ * (MapSchema, ArraySchema, etc.). Real Symbol — same rationale as $values.
  */
-export const $childType = '~childType';
+export const $childType: unique symbol = Symbol("$childType");
+
+/**
+ * Self-reference an instance sets on `this` so its own methods can recover
+ * the underlying object even when `this` is a Proxy wrapper. Used by
+ * ArraySchema (whose public API is a Proxy) to grab the underlying instance
+ * once at the top of hot methods and then access fields directly without
+ * paying the Proxy.get cost on every read.
+ */
+export const $proxyTarget: unique symbol = Symbol("$proxyTarget");
 
 /**
  * Optional "discard" method for custom types (ArraySchema)
@@ -30,11 +41,48 @@ export const $onEncodeEnd = '~onEncodeEnd';
  */
 export const $onDecodeEnd = "~onDecodeEnd";
 
+/**
+ * Per-instance dense array holding field values by index.
+ * Replaces per-field _fieldName shadow properties.
+ *
+ * Real JS Symbol (not "~"-prefixed string) so plain assignment is safe —
+ * symbols are non-enumerable to Object.keys / JSON.stringify / for-in,
+ * which means we can drop Object.defineProperty(...{ enumerable: false })
+ * and avoid the slow-path / dictionary-mode hazards that come with it.
+ */
+export const $values: unique symbol = Symbol("$values");
+
+/**
+ * Brand for FieldBuilder instances so schema() can detect them.
+ */
+export const $builder = "~builder";
+
 /**
  * Metadata
  */
 export const $descriptors = "~descriptors";
+
+/**
+ * Per-class bitmask: bit i set iff field i carries a @view tag.
+ * Lazily computed from $viewFieldIndexes on first encode pass.
+ * Skips the per-field metadata[i].tag property chase in the hot encode loop.
+ */
+export const $filterBitmask = "~__filterBitmask";
+
+/**
+ * Cached per-class encode descriptor: bundles encoder fn, filter fn,
+ * metadata, isSchema flag, and filterBitmask into one object stashed on
+ * the constructor. Replaces 5 separate per-tree property chases /
+ * function calls in the encode loop with a single property load.
+ */
+export const $encodeDescriptor = "~__encodeDescriptor";
+export const $encoders = "~encoders";
 export const $numFields = "~__numFields";
 export const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
 export const $viewFieldIndexes = "~__viewFieldIndexes";
-export const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
+export const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
+export const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
+export const $transientFieldIndexes = "~__transientFieldIndexes";
+export const $staticFieldIndexes = "~__staticFieldIndexes";
+export const $streamFieldIndexes = "~__streamFieldIndexes";
+export const $streamPriorities = "~__streamPriorities";

package/src/utils.ts

@@ -35,15 +35,13 @@ export function dumpChanges(schema: Schema) {
             continue;
         }
 
-        const changes = changeTree.indexedOperations;
-
         dump.refs.push(`refId#${changeTree.ref[$refId]}`);
-        for (const index in changes) {
-            const op = changes[index];
+        changeTree.forEach((index, op) => {
+            if (index < 0 || !op) return;
             const opName = OPERATION[op];
             if (!dump.ops[opName as keyof ChangeDump['ops']]) { dump.ops[opName as keyof ChangeDump['ops']] = 0; }
-            dump.ops[OPERATION[op] as keyof ChangeDump['ops']]++;
-        }
+            dump.ops[opName as keyof ChangeDump['ops']]++;
+        });
         current = current.next;
     }