@colyseus/schema 5.0.14 → 5.0.20

package/src/encoder/changeTree/parentChain.ts

@@ -5,7 +5,7 @@
  * additional parents live in the `extraParents` linked list.
  */
 import { $changes } from "../../types/symbols.js";
-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
@@ -115,39 +115,69 @@ export 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 function findParent(
     tree: ChangeTree,
     predicate: (parent: Ref, index: number) => boolean,
-): ParentChain | undefined {
-    // Check inline parent first
-    if (tree.parentRef && predicate(tree.parentRef, tree._parentIndex)) {
+): ParentEntry | undefined {
+    if (tree.parentRef !== undefined && 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;
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (predicate(entry.ref, entry.index)) {
+            return { ref: entry.ref, index: entry.index };
         }
-        current = current.next;
     }
     return undefined;
 }
 
+/** Walks in place — `addParent` calls this per shared-instance attach. */
 export function hasParent(
     tree: ChangeTree,
     predicate: (parent: Ref, index: number) => boolean,
 ): boolean {
-    return findParent(tree, predicate) !== undefined;
+    if (tree.parentRef !== undefined && predicate(tree.parentRef, tree._parentIndex)) {
+        return true;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (predicate(entry.ref, entry.index)) { return true; }
+    }
+    return false;
 }
 
 /**
- * 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 function getAllParents(tree: ChangeTree): Array<{ ref: Ref, index: number }> {
-    const parents: Array<{ ref: Ref, index: number }> = [];
+export function indexInParent(tree: ChangeTree, parent: Ref): number | undefined {
+    // `$changes` comparison — ArraySchema parents arrive proxied.
+    if (tree.parentRef && tree.parentRef[$changes] === parent[$changes]) {
+        return tree._parentIndex;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (entry.ref[$changes] === parent[$changes]) {
+            return entry.index;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Return all parents as detached entries (debug/test helper).
+ */
+export function getAllParents(tree: ChangeTree): ParentEntry[] {
+    const parents: ParentEntry[] = [];
     if (tree.parentRef) {
         parents.push({ ref: tree.parentRef, index: tree._parentIndex });
     }
@@ -158,3 +188,30 @@ export function getAllParents(tree: ChangeTree): Array<{ ref: Ref, index: number
     }
     return parents;
 }
+
+/**
+ * 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 function isEdgeLive(tree: ChangeTree, parentTree: ChangeTree, index: number): boolean {
+    const target = parentTree.refTarget as any;
+    if (parentTree.isArray) {
+        // Read `items` directly, not `$getByIndex` — the latter serves the
+        // staged (tmpItems) view, which can still hold a same-tick removal.
+        const items = target.items;
+        const at = items[index];
+        if (at !== undefined && at[$changes] === tree) return true;
+        // Recorded slot goes stale after reorders — scan before declaring dead.
+        for (let i = 0, len = items.length; i < len; i++) {
+            const v = items[i];
+            if (v !== undefined && v[$changes] === tree) return true;
+        }
+        return false;
+    }
+    const at = parentTree.getValue(index);
+    return at !== undefined && at[$changes] === tree;
+}

package/src/encoder/streaming.ts

@@ -204,7 +204,8 @@ export function streamDequeueForView(
     viewId: number,
     refId: number,
     index: number,
-    viewChanges: Map<number, Map<number, number>>,
+    // widened key: StateView.changes carries identity-keyed array entries too
+    viewChanges: Map<number, Map<number | object, number>>,
 ): boolean {
     const st = s._stream;
     if (st === undefined) return false;

package/src/types/HelperTypes.ts

@@ -17,10 +17,18 @@ type PrimitiveStringToType<T> =
     : T extends "boolean" ? boolean
     : T;
 
-export interface Collection<K = any, V = any, IT = V> {
+/**
+ * What the decoder callbacks accept as "a collection": the public shape, which
+ * a plain array satisfies too — `@type([X]) items: X[]` is a common way to
+ * declare a field. {@link Collection} is the runtime contract on top of it.
+ */
+export interface CollectionLike<K = any, V = any, IT = V> {
     [Symbol.iterator](): IterableIterator<IT>;
     forEach(callback: Function): void;
     entries(): IterableIterator<[K, V]>;
+}
+
+export interface Collection<K = any, V = any, IT = V> extends CollectionLike<K, V, IT> {
     /** See {@link $resyncPrune} — every collection kind must declare its resync-sweep semantics. */
     [$resyncPrune](
         visited: Set<number | string>,
@@ -90,13 +98,13 @@ export type InferValueType<T> =
 // Keys whose builder carries the `.optional()` brand. Reads the brand rather
 // than `undefined extends V`: the latter is true for EVERY V when the consumer
 // compiles with `strictNullChecks: false`, flipping all fields optional.
-type OptionalBuilderKeys<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean>
-        ? (O extends true ? K : never)
-        : never
-}[keyof T];
+type IsOptionalBuilderKey<T, K extends keyof T> =
+    T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? O : false;
 
-type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
+// Per key, like `DataKey` below — an `Exclude<keyof T, …>` split defers every
+// key once one field is typed by a bare type parameter.
+type OptionalBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? K : never }[keyof T];
+type RequiredBuilderKeys<T> = { [K in keyof T]-?: IsOptionalBuilderKey<T, K> extends true ? never : K }[keyof T];
 
 export type InferSchemaInstanceType<T> = {
     [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any>
@@ -110,20 +118,20 @@ export type InferSchemaInstanceType<T> = {
         : never
 } & Schema;
 
-export type NonFunctionProps<T> = Omit<T, {
-    [K in keyof T]: T[K] extends Function ? K : never;
-}[keyof T]>;
+// Per-key filter, never `Omit`/`Exclude` over the union of method names: with
+// one field typed by a bare type parameter that union defers EVERY key, and a
+// mapped type with no resolvable keys has no members to relate — which is what
+// stopped `SpecialNode<E>` from satisfying `extends NodeBase`.
+// `keyof Schema` is dropped so `restore({ ... })` takes a plain literal.
+type DataKey<T, K extends keyof T> =
+    K extends keyof Schema ? never
+    : T[K] extends Function ? never
+    : K;
 
-export type NonFunctionPropNames<T> = {
-    [K in keyof T]: T[K] extends Function ? never : K
-}[keyof T];
+export type NonFunctionPropNames<T> = { [K in keyof T]-?: DataKey<T, K> }[keyof T];
 
 export type NonFunctionNonPrimitivePropNames<T> = {
-    [K in keyof T]: T[K] extends Function
-        ? never
-        : T[K] extends number | string | boolean
-            ? never
-            : K
+    [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : T[K] extends number | string | boolean ? never : K
 }[keyof T];
 
 // Helper to recursively convert Schema instances to their JSON representation
@@ -138,21 +146,23 @@ type ToJSONField<X> =
     : X extends Schema ? ToJSON<X>
     : X;
 
-// Keys whose value admits `undefined` — runtime `toJSON()` omits those, so
-// they surface as `?:` on the JSON shape. Under `strictNullChecks: false`
-// (`undefined extends {}` detects it) `undefined extends T[K]` is true for
-// every key, so only the `?` modifier can signal optionality there.
-type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends {}
-        ? ({} extends Pick<T, K> ? K : never)
-        : (undefined extends T[K] ? K : never)
-}[keyof T];
-type ToJSONRequiredKeys<T> = Exclude<keyof T, ToJSONOptionalKeys<T>>;
-
-export type ToJSON<T> = NonFunctionProps<
+// Runtime `toJSON()` omits `undefined` values, so those keys surface as `?:`.
+// Under `strictNullChecks: false` (`undefined extends {}` detects it)
+// `undefined extends T[K]` is true for every key, so only the `?` modifier
+// can signal optionality there.
+type IsOptionalKey<T, K extends keyof T> = undefined extends {}
+    ? ({} extends Pick<T, K> ? true : false)
+    : (undefined extends T[K] ? true : false);
+
+// `DataKey` first: machinery and method keys drop before the optionality probe.
+type ToJSONRequiredKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? never : K }[keyof T];
+type ToJSONOptionalKeys<T> = { [K in keyof T]-?: [DataKey<T, K>] extends [never] ? never : IsOptionalKey<T, K> extends true ? K : never }[keyof T];
+
+// Keys are filtered before mapping: `ToJSONField` over the `this`-typed methods
+// exceeds TypeScript 7's instantiation depth.
+export type ToJSON<T> =
     & { [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]> }
-    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> }
->;
+    & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> };
 
 /**
  * The plain DATA shape of a Schema instance type `T`: its synchronized fields
@@ -172,8 +182,7 @@ export type ToJSON<T> = NonFunctionProps<
  *
  * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
  * structural projection: nested Schema / collection fields keep their instance
- * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
- * `NonFunctionProps` pass leaves behind.
+ * types.
  */
 export type Data<T> = Omit<T, keyof Schema>;
 

package/src/types/TypeContext.ts

@@ -8,16 +8,6 @@ export class TypeContext {
     schemas = new Map<typeof Schema, number>();
 
     hasFilters: boolean = false;
-    parentFiltered: {[typeIdAndParentIndex: string]: boolean} = {};
-    /**
-     * True iff `parentFiltered` has at least one entry. Flipped on by
-     * `registerFilteredByParent` and read in `checkInheritedFlags` as a
-     * cheap gate to skip the string-keyed `parentFiltered[key]` lookup
-     * when no class has registered filter inheritance via ancestry — the
-     * common case when @view tags exist only on sibling fields, not
-     * along any attachment chain.
-     */
-    hasParentFilteredEntries: boolean = false;
 
     /**
      * For inheritance support
@@ -84,17 +74,13 @@ export class TypeContext {
         return this.schemas.get(klass);
     }
 
-    private discoverTypes(klass: typeof Schema, parentType?: typeof Schema, parentIndex?: number, parentHasViewTag?: boolean) {
-        if (parentHasViewTag) {
-            this.registerFilteredByParent(klass, parentType, parentIndex);
-        }
-
+    private discoverTypes(klass: typeof Schema) {
         // skip if already registered
         if (!this.add(klass)) { return; }
 
         // add classes inherited from this base class
         TypeContext.inheritedTypes.get(klass)?.forEach((child) => {
-            this.discoverTypes(child, parentType, parentIndex, parentHasViewTag);
+            this.discoverTypes(child);
         });
 
         // add parent classes
@@ -120,7 +106,6 @@ export class TypeContext {
             const index = fieldIndex as any as number;
 
             const fieldType = metadata[index].type;
-            const fieldHasViewTag = (metadata[index].tag !== undefined);
 
             if (typeof (fieldType) === "string") {
                 continue;
@@ -133,7 +118,7 @@ export class TypeContext {
             }
 
             if (typeof (fieldType) === "function") {
-                this.discoverTypes(fieldType as typeof Schema, klass, index, parentHasViewTag || fieldHasViewTag);
+                this.discoverTypes(fieldType as typeof Schema);
 
             } else {
                 const type = Object.values(fieldType)[0];
@@ -143,47 +128,15 @@ export class TypeContext {
                     continue;
                 }
 
-                this.discoverTypes(type as typeof Schema, klass, index, parentHasViewTag || fieldHasViewTag);
+                this.discoverTypes(type as typeof Schema);
             }
         }
     }
 
-    /**
-     * Keep track of which classes have filters applied.
-     * Format: `${typeid}-${parentTypeid}-${parentIndex}`
-     */
-    private registerFilteredByParent(schema: typeof Schema, parentType?: typeof Schema, parentIndex?: number) {
-        const typeid = this.schemas.get(schema) ?? this.schemas.size;
-
-        let key = `${typeid}`;
-        if (parentType) { key += `-${this.schemas.get(parentType)}`; }
-
-        key += `-${parentIndex}`;
-        this.parentFiltered[key] = true;
-        this.hasParentFilteredEntries = true;
-    }
-
     debug() {
-        let parentFiltered = "";
-
-        for (const key in this.parentFiltered) {
-            const keys: number[] = key.split("-").map(Number);
-            const fieldIndex = keys.pop();
-
-            parentFiltered += `\n\t\t`;
-            parentFiltered += `${key}: ${keys.reverse().map((id, i) => {
-                const klass = this.types[id];
-                const metadata: Metadata = klass[Symbol.metadata];
-                let txt = klass.name;
-                if (i === 0) { txt += `[${metadata[fieldIndex].name}]`; }
-                return `${txt}`;
-            }).join(" -> ")}`;
-        }
-
         return `TypeContext ->\n` +
             `\tSchema types: ${this.schemas.size}\n` +
-            `\thasFilters: ${this.hasFilters}\n` +
-            `\tparentFiltered:${parentFiltered}`;
+            `\thasFilters: ${this.hasFilters}`;
     }
 
 }

package/src/types/builder.ts

@@ -307,16 +307,24 @@ function primitive<TBase>(name: RawPrimitiveType): PrimitiveFactory<TBase> {
     return (() => new FieldBuilder<TBase>(name)) as PrimitiveFactory<TBase>;
 }
 
-// Accepts a Schema class, a primitive string, or another FieldBuilder as a child type.
+// Collection element: a Schema class or a primitive type NAME (`"string"`).
 export type ChildType =
     | RawPrimitiveType
-    | Constructor<Schema>
-    | FieldBuilder<any>;
+    | Constructor<Schema>;
 
+/**
+ * Guard against `t.array(t.string())`. A builder child looks like it should
+ * work — and its bare `_type` would — but every modifier on it (`.view()`,
+ * `.default()`, quantize options) would be silently dropped, since modifiers
+ * describe the FIELD, not the elements. Fail loudly instead.
+ */
 function resolveChild(child: ChildType): DefinitionType {
     if (isBuilder(child)) {
-        // `_type` is private; element access bypasses the visibility check.
-        return child['_type'];
+        const inner = child['_type']; // private; element access bypasses the check
+        const hint = (typeof inner === "string")
+            ? `use the type name instead: t.array("${inner}")`
+            : `collections accept a Schema class or a primitive type name ("string", "number", …)`;
+        throw new Error(`t.array/map/set/collection(): a t.* builder is not a valid element type — ${hint}.`);
     }
     return child as DefinitionType;
 }
@@ -326,28 +334,24 @@ function resolveChild(child: ChildType): DefinitionType {
 // ---------------------------------------------------------------------------
 
 // Overloaded factories for collections. Implementation lives in a single function;
-// overloads narrow the return type for Schema/primitive/builder children.
+// overloads narrow the return type for Schema/primitive children.
 // All collection factories tag `HasDefault = true` because schema() auto-
 // instantiates an empty collection when no explicit default is given.
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>, true, false>;
 }
 interface MapFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>, true, false>;
 }
 interface SetFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>, true, false>;
 }
 interface CollectionFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
     <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
-    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>, true, false>;
 }
 // t.stream(Entity) — priority-batched collection of Schema instances.
 // Element type is restricted to Schema subclasses (no primitives) because

package/src/types/custom/ArraySchema.ts

@@ -178,7 +178,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         const proxy = new Proxy(this, ARRAY_PROXY_HANDLER);
 
         Object.defineProperty(this, $changes, {
-            value: new ChangeTree(proxy),
+            value: new ChangeTree(proxy, this),
             enumerable: false,
             writable: true,
         });
@@ -486,7 +486,22 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     // @ts-ignore
     reverse(): ArraySchema<V> {
         const self = this[$proxyTarget];
-        self[$changes].operation(OPERATION.REVERSE);
+        const changeTree = self[$changes];
+
+        if (changeTree.has() || self.deletedIndexes.length > 0) {
+            //
+            // Ops recorded earlier this tick address the staged (pre-reverse)
+            // layout, and the encoder only resolves their values at encode
+            // time — a pure REVERSE would move that layout under them.
+            // Degrade to a full re-state: CLEAR + re-ADD in reversed order.
+            //
+            const reversed = self.items.slice().reverse();
+            this.clear(); // also drops staged holes (discard → $onEncodeEnd)
+            this.push(...reversed);
+            return this;
+        }
+
+        changeTree.operation(OPERATION.REVERSE);
         self.items.reverse();
         self.tmpItems.reverse();
         self.$reindexChildren(0);
@@ -602,13 +617,13 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
 
         // insert operations
         if (insertCount > 0) {
-            if (insertCount > deleteCount) {
-                console.error("Inserting more elements than deleting during ArraySchema#splice()");
-                throw new Error("ArraySchema#splice(): insertCount must be equal or lower than deleteCount.");
-            }
+            const base = indexes[start] ?? itemsLength;
 
-            for (let i = 0; i < insertCount; i++) {
-                const addIndex = (indexes[start] ?? itemsLength) + i;
+            // the first `reuse` items take over the wire slots just deleted
+            const reuse = Math.min(insertCount, deleteCount);
+
+            for (let i = 0; i < reuse; i++) {
+                const addIndex = base + i;
 
                 changeTree.indexedOperation(
                     addIndex,
@@ -617,9 +632,36 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
                         : OPERATION.ADD
                 );
 
+                // the slot is live again — the staged snapshot must carry the
+                // new value, or `$getByIndex` falls back to `items[addIndex]`
+                // and resolves an unrelated element once tmp/items diverge.
+                tmpItems[addIndex] = insertItems[i];
+                deletedIndexes[addIndex] = false;
+
                 // set value's parent/root — use `this` (Proxy) as parent.
                 insertItems[i][$changes]?.setParent(this, changeTree.root, addIndex);
             }
+
+            // ...the rest have no slot to take: widen the wire layout, same as
+            // unshift() but at `at` instead of 0.
+            const extra = insertCount - reuse;
+            if (extra > 0) {
+                const at = base + reuse;
+
+                changeTree.insertAt(at, extra);
+
+                for (let i = 0; i < extra; i++) {
+                    insertItems[reuse + i][$changes]?.setParent(this, changeTree.root, at + i);
+                }
+
+                // keep staged-delete flags aligned with the inserted tmp slots
+                if (deletedIndexes.length > 0) {
+                    deletedIndexes.splice(at, 0, ...new Array(extra).fill(false));
+                }
+
+                tmpItems.splice(at, 0, ...insertItems.slice(reuse));
+                self.$reindexChildren(at + extra); // survivors only — the loop above placed the new items
+            }
         }
 
         changeTree.root?.enqueueChangeTree(changeTree);
@@ -969,15 +1011,16 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     }
 
     protected [$onEncodeEnd]() {
-        const self = this[$proxyTarget] ?? this;
-        const staged = self.tmpItems;
-        self.tmpItems = self.items.slice();
+        // No unwrap: ChangeTree's gated sites are the only callers and they
+        // invoke on `refTarget` (the raw target) already.
+        const staged = this.tmpItems;
+        this.tmpItems = this.items.slice();
 
-        if (self.deletedIndexes.length > 0) {
+        if (this.deletedIndexes.length > 0) {
             // compaction just closed the staged holes — everything above the
             // lowest one slid down a slot
-            self.$reindexChildren(0, staged);
-            self.deletedIndexes.length = 0;
+            this.$reindexChildren(0, staged);
+            this.deletedIndexes.length = 0;
         }
     }
 

package/src/types/symbols.ts

@@ -131,6 +131,9 @@ export const $viewFieldIndexes = "~__viewFieldIndexes";
 export const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 export const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
 export const $patchOnlyFieldIndexes = "~__patchOnlyFieldIndexes";
+// @patchOnly ∪ @deprecated() — indexes the full-sync walk must not read (the
+// deprecated accessor may throw). Maintained at decoration time.
+export const $fullSyncSkipIndexes = "~__fullSyncSkipIndexes";
 export const $fullStateOnlyFieldIndexes = "~__fullStateOnlyFieldIndexes";
 export const $streamFieldIndexes = "~__streamFieldIndexes";
 export const $streamPriorities = "~__streamPriorities";