@colyseus/schema 5.0.5 → 5.0.8

package/build/codegen/types.d.ts

@@ -9,7 +9,6 @@ export declare class Context {
         enums: Enum[];
     };
     addStructure(structure: IStructure): void;
-    private getParentClass;
     private isSchemaClass;
 }
 export interface IStructure {

package/build/decoder/Decoder.d.ts

@@ -11,9 +11,37 @@ export declare class Decoder<T extends IRef = any> {
     root: ReferenceTracker;
     currentRefId: number;
     triggerChanges?: (allChanges: DataChange[]) => void;
+    /**
+     * @internal Non-null only while a `decodeResync()` walk is in progress:
+     * collection refId → entry identities the payload visited (map string
+     * keys; array/set/collection/stream indexes). Written by the collection
+     * DecodeOperation functions, read by the post-decode sweep.
+     */
+    resyncVisited: Map<number, Set<number | string>> | null;
+    /**
+     * @internal Set when a structure had to be skipped during a resync
+     * decode — visited data is incomplete, so the sweep must not delete.
+     */
+    resyncDamaged: boolean;
     constructor(root: T, context?: TypeContext);
     protected setState(root: T): void;
     decode(bytes: Uint8Array, it?: Iterator, ref?: IRef): DataChange<any, string>[];
+    /**
+     * Full-snapshot reconciliation ("resync") decode.
+     *
+     * Behaves exactly like {@link decode}, plus: every collection entry the
+     * payload does NOT mention is removed through the regular DELETE path —
+     * `onRemove` callbacks fire with the real previous value and released
+     * refs are garbage-collected. Use it to apply a rejoin/reconnect full
+     * state over an existing decoded tree: DELETEs that happened while the
+     * client was off the wire are reconciled as if they had been received,
+     * while surviving entries keep their instance identity and callbacks.
+     *
+     * ONLY valid for full-snapshot payloads (`encodeAll` / `encodeAllView`
+     * output). Calling it on an incremental patch would prune everything
+     * the patch doesn't touch.
+     */
+    decodeResync(bytes: Uint8Array, it?: Iterator): DataChange<any, string>[];
     skipCurrentStructure(bytes: Uint8Array, it: Iterator, totalBytes: number): void;
     getInstanceType(bytes: Uint8Array, it: Iterator, defaultType: typeof Schema): typeof Schema;
     createInstanceOfType(type: typeof Schema): Schema;

package/build/decoder/Resync.d.ts

@@ -0,0 +1,61 @@
+import { OPERATION } from "../encoding/spec.js";
+import type { Decoder } from "./Decoder.js";
+import type { DataChange } from "./DecodeOperation.js";
+/**
+ * Resync ("full-snapshot reconciliation") support for {@link Decoder.decodeResync}.
+ *
+ * A rejoin snapshot is authoritative for everything it contains — but the
+ * plain decode path is additive: entries deleted (or hidden by a view)
+ * while the client was off the wire survive as ghosts. This module owns the
+ * generic reconciliation algorithm:
+ *
+ * - during the decode walk, the collection DecodeOperation functions report
+ *   every entry the payload touches ({@link resyncRecordVisit}) and every
+ *   collection that appears at all ({@link resyncMarkPresent});
+ * - after the walk, {@link resyncSweep} removes whatever was never reported,
+ *   through the same DELETE bookkeeping the regular decode path uses
+ *   (DataChange DELETE → onRemove; removeRef → GC).
+ *
+ * Storage-specific pruning (journal upkeep, array compaction, stream
+ * exemption) lives on each collection class as `[$resyncPrune]` — declared
+ * on the `Collection` interface, so every collection kind must state its
+ * own sweep semantics.
+ *
+ * All entry points are guarded by `decoder.resyncVisited !== null` at the
+ * call sites — the normal decode path never pays for any of this.
+ */
+/**
+ * Record that the current structure's entry at `identity` (map string key /
+ * element index) appeared in the payload — even when its value is unchanged
+ * (`allChanges` cannot serve as this record: its pushes are guarded by
+ * `previousValue !== value`, so unchanged entries would look unvisited).
+ *
+ * Also releases a replaced occupant: full-sync emits plain ADD (never
+ * DELETE_AND_ADD), so an entry whose instance changed while this client was
+ * off the wire would otherwise leak its previous ref (no onRemove, never
+ * GC'd). This release is correct ONLY under a full snapshot — a live patch's
+ * plain ADD over a different instance can be a positional rewrite (array
+ * shift/unshift) where the occupant *moved* and is still alive; a snapshot
+ * re-adds moved instances elsewhere, so the refcounts balance.
+ */
+export declare function resyncTouchEntry(decoder: Decoder, ref: any, operation: OPERATION, identity: number | string, previousValue: any, value: any, allChanges: DataChange[] | null): void;
+/**
+ * Mark a collection as present in the payload — even with zero entries.
+ * The sweep only prunes collections reported here: absence means "not part
+ * of full-sync" (@transient, view-invisible), where pruning would destroy
+ * live data. Reflected clients have no @transient metadata, so payload
+ * presence is the only reliable signal.
+ */
+export declare function resyncMarkPresent(decoder: Decoder, refId: number): void;
+/**
+ * Post-decode phase of {@link Decoder.decodeResync}: remove every collection
+ * entry the snapshot did not visit.
+ *
+ * Walks the tree from the root — NOT `root.refs` — for three reasons:
+ * `@transient` fields are never part of a snapshot and must be left alone;
+ * entries of subtrees removed by the sweep itself are left to the GC's
+ * transitive walk (sweeping them directly would double-decrement shared
+ * children); and collections the snapshot never mentions (emptied
+ * server-side) are still reachable and get pruned.
+ */
+export declare function resyncSweep(decoder: Decoder, allChanges: DataChange[] | null): void;

package/build/encoder/ChangeTree.d.ts

@@ -61,6 +61,7 @@ export interface ParentChain {
 export declare const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
 export declare const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
 export declare const IS_STREAM_COLLECTION = 64;
+export declare const NEEDS_RESTAGE = 128;
 /**
  * Flags a child inherits from its parent's own transitive state via
  * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
@@ -154,6 +155,8 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     set isStatic(v: boolean);
     get isStreamCollection(): boolean;
     set isStreamCollection(v: boolean);
+    get needsRestage(): boolean;
+    set needsRestage(v: boolean);
     get hasFilteredFields(): boolean;
     ensureUnreliableRecorder(): ChangeRecorder;
     isFieldUnreliable(index: number): boolean;
@@ -174,6 +177,18 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     size(): number;
     has(): boolean;
     reset(): void;
+    /**
+     * Full reset to construction defaults so the owning ref can be returned to
+     * a pool and reused for a different logical entity (see encoder/Pool.ts +
+     * Schema.reset). Unlike `reset()` / `endEncode()` (which only clear the
+     * dirty bucket for the next encode), this also drops parent links, queue
+     * nodes and per-view bitmaps, and re-arms IS_NEW.
+     *
+     * Precondition: the tree must already be detached from the encoder
+     * (`root === undefined`) — i.e. the ref was removed from its parent
+     * collection/field, which `Root.remove` does before this runs.
+     */
+    recycle(): void;
     shift(shiftIndex: number): void;
     setRoot(root: Root): void;
     setParent(parent: Ref, root?: Root, parentIndex?: number): void;

package/build/encoder/Encoder.d.ts

@@ -4,6 +4,17 @@ import type { Iterator } from "../encoding/decode.js";
 import { Root } from "./Root.js";
 import type { StateView } from "./StateView.js";
 export declare class Encoder<T extends Schema = any> {
+    /**
+     * Per-encoder shared output buffer size. The encoder auto-grows on
+     * overflow and logs a one-time warning suggesting a higher value, so
+     * the default just needs to comfortably cover typical room state.
+     *
+     * Sized to fit ~100 items in a `MapSchema<{x,y,z}>` keyed by
+     * `nanoid(9)` (~4.5 KB worst-case full encode, float64-heavy) with
+     * ~3-4× headroom for surrounding state (player list, world refs,
+     * etc.). Raise per app via `Encoder.BUFFER_SIZE = N * 1024` before
+     * constructing any Encoder.
+     */
     static BUFFER_SIZE: number;
     sharedBuffer: Uint8Array;
     context: TypeContext;
@@ -38,6 +49,8 @@ export declare class Encoder<T extends Schema = any> {
     private _resizeBuffer;
     encodeAll(it?: Iterator, buffer?: Uint8Array): Uint8Array<ArrayBufferLike>;
     encodeAllView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
+    /** Grow `buffer` to keep BUFFER_SIZE free bytes past `offset`, preserving `[0, offset)`. */
+    protected ensureCapacity(buffer: Uint8Array, offset: number): Uint8Array;
     encodeView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
     /**
      * Per-view unreliable encode. Walks `root.unreliableChanges` and emits

package/build/encoder/Pool.d.ts

@@ -0,0 +1,62 @@
+import { Schema } from "../Schema.js";
+/**
+ * Server-side object pool for Schema instances.
+ *
+ * Constructing a Schema is comparatively expensive (per-instance ChangeTree +
+ * `Object.defineProperty($changes)` + values array, multiplied by the number
+ * of instances in the entity tree). For workloads that spawn/despawn entities
+ * (ECS, matchmaking bots, projectiles), reusing instances avoids that cost.
+ *
+ * The pool relies on {@link Schema.reset} to return a detached instance to a
+ * pristine, construction-default state — including dropping its `$refId` so a
+ * re-add re-acquires a fresh id (making reuse wire-format-identical to `new`).
+ *
+ * Lifecycle:
+ * ```ts
+ * const pool = createPool(Entity, { preallocate: 1000 });
+ *
+ * // spawn
+ * const e = pool.acquire();
+ * e.x = 10; e.y = 20;            // re-assign fields (pool does NOT reset primitives)
+ * state.entities.set(id, e);
+ *
+ * // despawn — remove from the state tree FIRST, then release
+ * state.entities.delete(id);
+ * pool.release(e);
+ * ```
+ *
+ * Not supported (throws on release): instances shared across multiple parents,
+ * `@stream` collections, and decoder-side (mirror) instances.
+ */
+export interface PoolOptions {
+    /** Construct this many instances up front, so the first spawns reuse rather than allocate. */
+    preallocate?: number;
+    /**
+     * Cap on retained free instances. Releases beyond the cap are dropped (and
+     * garbage-collected), keeping a long-running pool bounded. Default: no cap.
+     */
+    maxSize?: number;
+}
+/**
+ * Object pool for Schema instances. Exported as a **type only** — construct one
+ * via {@link createPool}, which is the public entry point. The class is public
+ * for typing (`SchemaPool<Entity>` annotations) and `instanceof` checks.
+ */
+export declare class SchemaPool<T extends Schema> {
+    private readonly _free;
+    private readonly _factory;
+    private readonly _maxSize;
+    constructor(factory: () => T, opts?: PoolOptions);
+    /** Pop a pre-reset free instance, or construct a fresh one. */
+    acquire(): T;
+    /**
+     * Reset `instance` to construction defaults and return it to the pool.
+     * PRECONDITION: the instance must already be detached from the state tree
+     * (removed from its parent collection/field, so the encoder released it).
+     */
+    release(instance: T): void;
+    /** Number of instances currently available for reuse. */
+    get size(): number;
+}
+/** Convenience factory: `createPool(Entity, { preallocate: 64 })`. */
+export declare function createPool<T extends Schema>(ctor: new () => T, opts?: PoolOptions): SchemaPool<T>;

package/build/encoder/Root.d.ts

@@ -1,7 +1,6 @@
 import { TypeContext } from "../types/TypeContext.js";
 import { ChangeTree, ChangeTreeList, type ChangeTreeNode } from "./ChangeTree.js";
 import { $changes, $refId } from "../types/symbols.js";
-import { RefIdAllocator } from "./RefIdAllocator.js";
 import type { StateView } from "./StateView.js";
 import type { StreamableState } from "./streaming.js";
 /**
@@ -22,10 +21,12 @@ export interface Streamable {
 export declare class Root {
     types: TypeContext;
     /**
-     * Allocates and recycles refIds. See `RefIdAllocator` for the reuse
-     * pool semantics (one-tick defer + resurrection).
+     * Monotonic refId counter. RefIds are never recycled — a refId is a
+     * stable identity for the lifetime of the room, so a client that
+     * missed DELETEs (reconnect) can never see an old id rebound to a
+     * different instance. DevMode reads/writes this across HMR cycles.
      */
-    readonly refIds: RefIdAllocator;
+    protected nextUniqueId: number;
     refCount: {
         [id: number]: number;
     };

package/build/encoder/StateView.d.ts

@@ -70,11 +70,20 @@ export declare class StateView {
     markInvisible(tree: ChangeTree): void;
     /** Clear invisible bit. */
     unmarkInvisible(tree: ChangeTree): void;
-    /** True iff this view has `tag` associated with `tree`. */
+    /**
+     * True iff this view shares at least one tag bit with `tree`.
+     *
+     * `tagViews` is keyed by individual power-of-two bits (custom tags must
+     * be powers of two; `@view(A|B)` field masks are decomposed on store).
+     * A field whose mask is `tag` is visible if the view was `add()`ed with
+     * any overlapping bit — so we walk `tag`'s set bits and return on the
+     * first match. Passing DEFAULT_VIEW_TAG (-1, all bits) answers "does
+     * this view hold ANY custom tag on the tree".
+     */
     hasTagOnTree(tree: ChangeTree, tag: number): boolean;
-    /** Mark `tree` as carrying `tag` for this view. */
+    /** Mark `tree` as carrying `tag` (each of its bits) for this view. */
     addTag(tree: ChangeTree, tag: number): void;
-    /** Clear this view's `tag` bit on `tree`. */
+    /** Clear each of `tag`'s bits for this view on `tree`. */
     removeTag(tree: ChangeTree, tag: number): void;
     /** Clear ALL tag bits this view holds on `tree` (used when the per-tag isn't known). */
     removeAllTagsOnTree(tree: ChangeTree): void;