@colyseus/schema 4.0.20 → 5.0.0

package/src/encoder/changeTree/inheritedFlags.ts

@@ -0,0 +1,217 @@
+/**
+ * Filter / unreliable / transient / static inheritance helpers for
+ * ChangeTree. Called by setRoot / setParent to derive child flags from
+ * the parent field's annotation + the parent tree's own state.
+ */
+import { Metadata } from "../../Metadata.js";
+import {
+    $changes, $childType,
+    $staticFieldIndexes, $streamFieldIndexes,
+    $transientFieldIndexes, $viewFieldIndexes,
+    // $unreliableFieldIndexes — tree-level unreliable currently disabled
+    // (see INHERITABLE_FLAGS comment in ChangeTree.ts). Per-field unreliable
+    // routing on primitive fields still uses it via `isFieldUnreliable()`.
+} from "../../types/symbols.js";
+import type { Schema } from "../../Schema.js";
+import {
+    INHERITABLE_FLAGS, IS_STATIC, IS_TRANSIENT,
+    // IS_UNRELIABLE — tree-level unreliable currently disabled; see
+    // INHERITABLE_FLAGS comment in ChangeTree.ts.
+    type ChangeTree, type Ref,
+} from "../ChangeTree.js";
+import type { ICollectionChangeRecorder } from "../ChangeRecorder.js";
+import type { Streamable } from "../Root.js";
+import { ensureStreamState } from "../streaming.js";
+
+/**
+ * Reconcile queue membership + inherited flags for a tree that just had
+ * its root/parent assigned. See `_checkInheritedFlags` for the flag
+ * inheritance logic.
+ */
+export function checkIsFiltered(
+    tree: ChangeTree,
+    parent: Ref,
+    parentIndex: number,
+    _isNewChangeTree: boolean,
+): void {
+    checkInheritedFlags(tree, parent, parentIndex);
+
+    // Static trees never track per-tick changes — skip the queue entirely.
+    // Full-sync reaches them via structural walk (forEachChild).
+    if (tree.isStatic) return;
+
+    // Mutations that happened before setRoot (e.g. class-field initializers)
+    // recorded into the appropriate recorder but couldn't enqueue yet.
+    // Reconcile both queues now.
+    if (tree.has()) {
+        tree.root?.enqueueChangeTree(tree);
+    }
+    if (tree.unreliableRecorder?.has()) {
+        tree.root?.enqueueUnreliable(tree);
+    }
+    // Fresh tree with nothing recorded: still enqueue into its primary
+    // queue so the tree is reachable for its first mutation cycle.
+    //
+    // Tree-level unreliable is disabled (see INHERITABLE_FLAGS) so the
+    // unreliable branch is unreachable today. Kept as a comment for
+    // re-enablement.
+    if (!tree.has() && !(tree.unreliableRecorder?.has())) {
+        // if (tree.isUnreliable) {
+        //     tree.root?.enqueueUnreliable(tree);
+        // } else {
+            tree.root?.enqueueChangeTree(tree);
+        // }
+    }
+}
+
+/**
+ * Inherit filter / unreliable / transient / static classification from
+ * the parent field's annotation. Collections (MapSchema / ArraySchema /
+ * 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.
+ */
+export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex: number): void {
+    if (!parent) { return; }
+
+    // Walk up a collection level so `parent` lands on the Schema that
+    // owns the field at `parentIndex`. Field annotations live on Schema
+    // metadata; collections have none.
+    let parentChangeTree: ChangeTree = parent[$changes];
+    const parentIsCollection = !Metadata.isValidInstance(parent);
+    if (parentIsCollection) {
+        parent = parentChangeTree.parent;
+        parentIndex = parentChangeTree.parentIndex;
+    }
+
+    const parentMetadata: any = (parent as any)?.constructor?.[Symbol.metadata];
+
+    // Flag inheritance — pack the transient/static annotation checks into
+    // flag bits alongside the parent's own transitive flags, then OR onto
+    // `tree.flags` in one write. The bit diff tells us which flag just
+    // went from 0→1, cheaper than the prior `becameX = !tree.isX && (...)`
+    // pairs. IS_UNRELIABLE is omitted from both sides — tree-level
+    // unreliable is disabled (see INHERITABLE_FLAGS in ChangeTree.ts).
+    const fieldBits =
+        (parentMetadata?.[$transientFieldIndexes]?.includes(parentIndex) ? IS_TRANSIENT : 0)
+        | (parentMetadata?.[$staticFieldIndexes]?.includes(parentIndex) ? IS_STATIC : 0);
+    const inheritedBits = (parentChangeTree.flags & INHERITABLE_FLAGS) | fieldBits;
+    const beforeFlags = tree.flags;
+    tree.flags = beforeFlags | inheritedBits;
+    const gainedBits = inheritedBits & ~beforeFlags;
+
+    // If this tree just became static via inheritance, discard any entries
+    // that may have been recorded before the parent was assigned (e.g.
+    // `new Config().assign({...})` populates the recorder before the
+    // Config instance is attached). Static trees ship state via structural
+    // walk only; per-tick dirty entries would leak post-first-sync.
+    if (gainedBits & IS_STATIC) {
+        tree.reset();
+        tree.unreliableRecorder?.reset();
+    }
+    // Tree-level unreliable promotion is disabled — no tree can gain
+    // IS_UNRELIABLE via inheritance under the current decoration-time
+    // rejection (`Metadata.setUnreliable` on ref-type fields throws). The
+    // promotion block used to migrate reliable-recorder entries populated
+    // before attach (`new Item().assign({...})` then push into an
+    // unreliable collection) over to the unreliable recorder. Kept here
+    // as a comment for re-enablement if a safe tree-level unreliable
+    // semantics is designed later.
+    //
+    // else if ((gainedBits & IS_UNRELIABLE) && tree.has()) {
+    //     const dst = tree.ensureUnreliableRecorder() as ICollectionChangeRecorder;
+    //     tree.forEach((index, op) => {
+    //         if (index < 0) dst.recordPure(op);
+    //         else dst.record(index, op);
+    //     });
+    //     tree.reset();
+    // }
+
+    // Filter inheritance — only when the type context has any @view or
+    // @stream fields registered anywhere.
+    const types = tree.root?.types;
+    if (!types?.hasFilters) return;
+
+    const fieldHasViewTag = parentMetadata?.[$viewFieldIndexes]?.includes(parentIndex) ?? false;
+    // Stream fields are always view-scoped: the stream itself and its
+    // child elements must behave as filtered trees. Elements must NOT
+    // share visibility with the parent stream — `encodeView`'s priority
+    // pass is the only way elements become visible to a view.
+    const fieldHasStream = parentMetadata?.[$streamFieldIndexes]?.includes(parentIndex) ?? false;
+
+    // Skip the `parentFiltered` string-key lookup when no class has
+    // actually registered filter inheritance via ancestry. The lookup
+    // cannot hit in that state, so the string concat + hash lookup would
+    // be wasted work every attach.
+    let parentFiltered = false;
+    const parentConstructor = (parent as any)?.constructor as typeof Schema | undefined;
+    if (types.hasParentFilteredEntries && parentConstructor !== undefined) {
+        const refType = Metadata.isValidInstance(tree.ref)
+            ? tree.ref.constructor
+            : (tree.ref as any)[$childType];
+        const key = `${types.getTypeId(refType as typeof Schema)}-${types.schemas.get(parentConstructor)}-${parentIndex}`;
+        parentFiltered = types.parentFiltered[key] ?? false;
+    }
+
+    const newFiltered = parentChangeTree.isFiltered || parentFiltered || fieldHasViewTag || fieldHasStream;
+    tree.isFiltered = newFiltered;
+
+    // Flag collection trees attached to a `.stream()` field so the encoder
+    // routes their emission through the priority/broadcast pass. Applies
+    // when the tree IS the collection (not the collection's parent
+    // structure walk above). `parentIsCollection` was true at entry iff
+    // `tree.ref` is a child-of-collection (e.g. stream element) — we only
+    // set the flag on the collection itself, not its elements.
+    if (fieldHasStream && !parentIsCollection) {
+        tree.isStreamCollection = true;
+        // Allocate the lazy `_stream` slot once, here — so downstream
+        // helpers (`streamRouteAdd`, `_emitStreamPriority`, …) never need
+        // a null-check. `_stream` was always declared on the class at
+        // `undefined`, so this is a value write, not a shape transition.
+        const state = ensureStreamState(tree.ref as unknown as Streamable);
+        // Seed the priority callback from the schema declaration (builder's
+        // `.priority(fn)` or decorator's `{ stream: X, priority: fn }`).
+        // Instance-level overrides via `stream.priority = ...` win — only
+        // assign if the instance slot hasn't already been set.
+        if (state.priority === undefined) {
+            const declared = Metadata.getStreamPriority(parentMetadata, parentIndex);
+            if (declared !== undefined) state.priority = declared;
+        }
+        // Auto-register with `root.streamTrees` so the encoder's priority /
+        // broadcast pass picks it up. Covers both `StreamSchema` and any
+        // `.stream()`-opted collection (e.g. `MapSchema.stream()`).
+        tree.root?.registerStream(tree.ref as any);
+    }
+
+    if (newFiltered) {
+        const refType = Metadata.isValidInstance(tree.ref)
+            ? tree.ref.constructor
+            : (tree.ref as any)[$childType];
+        tree.isVisibilitySharedWithParent = (
+            parentChangeTree.isFiltered
+            && typeof refType !== "string"
+            && !fieldHasViewTag
+            && !fieldHasStream
+            && parentIsCollection
+        );
+    }
+}

package/src/encoder/changeTree/liveIteration.ts

@@ -0,0 +1,74 @@
+/**
+ * Walk all currently-populated non-transient indexes on a tree, emitting
+ * each index once. Used by Root.add (re-stage), Encoder.encodeAll, and
+ * StateView.add to derive full-sync output from the live structure.
+ *
+ * Transient fields (`@transient`) are skipped — they're delivered only on
+ * tick patches and not persisted to snapshots. Collections whose parent
+ * field is @transient inherit the skip (`tree.isTransient`).
+ */
+import { $childType, $numFields, $transientFieldIndexes } from "../../types/symbols.js";
+import type { ChangeTree } from "../ChangeTree.js";
+
+// Adapter that lets `forEachLive(cb)` delegate to `forEachLiveWithCtx(cb, _invokeNoCtx)` —
+// keeps the no-ctx path closure-free and shares one walker implementation.
+const _invokeNoCtx = (cb: (index: number) => void, index: number) => cb(index);
+
+export function forEachLive(tree: ChangeTree, callback: (index: number) => void): void {
+    forEachLiveWithCtx(tree, callback, _invokeNoCtx);
+}
+
+export function forEachLiveWithCtx<C>(
+    tree: ChangeTree,
+    ctx: C,
+    cb: (ctx: C, index: number) => void,
+): void {
+    // `refTarget` skips the ArraySchema Proxy on every `.items` / `.$items`
+    // / `[$childType]` read below. Same reference as `ref` for non-proxied
+    // types. See `ChangeTree.refTarget` doc.
+    const ref = tree.refTarget as any;
+
+    if (ref[$childType] !== undefined) {
+        // Collection inheriting @transient from parent field: skip entirely.
+        if (tree.isTransient) return;
+
+        // Collection types: dispatch by shape.
+        if (Array.isArray(ref.items)) {
+            // ArraySchema
+            const items = ref.items as any[];
+            for (let i = 0, len = items.length; i < len; i++) {
+                if (items[i] !== undefined) cb(ctx, i);
+            }
+        } else if (ref.journal !== undefined) {
+            // MapSchema
+            for (const [index, key] of ref.journal.keyByIndex as Map<number, any>) {
+                if (ref.$items.has(key)) cb(ctx, index);
+            }
+        } else if (ref.$items !== undefined) {
+            // SetSchema / CollectionSchema (key === wire index)
+            for (const index of (ref.$items as Map<number, any>).keys()) {
+                cb(ctx, index);
+            }
+        }
+    } else {
+        // Schema: walk declared fields. `null` is treated as absent —
+        // the setter records a DELETE when a field is set to null or
+        // undefined, so it should not appear in full-sync output.
+        //
+        // Read names from the per-class descriptor's parallel array —
+        // saves the `metadata[i]` (per-field obj) + `.name` chain on
+        // every iteration of the full-sync DFS.
+        const metadata = tree.metadata;
+        if (!metadata) return;
+        const numFields = (metadata[$numFields] ?? -1) as number;
+        const transientIndexes = metadata[$transientFieldIndexes];
+        const names = tree.encDescriptor.names;
+        for (let i = 0; i <= numFields; i++) {
+            const name = names[i];
+            if (name === undefined) continue;
+            if (transientIndexes && transientIndexes.includes(i)) continue;
+            const value = ref[name];
+            if (value !== undefined && value !== null) cb(ctx, i);
+        }
+    }
+}

package/src/encoder/changeTree/parentChain.ts

@@ -0,0 +1,131 @@
+/**
+ * Parent-chain helpers for ChangeTree. A tree can have multiple parents
+ * (rare — instance sharing between Schema/Collection containers). The
+ * primary parent is stored inline on the tree (`parentRef` / `_parentIndex`);
+ * additional parents live in the `extraParents` linked list.
+ */
+import { $changes } from "../../types/symbols.js";
+import type { ChangeTree, ParentChain, 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
+ * behavior).
+ */
+export function addParent(tree: ChangeTree, parent: Ref, index: number): void {
+    // Check if this parent already exists anywhere in the chain
+    if (tree.parentRef) {
+        if (tree.parentRef[$changes] === parent[$changes]) {
+            // Primary parent matches — update index
+            tree._parentIndex = index;
+            return;
+        }
+
+        // Check extra parents for duplicate
+        if (hasParent(tree, (p, _) => p[$changes] === parent[$changes])) {
+            // Match old behavior: update primary parent's index
+            tree._parentIndex = index;
+            return;
+        }
+    }
+
+    if (tree.parentRef === undefined) {
+        // First parent — store inline
+        tree.parentRef = parent;
+        tree._parentIndex = index;
+    } else {
+        // Push current inline parent to extraParents, set new as primary
+        tree.extraParents = {
+            ref: tree.parentRef,
+            index: tree._parentIndex,
+            next: tree.extraParents
+        };
+        tree.parentRef = parent;
+        tree._parentIndex = index;
+    }
+}
+
+/**
+ * Remove a parent from the chain.
+ * @returns true if parent was found and removed (Root.remove relies on this).
+ */
+export function removeParent(tree: ChangeTree, parent: Ref): boolean {
+    //
+    // FIXME: it is required to check against `$changes` here because
+    // ArraySchema is instance of Proxy
+    //
+    if (tree.parentRef && tree.parentRef[$changes] === parent[$changes]) {
+        // Removing inline parent — promote first extra parent if exists
+        if (tree.extraParents) {
+            tree.parentRef = tree.extraParents.ref;
+            tree._parentIndex = tree.extraParents.index;
+            tree.extraParents = tree.extraParents.next;
+        } else {
+            tree.parentRef = undefined;
+            tree._parentIndex = undefined;
+        }
+        return true;
+    }
+
+    // Search extra parents
+    let current = tree.extraParents;
+    let previous = null;
+    while (current) {
+        if (current.ref[$changes] === parent[$changes]) {
+            if (previous) {
+                previous.next = current.next;
+            } else {
+                tree.extraParents = current.next;
+            }
+            return true;
+        }
+        previous = current;
+        current = current.next;
+    }
+    return tree.parentRef === undefined;
+}
+
+/**
+ * Find the first parent in the chain matching `predicate`.
+ */
+export function findParent(
+    tree: ChangeTree,
+    predicate: (parent: Ref, index: number) => boolean,
+): ParentChain | undefined {
+    // Check inline parent first
+    if (tree.parentRef && predicate(tree.parentRef, tree._parentIndex)) {
+        return { ref: tree.parentRef, index: tree._parentIndex };
+    }
+
+    let current = tree.extraParents;
+    while (current) {
+        if (predicate(current.ref, current.index)) {
+            return current;
+        }
+        current = current.next;
+    }
+    return undefined;
+}
+
+export function hasParent(
+    tree: ChangeTree,
+    predicate: (parent: Ref, index: number) => boolean,
+): boolean {
+    return findParent(tree, predicate) !== undefined;
+}
+
+/**
+ * Return all parents as an array (debug/test helper).
+ */
+export function getAllParents(tree: ChangeTree): Array<{ ref: Ref, index: number }> {
+    const parents: Array<{ ref: Ref, index: number }> = [];
+    if (tree.parentRef) {
+        parents.push({ ref: tree.parentRef, index: tree._parentIndex });
+    }
+    let current = tree.extraParents;
+    while (current) {
+        parents.push({ ref: current.ref, index: current.index });
+        current = current.next;
+    }
+    return parents;
+}

package/src/encoder/changeTree/treeAttachment.ts

@@ -0,0 +1,171 @@
+/**
+ * Tree-attachment helpers: setRoot / setParent + child-iteration recursion.
+ * Hot path: every new Schema/Collection instance attached to the root
+ * goes through here, which is why the recursive walk uses a hoisted
+ * callback + ctx-pool instead of per-call closures.
+ */
+import type { MapSchema } from "../../types/custom/MapSchema.js";
+import { $changes, $childType, $refTypeFieldIndexes } from "../../types/symbols.js";
+import { Root } from "../Root.js";
+import type { ChangeTree, Ref } from "../ChangeTree.js";
+import { checkIsFiltered } from "./inheritedFlags.js";
+import { propagateNewChildToSubscribers } from "../subscriptions.js";
+
+export function setRoot(tree: ChangeTree, root: Root): void {
+    tree.root = root;
+
+    const isNewChangeTree = root.add(tree);
+
+    checkIsFiltered(tree, tree.parent, tree.parentIndex, isNewChangeTree);
+
+    // Recursively set root on child structures (closure-free hot path).
+    if (isNewChangeTree) {
+        forEachChildWithCtx(tree, root, _setRootChildCb);
+    }
+}
+
+export function setParent(
+    tree: ChangeTree,
+    parent: Ref,
+    root?: Root,
+    parentIndex?: number,
+): void {
+    tree.addParent(parent, parentIndex);
+
+    // avoid setting parents with empty `root`
+    if (!root) { return; }
+
+    const isNewChangeTree = root.add(tree);
+
+    // skip if parent is already set
+    if (root !== tree.root) {
+        tree.root = root;
+        checkIsFiltered(tree, parent, parentIndex, isNewChangeTree);
+    }
+
+    // Persistent-subscription propagation — when this new child is being
+    // attached to a collection that has one or more subscribed views,
+    // force-ship (or enqueue, for streams) the new child to each of them.
+    // Gated by `parent` being a collection (not a Schema) and the parent
+    // tree having a non-empty `subscribedViews` bitmap; both common-case
+    // short circuits are cheap.
+    const parentTree = parent?.[$changes];
+    if (
+        parentTree !== undefined &&
+        parentTree.subscribedViews !== undefined &&
+        // Collection check: `$childType` on the ref identifies Array/Map/
+        // Set/Collection/Stream. Schema-field parents don't have it.
+        (parent as any)[$childType] !== undefined
+    ) {
+        propagateNewChildToSubscribers(parentTree, parentIndex!, tree.ref, root);
+    }
+
+    // assign same parent on child structures (closure-free hot path).
+    // setParent recurses, so each depth gets its own ctx from a pool
+    // that grows to the recursion depth (typically tree height = 3-5).
+    if (isNewChangeTree) {
+        let ctx = _setParentCtxPool[_setParentDepth];
+        if (ctx === undefined) {
+            ctx = { parentRef: undefined!, root: undefined! };
+            _setParentCtxPool[_setParentDepth] = ctx;
+        }
+        ctx.parentRef = tree.ref;
+        ctx.root = root;
+        _setParentDepth++;
+        forEachChildWithCtx(tree, ctx, _setParentChildCb);
+        _setParentDepth--;
+    }
+}
+
+export function forEachChild(
+    tree: ChangeTree,
+    callback: (change: ChangeTree, at: any) => void,
+): void {
+    //
+    // assign same parent on child structures
+    //
+    if ((tree.ref as any)[$childType]) {
+        if (typeof ((tree.ref as any)[$childType]) !== "string") {
+            // MapSchema / ArraySchema, etc.
+            for (const [key, value] of (tree.ref as MapSchema).entries()) {
+                if (!value) { continue; } // sparse arrays can have undefined values
+                callback(value[$changes], (tree.ref as any)._collectionIndexes?.[key] ?? key);
+            };
+        }
+
+    } else {
+        const names = tree.encDescriptor.names;
+        for (const index of tree.metadata?.[$refTypeFieldIndexes] ?? []) {
+            const value = tree.ref[names[index] as keyof Ref];
+            if (!value) { continue; }
+            callback(value[$changes], index);
+        }
+    }
+}
+
+/**
+ * Closure-free variant of {@link forEachChild}. Hot setRoot / setParent
+ * recursion calls this once per new Schema instance attached to the
+ * tree — the per-call closure was the #1 JS hotspot in profile-baseline.
+ * Pass an explicit `ctx` so callers can hoist the callback to module
+ * scope and avoid the allocation.
+ */
+export function forEachChildWithCtx<C>(
+    tree: ChangeTree,
+    ctx: C,
+    callback: (ctx: C, change: ChangeTree, at: any) => void,
+): void {
+    // `refTarget` is the raw backing instance — identical to `ref` for all
+    // non-Proxy types (Schema / Map / Set / Collection / Stream), and the
+    // un-wrapped `$proxyTarget` for ArraySchema. Reading through it here
+    // skips the ArraySchema Proxy `get` trap on every `$childType`,
+    // `_collectionIndexes`, `.entries()`, `.items` lookup below — hot during
+    // the encodeAll DFS walk which touches every ArraySchema in the tree.
+    const ref = tree.refTarget as any;
+    if (ref[$childType]) {
+        if (typeof ref[$childType] !== "string") {
+            const collectionIndexes = ref._collectionIndexes;
+            for (const [key, value] of (ref as MapSchema).entries()) {
+                if (!value) { continue; }
+                callback(ctx, value[$changes], collectionIndexes?.[key] ?? key);
+            }
+        }
+    } else {
+        const metadata = tree.metadata;
+        const indexes = metadata?.[$refTypeFieldIndexes];
+        if (!indexes) return;
+        const names = tree.encDescriptor.names;
+        for (let i = 0, len = indexes.length; i < len; i++) {
+            const index = indexes[i];
+            const value = ref[names[index]];
+            if (!value) { continue; }
+            callback(ctx, value[$changes], index);
+        }
+    }
+}
+
+// Hoisted callbacks used by setRoot / setParent to avoid per-call
+// closure allocation in the recursive attach path.
+
+function _setRootChildCb(root: Root, child: ChangeTree, _index: any): void {
+    if (child.root !== root) {
+        child.setRoot(root);
+    } else {
+        root.add(child); // increment refCount
+    }
+}
+
+interface SetParentCtx { parentRef: Ref; root: Root; }
+// Pool of ctx objects, indexed by setParent recursion depth. Grows to
+// max depth seen (typically tree height = 3-5 in bench), then stays put.
+const _setParentCtxPool: SetParentCtx[] = [];
+let _setParentDepth = 0;
+
+function _setParentChildCb(ctx: SetParentCtx, child: ChangeTree, index: any): void {
+    if (child.root === ctx.root) {
+        ctx.root.add(child);
+        ctx.root.moveNextToParent(child);
+        return;
+    }
+    child.setParent(ctx.parentRef, ctx.root, index);
+}