@colyseus/schema 5.0.12 → 5.0.14

package/build/types/HelperTypes.d.ts

@@ -70,7 +70,7 @@ export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends
     stream: infer ChildType;
 } ? StreamSchema<ChildType> : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
 type OptionalBuilderKeys<T> = {
-    [K in keyof T]: T[K] extends FieldBuilder<infer V> ? (undefined extends V ? K : never) : never;
+    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean> ? (O extends true ? K : never) : never;
 }[keyof T];
 type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
 export type InferSchemaInstanceType<T> = {
@@ -89,12 +89,10 @@ export type NonFunctionNonPrimitivePropNames<T> = {
 }[keyof T];
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
 type ToJSONField<X> = X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : X extends ArraySchema<infer U> ? ToJSONValue<U>[] : X extends SetSchema<infer U> ? ToJSONValue<U>[] : X extends CollectionSchema<infer U> ? ToJSONValue<U>[] : X extends Schema ? ToJSON<X> : X;
-type ToJSONRequiredKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? never : K;
-}[keyof T];
 type ToJSONOptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? K : never;
+    [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<{
     [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
 } & {

package/build/types/builder.d.ts

@@ -45,10 +45,11 @@ export type BuilderOf<T> = FieldBuilder<T>;
  *    Schema ref whose `initialize` takes zero args.
  *  - `IsOptional` is a compile-time brand for `.optional()`. Both
  *    `HasDefault` and `IsOptional` make the field omittable in
- *    `BuilderInitProps<T>`. A separate brand (rather than reading
- *    `undefined extends V`) sidesteps a TypeScript quirk where
- *    class-generic-inferred `V` resolves `undefined extends V` as `true`
- *    even for non-undefined types.
+ *    `BuilderInitProps<T>`; `IsOptional` alone marks the instance property
+ *    `?:`. A separate brand (rather than reading `undefined extends V`)
+ *    keeps both correct for consumers compiling with
+ *    `strictNullChecks: false`, where `undefined extends V` is true for
+ *    every V.
  *
  * schema() reads the internal configuration via `toDefinition()` and wires
  * up metadata through the existing pipeline.
@@ -199,8 +200,8 @@ export declare function isBuilder(value: any): value is FieldBuilder<any>;
  * Two call signatures, NOT a defaulted generic `<T extends TBase = TBase>`: the
  * bare form must return a CONCRETE `FieldBuilder<TBase>` so `schema({ x:
  * t.number() })` still infers `x: number`. A defaulted free type parameter gets
- * captured as `any` during `schema()`'s self-referential field inference (and
- * `undefined extends any` then flips every field optional).
+ * captured as `any` during `schema()`'s self-referential field inference,
+ * degrading every field's value type to `any`.
  *
  * NOTE: the refinement is a TYPE-LEVEL assertion, not a runtime guarantee — the
  * wire still carries the codec's full range and the DECODER writes whatever

package/build/types/custom/ArraySchema.d.ts

@@ -63,6 +63,23 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
      * land on the wrong wire slots.
      */
     protected $wireIndex(index: number): number;
+    /**
+     * Re-point children at their wire slot. `ChangeTree._parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader and reaches the index only through a filtered array
+     * (`addParentOf` bails on `hasFilteredFields`, `remove` on the child's
+     * `isFiltered`). Everything else stops at the flag read instead of walking
+     * its children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]): void;
     protected $changeAt(index: number, value: V): number | undefined;
     protected $deleteAt(index: number, operation?: OPERATION): void;
     protected $setAt(index: number, value: V, operation: OPERATION): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.12",
+  "version": "5.0.14",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -18,7 +18,7 @@
     "watch": "tsc -p tsconfig.build.json -w",
     "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
     "test": "npm run test:types && tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
-    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
+    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json && tsc -p tsconfig.types-nostrict.json",
     "test:exports": "node test/verify-exports.mjs",
     "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",

package/src/encoder/ChangeTree.ts

@@ -34,6 +34,7 @@ import type { DecodeOperation } from "../decoder/DecodeOperation.js";
 
 import {
     addParent as _addParent, removeParent as _removeParent,
+    setParentIndex as _setParentIndex,
     findParent as _findParent, hasParent as _hasParent,
     getAllParents as _getAllParents,
 } from "./changeTree/parentChain.js";
@@ -804,6 +805,9 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
 
     addParent(parent: Ref, index: number): void { _addParent(this, parent, index); }
 
+    /** Re-point an existing parent's cached index after the parent reindexed. */
+    setParentIndex(parent: Ref, index: number): void { _setParentIndex(this, parent, index); }
+
     /** @returns true if parent was found and removed */
     removeParent(parent: Ref = this.parent): boolean { return _removeParent(this, parent); }
 
@@ -856,6 +860,7 @@ export class UntrackedChangeTree {
     operation(): void {}
     setParent(): void {}
     addParent(): void {}
+    setParentIndex(): void {}
     removeParent(): boolean { return false; }
     getChange(): number { return 0; }
     discard(): void {}

package/src/encoder/changeTree/parentChain.ts

@@ -45,6 +45,35 @@ export function addParent(tree: ChangeTree, parent: Ref, index: number): void {
     }
 }
 
+/**
+ * Move `parent`'s existing chain entry to `index`, skipping the attachment
+ * work `addParent` does. `parent` must already be a parent of `tree`.
+ *
+ * Called by collections whose wire slots shift (ArraySchema): StateView
+ * addresses per-view ADD/DELETE by that index, so it has to follow the
+ * element it names.
+ */
+export function setParentIndex(tree: ChangeTree, parent: Ref, index: number): void {
+    if (tree.extraParents === undefined) {
+        tree._parentIndex = index; // sole parent, so it is `parent`
+        return;
+    }
+    // Shared instance — move only the entry `parent` owns. Matching goes
+    // through `$changes` because ArraySchema arrives proxied (see removeParent
+    // below), and `extraParents` only ever fills by demoting `parentRef`, so
+    // the inline parent is set here.
+    if (tree.parentRef[$changes] === parent[$changes]) {
+        tree._parentIndex = index;
+        return;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (entry.ref[$changes] === parent[$changes]) {
+            entry.index = index;
+            return;
+        }
+    }
+}
+
 /**
  * Remove a parent from the chain.
  * @returns true if parent was found and removed (Root.remove relies on this).

package/src/types/HelperTypes.ts

@@ -87,10 +87,12 @@ export type InferValueType<T> =
 
     : never;
 
-// Keys whose FieldBuilder generic admits `undefined` (i.e. `.optional()` was chained).
+// 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<infer V>
-        ? (undefined extends V ? K : never)
+    [K in keyof T]: T[K] extends FieldBuilder<unknown, boolean, infer O extends boolean>
+        ? (O extends true ? K : never)
         : never
 }[keyof T];
 
@@ -136,14 +138,16 @@ type ToJSONField<X> =
     : X extends Schema ? ToJSON<X>
     : X;
 
-// Keys whose value type admits `undefined` — runtime `toJSON()` omits those,
-// so they surface as `?:` on the JSON shape.
-type ToJSONRequiredKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? never : K
-}[keyof T];
+// 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 T[K] ? K : never
+    [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<
     & { [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]> }
@@ -226,10 +230,9 @@ type FieldValue<F> =
 
 // Classify each key of a fields map as "required" / "optional" / "none"
 // (methods). Both `HasDefault = true` and the explicit `.optional()` brand
-// `IsOptional = true` mark the field omittable at construction. The brand
-// sidesteps a TypeScript quirk where `undefined extends V` returned `true`
-// for non-undefined V when V was inferred from a class with T in
-// contravariant + covariant positions.
+// `IsOptional = true` mark the field omittable at construction. Reading the
+// brands (never `undefined extends V`) keeps this correct for consumers on
+// `strictNullChecks: false`, where `undefined extends V` is true for every V.
 type KeyClass<T, K extends keyof T> =
     T[K] extends FieldBuilder<unknown, infer D extends boolean, infer O extends boolean>
         ? (D extends true

package/src/types/builder.ts

@@ -51,10 +51,11 @@ export type BuilderOf<T> = FieldBuilder<T>;
  *    Schema ref whose `initialize` takes zero args.
  *  - `IsOptional` is a compile-time brand for `.optional()`. Both
  *    `HasDefault` and `IsOptional` make the field omittable in
- *    `BuilderInitProps<T>`. A separate brand (rather than reading
- *    `undefined extends V`) sidesteps a TypeScript quirk where
- *    class-generic-inferred `V` resolves `undefined extends V` as `true`
- *    even for non-undefined types.
+ *    `BuilderInitProps<T>`; `IsOptional` alone marks the instance property
+ *    `?:`. A separate brand (rather than reading `undefined extends V`)
+ *    keeps both correct for consumers compiling with
+ *    `strictNullChecks: false`, where `undefined extends V` is true for
+ *    every V.
  *
  * schema() reads the internal configuration via `toDefinition()` and wires
  * up metadata through the existing pipeline.
@@ -289,8 +290,8 @@ export function isBuilder(value: any): value is FieldBuilder<any> {
  * Two call signatures, NOT a defaulted generic `<T extends TBase = TBase>`: the
  * bare form must return a CONCRETE `FieldBuilder<TBase>` so `schema({ x:
  * t.number() })` still infers `x: number`. A defaulted free type parameter gets
- * captured as `any` during `schema()`'s self-referential field inference (and
- * `undefined extends any` then flips every field optional).
+ * captured as `any` during `schema()`'s self-referential field inference,
+ * degrading every field's value type to `any`.
  *
  * NOTE: the refinement is a TYPE-LEVEL assertion, not a runtime guarantee — the
  * wire still carries the codec's full range and the DECODER writes whatever

package/src/types/custom/ArraySchema.ts

@@ -331,6 +331,35 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return tmpItems.length + (index - live);
     }
 
+    /**
+     * Re-point children at their wire slot. `ChangeTree._parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader and reaches the index only through a filtered array
+     * (`addParentOf` bails on `hasFilteredFields`, `remove` on the child's
+     * `isFiltered`). Everything else stops at the flag read instead of walking
+     * its children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]) {
+        if (!this[$changes].hasFilteredFields) { return; } // nothing will read the cache
+        if (typeof this[$childType] === "string") { return; } // primitives have no child tree
+        const tmpItems = this.tmpItems;
+        const length = tmpItems.length;
+        if (staged !== undefined) {
+            while (from < length && tmpItems[from] === staged[from]) { from++; }
+        }
+        for (let i = from; i < length; i++) {
+            tmpItems[i]?.[$changes]?.setParentIndex(this, i);
+        }
+    }
+
     // encoding only. Returns the wire index the change was recorded at
     // (undefined when nothing was recorded).
     protected $changeAt(index: number, value: V): number | undefined {
@@ -460,6 +489,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         self[$changes].operation(OPERATION.REVERSE);
         self.items.reverse();
         self.tmpItems.reverse();
+        self.$reindexChildren(0);
         return this;
     }
 
@@ -515,6 +545,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         sortedItems.forEach((_, i) => changeTree.change(i, OPERATION.REPLACE));
 
         self.tmpItems.sort(compareFn);
+        self.$reindexChildren(0);
 
         self.isMovingItems = false;
         return this;
@@ -620,6 +651,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         }
 
         self.tmpItems.unshift(...items);
+        self.$reindexChildren(items.length); // survivors only — the loop above placed the new items
 
         return self.items.unshift(...items);
     }
@@ -938,8 +970,15 @@ 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();
-        self.deletedIndexes.length = 0;
+
+        if (self.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;
+        }
     }
 
     protected [$onDecodeEnd]() {