@colyseus/schema 5.0.14 → 5.0.19

package/build/codegen/parser.d.ts

@@ -1,6 +1,11 @@
 import * as ts from "typescript";
 import { Class, Interface, Context, Enum } from "./types.js";
-export declare function parseFiles(fileNames: string[], decoratorName?: string, context?: Context): {
+import { ResolveOptions } from "./resolve.js";
+/**
+ * `options` is only honored for a top-level call (one passing a fresh
+ * `Context`) — the recursive import walk reuses the run's resolver state.
+ */
+export declare function parseFiles(fileNames: string[], decoratorName?: string, context?: Context, options?: ResolveOptions): {
     classes: Class[];
     interfaces: Interface[];
     enums: Enum[];

package/build/codegen/resolve.d.ts

@@ -0,0 +1,25 @@
+export interface ResolveOptions {
+    /** Explicit `--tsconfig`. When set, nearest-config discovery is skipped. */
+    tsconfig?: string;
+}
+/**
+ * Drop every cached tsconfig lookup. Called once per top-level `parseFiles()`
+ * run so a long-lived process can generate for two different projects.
+ */
+export declare function resetResolver(options?: ResolveOptions): void;
+/**
+ * Resolve a non-relative import (`@schemas/Player`, `shared/Player`) to a
+ * first-party source file through the tsconfig governing `containingFile`.
+ * Returns undefined for npm packages, declaration files, and specifiers no
+ * alias covers.
+ */
+export declare function resolveNonRelativeImport(specifier: string, containingFile: string): string | undefined;
+/** The extension alternatives parseFiles() probes, in order. Pure — no fs. */
+export declare function sourceFileCandidates(fileName: string): string[];
+/** Same probing as parseFiles(), answering "which candidate exists?". */
+export declare function resolveSourceFile(fileName: string): string | undefined;
+/**
+ * The serializer's own source declares wire-internal schemas (`Reflection`,
+ * `ReflectionField`, …) that must never reach generated client code.
+ */
+export declare function isOwnPackageSource(fileName: string): boolean;

package/build/codegen/types.d.ts

@@ -1,3 +1,5 @@
+/** Root of the @colyseus/schema package — `src/codegen/` in dev, `build/codegen/` once bundled. */
+export declare const PACKAGE_ROOT: string;
 export declare function getCommentHeader(singleLineComment?: string): string;
 export declare class Context {
     classes: Class[];

package/build/encoder/ChangeTree.d.ts

@@ -54,15 +54,30 @@ export interface ChangeTreeList {
     nextPosition: number;
 }
 export declare function createChangeTreeList(): ChangeTreeList;
+/**
+ * Live node in a tree's parent chain — mutating one edits the chain. Only
+ * `parentChain.ts` should hold these.
+ */
 export interface ParentChain {
     ref: Ref;
     index: number;
     next?: ParentChain;
 }
+/**
+ * Detached copy of one parent link, handed out by the query helpers. Distinct
+ * from `ParentChain` on purpose: it carries no `next`, so it cannot be walked
+ * as if it were the chain, and it is readonly, so it cannot be mistaken for a
+ * way to move a parent's index — `setParentIndex` does that.
+ */
+export interface ParentEntry {
+    readonly ref: Ref;
+    readonly index: number;
+}
 export declare const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
 export declare const IS_UNRELIABLE = 8, IS_PATCH_ONLY = 16, IS_FULL_STATE_ONLY = 32;
 export declare const IS_STREAM_COLLECTION = 64;
 export declare const NEEDS_RESTAGE = 128;
+export declare const PENDING_FILTER_REFRESH = 256;
 /**
  * Flags a child inherits from its parent's own transitive state via
  * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
@@ -94,6 +109,13 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      * facing identity (debug output, callback parents) keep using `ref`.
      */
     refTarget: T;
+    /**
+     * True when `ref` is an ArraySchema — the only proxied type, so its
+     * user-facing identity differs from `refTarget`. Canonical predicate for
+     * "is this tree's ref an array" without probing `ref` (which would hit
+     * the Proxy trap) — two monomorphic loads on the tree itself.
+     */
+    get isArray(): boolean;
     metadata: Metadata;
     /**
      * Per-class cache of encoder fn / filter fn / isSchema / metadata /
@@ -162,7 +184,7 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     isFieldUnreliable(index: number): boolean;
     isFieldFullStateOnly(index: number): boolean;
     isFieldStream(index: number): boolean;
-    constructor(ref: T);
+    constructor(ref: T, refTarget?: T);
     private _opAt;
     private _opPut;
     private _markDirty;
@@ -190,14 +212,21 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
      */
     recycle(): void;
     /**
-     * ArraySchema#unshift(): re-key pending ops on both channels by
-     * `+count`, then record ADDs for the new items at indexes 0..count-1.
+     * ArraySchema insert (unshift / splice with more inserts than deletes):
+     * re-key pending ops at or above `at` by `+count`, then record ADDs for
+     * the new items at indexes `at..at+count-1`.
      *
-     * The rebuilt map's insertion order IS the wire order: new ADDs first
-     * (ascending — the decoder splice-inserts each one, which only works
-     * lowest-index-first), then prior ops in their original relative order
-     * at their shifted positions. See ArraySchema#$setAt.
+     * The rebuilt map's insertion order IS the wire order:
+     *   1. ops below `at` — the insert doesn't move them, and an insert of
+     *      their own must still be applied before this one (ascending);
+     *   2. the new ADDs, ascending — the decoder splice-inserts each one,
+     *      which only works lowest-index-first;
+     *   3. the re-keyed ops, in their original relative order — their
+     *      indexes now address the post-insert layout.
+     * See ArraySchema#$setAt.
      */
+    insertAt(at: number, count: number): void;
+    /** ArraySchema#unshift(): insert `count` items at the head. */
     unshift(count: number): void;
     setRoot(root: Root): void;
     setParent(parent: Ref, root?: Root, parentIndex?: number): void;
@@ -255,12 +284,11 @@ export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     setParentIndex(parent: Ref, index: number): void;
     /** @returns true if parent was found and removed */
     removeParent(parent?: Ref): boolean;
-    findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined;
+    findParent(predicate: (parent: Ref, index: number) => boolean): ParentEntry | undefined;
     hasParent(predicate: (parent: Ref, index: number) => boolean): boolean;
-    getAllParents(): Array<{
-        ref: Ref;
-        index: number;
-    }>;
+    /** Wire index this tree holds inside `parent`, or undefined if not a parent. */
+    indexInParent(parent: Ref): number | undefined;
+    getAllParents(): ParentEntry[];
 }
 /**
  * Lightweight per-instance no-op ChangeTree used for instances the decoder

package/build/encoder/Encoder.d.ts

@@ -2,7 +2,7 @@ import type { Schema } from "../Schema.js";
 import { TypeContext } from "../types/TypeContext.js";
 import type { Iterator } from "../encoding/decode.js";
 import { Root } from "./Root.js";
-import type { StateView } from "./StateView.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

package/build/encoder/Root.d.ts

@@ -46,6 +46,15 @@ export declare class Root {
      * fields dirty at the same time.
      */
     unreliableChanges: ChangeTreeList;
+    /**
+     * Trees whose parent-edge set changed this tick (instance sharing
+     * gained or lost an edge). The encoder drains this before emission —
+     * `inheritedFlags.drainFilterRefresh` re-derives each tree's filter
+     * state against the then-settled containers. Only populated when the
+     * TypeContext has any @view/@stream field.
+     */
+    pendingFilterRefresh: ChangeTree[];
+    enqueueFilterRefresh(tree: ChangeTree): void;
     /**
      * Free-list of ChangeTreeNode objects. Both queues share this pool —
      * a node carries no queue affinity, only `{ changeTree, prev, next, position }`.

package/build/encoder/StateView.d.ts

@@ -5,6 +5,21 @@ import type { MapSchema } from "../types/custom/MapSchema.js";
 import type { SetSchema } from "../types/custom/SetSchema.js";
 import type { CollectionSchema } from "../types/custom/CollectionSchema.js";
 export declare function createView(iterable?: boolean): StateView;
+/**
+ * Compact description of a rejected argument, for warning messages.
+ * Passing the value itself to `console.warn` is not an option — a
+ * populated collection inspects into dozens of lines of encoder
+ * internals and buries the message that matters.
+ */
+/**
+ * Sentinel inner-map key: "snapshot every live element of this ref-typed
+ * ArraySchema". Written by `_add`'s bulk path instead of one entry per
+ * element; `encodeView` expands it structurally at drain time, so the
+ * emitted slots reflect any reindex that happened after `view.add()` —
+ * and a whole-array snapshot costs one Map insert instead of N.
+ * Real slots are never negative, so -1 cannot collide.
+ */
+export declare const ARRAY_SNAPSHOT = -1;
 export declare class StateView {
     iterable: boolean;
     /**
@@ -36,8 +51,16 @@ export declare class StateView {
      * Inner storage is a Map so the encode loop in `encodeView` can iterate
      * directly with numeric keys — the legacy `{[index]: OPERATION}` shape
      * forced an `Object.keys(...)` allocation + `Number(key)` parse per ref.
+     *
+     * Inner keys are numbers (Schema field indexes, MapSchema journal
+     * indexes, Set/Collection indexes, stream positions — all stable within
+     * a tick), EXCEPT element bindings under a ref-typed ArraySchema parent,
+     * which are keyed by the child's ChangeTree. An array wire slot captured
+     * at `view.add()` time goes stale if the array reindexes (unshift /
+     * reverse / move) later in the same tick — identity keys let
+     * `encodeView` resolve the CURRENT slot at drain time instead.
      */
-    changes: Map<number, Map<number, OPERATION>>;
+    changes: Map<number, Map<number | ChangeTree<any>, OPERATION>>;
     constructor(iterable?: boolean);
     /**
      * Lazily bind this view to a Root and acquire a view ID. Called on
@@ -183,4 +206,18 @@ export declare class StateView {
     clear(): void;
     isChangeTreeVisible(changeTree: ChangeTree): boolean;
     protected _recursiveDeleteVisibleChangeTree(changeTree: ChangeTree): void;
+    /**
+     * Drop the pending `view.changes` entries of `tree` and every descendant.
+     * Called when a same-patch pending ADD is cancelled: the subtree's
+     * introduction never reaches this client, so its entries would emit
+     * refIds the decoder cannot resolve ("refId" not found).
+     */
+    private _dropPendingEntries;
+    /**
+     * Queue DELETE for a @view field on `changes` and hide the field
+     * value's subtree from this view. When the field's ADD is still
+     * pending (same-patch add + remove), the value's introduction never
+     * ships — its pending subtree entries are dropped along with it.
+     */
+    private _removeViewField;
 }

package/build/encoder/changeTree/inheritedFlags.d.ts

@@ -1,4 +1,5 @@
 import { type ChangeTree, type Ref } from "../ChangeTree.js";
+import type { Root } from "../Root.js";
 /**
  * Reconcile queue membership + inherited flags for a tree that just had
  * its root/parent assigned. See `_checkInheritedFlags` for the flag
@@ -11,24 +12,17 @@ export declare function checkIsFiltered(tree: ChangeTree, parent: Ref, parentInd
  * etc.) inherit these from the Schema field that holds them.
  *
  * The common case — fresh tree attached to a parent field that carries
- * none of the inheritable annotations — produces no flag change, no
- * queue update, and no `parentFiltered` hit. Two small structural
- * choices keep that case cheap without any precomputed descriptor
- * bitmask:
- *
- *  1) Flag inheritance is a single bitwise OR onto `tree.flags`. The
- *     three per-annotation reads pack into `fieldBits`, the parent's
- *     inherited bits come from `parentChangeTree.flags` directly; one
- *     read-modify-write replaces three getter/setter cycles, and the
- *     bit diff against `beforeFlags` gives us the "just became static /
- *     unreliable" signal for the side-effect branches.
- *
- *  2) The `parentFiltered` string-key lookup is gated on
- *     `types.hasParentFilteredEntries`, which is only flipped true when
- *     `registerFilteredByParent` actually records an entry — i.e. when
- *     some @view-tagged field reaches this (child, parent, index)
- *     triple through the ancestry walk. Schemas with @view tags only on
- *     sibling fields (not along any attachment chain) skip the string
- *     concat + hash lookup entirely.
+ * none of the inheritable annotations — produces no flag change and no
+ * queue update. Flag inheritance is a single bitwise OR onto
+ * `tree.flags`: the per-annotation reads pack into `fieldBits`, the
+ * parent's inherited bits come from `parentChangeTree.flags` directly,
+ * and one read-modify-write replaces three getter/setter cycles. The bit
+ * diff against `beforeFlags` gives the "just became static / unreliable"
+ * signal for the side-effect branches.
  */
 export declare function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex: number): void;
+/**
+ * Drain `root.pendingFilterRefresh`. Called by the encoder before any
+ * emission (per-tick channels and full-sync).
+ */
+export declare function drainFilterRefresh(root: Root): void;

package/build/encoder/changeTree/liveIteration.d.ts

@@ -1,3 +1,11 @@
 import type { ChangeTree } from "../ChangeTree.js";
+/**
+ * Re-stage one live index as a fresh ADD on its channel. Shared by
+ * `Root.add` (refCount-0 / NEEDS_RESTAGE re-adds) and
+ * `inheritedFlags.refreshFilterState` (filtered→public flip) via
+ * `forEachLiveWithCtx(tree, restageLiveCb)` — one home for the
+ * unreliable-routing rule.
+ */
+export declare const restageLiveCb: (tree: ChangeTree, fieldIndex: number) => void;
 export declare function forEachLive(tree: ChangeTree, callback: (index: number) => void): void;
 export declare function forEachLiveWithCtx<C>(tree: ChangeTree, ctx: C, cb: (ctx: C, index: number) => void): void;

package/build/encoder/changeTree/parentChain.d.ts

@@ -1,4 +1,4 @@
-import type { ChangeTree, ParentChain, Ref } from "../ChangeTree.js";
+import type { ChangeTree, ParentEntry, Ref } from "../ChangeTree.js";
 /**
  * Add a parent to the chain. If `parent` already exists anywhere in the
  * chain, update the primary parent's index instead (matches legacy
@@ -20,14 +20,36 @@ export declare function setParentIndex(tree: ChangeTree, parent: Ref, index: num
  */
 export declare function removeParent(tree: ChangeTree, parent: Ref): boolean;
 /**
- * Find the first parent in the chain matching `predicate`.
+ * First parent matching `predicate`, as a detached `ParentEntry`. Never returns
+ * a live `ParentChain` node — the inline parent has no node to return in the
+ * first place, so handing out the real node for the `extraParents` case only
+ * would make writes land or vanish depending on which parent matched. Use
+ * `setParentIndex` to move an index and `indexInParent` to read one.
  */
-export declare function findParent(tree: ChangeTree, predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined;
+export declare function findParent(tree: ChangeTree, predicate: (parent: Ref, index: number) => boolean): ParentEntry | undefined;
+/** Walks in place — `addParent` calls this per shared-instance attach. */
 export declare function hasParent(tree: ChangeTree, predicate: (parent: Ref, index: number) => boolean): boolean;
 /**
- * Return all parents as an array (debug/test helper).
+ * Wire index `tree` holds inside `parent`, or undefined when `parent` is
+ * nowhere in the chain. Allocation-free variant of `findParent` for the
+ * encodeView drain, which resolves identity-keyed view entries per emission.
+ *
+ * A child detached from `parent` this tick usually still resolves: Root.remove
+ * leaves the child's own parent link dangling, and the staged snapshot keeps
+ * the child in `tmpItems` (so reindexes keep the index current) until
+ * `$onEncodeEnd` — which runs after the drain.
+ */
+export declare function indexInParent(tree: ChangeTree, parent: Ref): number | undefined;
+/**
+ * Return all parents as detached entries (debug/test helper).
+ */
+export declare function getAllParents(tree: ChangeTree): ParentEntry[];
+/**
+ * True iff `parent` currently holds `tree`. Detached edges linger in the
+ * parent chain (load-bearing for same-tick view drains — see
+ * `indexInParent` above), so the chain alone cannot answer which edges
+ * are live. ArraySchema is probed by scanning `items`: the recorded slot
+ * can go stale after reorders, and `items` — unlike `$getByIndex`'s staged
+ * view — reflects the tick's completed mutations.
  */
-export declare function getAllParents(tree: ChangeTree): Array<{
-    ref: Ref;
-    index: number;
-}>;
+export declare function isEdgeLive(tree: ChangeTree, parentTree: ChangeTree, index: number): boolean;

package/build/encoder/streaming.d.ts

@@ -72,7 +72,7 @@ export declare function streamEnqueueForView(s: Streamable, viewId: number, inde
  * `view.changes`; false if it was only pending (silent drop) or not
  * present at all.
  */
-export declare function streamDequeueForView(s: Streamable, viewId: number, refId: number, index: number, viewChanges: Map<number, Map<number, number>>): boolean;
+export declare function streamDequeueForView(s: Streamable, viewId: number, refId: number, index: number, viewChanges: Map<number, Map<number | object, number>>): boolean;
 /**
  * Drop all per-view state for a disposing/GC'd StateView. Keeps memory
  * bounded in long-running rooms with client churn.