@colyseus/schema 5.0.2 → 5.0.4

package/build/decoder/strategy/Callbacks.d.ts

@@ -36,12 +36,12 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to property changes on a nested instance.
      */
-    listen<TInstance extends Schema, K extends PublicPropNames<TInstance>>(instance: TInstance, property: K, handler: PropertyChangeCallback<TInstance[K]>, immediate?: boolean): () => void;
+    listen<TInstance, K extends PublicPropNames<TInstance>>(instance: TInstance, property: K, handler: PropertyChangeCallback<TInstance[K]>, immediate?: boolean): () => void;
     protected listenInstance<TInstance extends IRef>(instance: TInstance, propertyName: string, handler: PropertyChangeCallback<any>, immediate?: boolean): () => void;
     /**
      * Listen to any property change on an instance.
      */
-    onChange<TInstance extends Schema>(instance: TInstance, handler: InstanceChangeCallback): () => void;
+    onChange<TInstance extends object>(instance: TInstance, handler: InstanceChangeCallback): () => void;
     /**
      * Listen to item changes in a collection on root state.
      */
@@ -49,7 +49,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to item changes in a nested collection.
      */
-    onChange<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
+    onChange<TInstance extends object, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>): () => void;
     /**
      * Listen to items added to a collection on root state.
      */
@@ -57,7 +57,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items added to a nested collection.
      */
-    onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>, immediate?: boolean): () => void;
+    onAdd<TInstance, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>, immediate?: boolean): () => void;
     /**
      * Listen to items removed from a collection on root state.
      */
@@ -65,12 +65,12 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items removed from a nested collection.
      */
-    onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>): () => void;
+    onRemove<TInstance, K extends CollectionPropNames<TInstance>>(instance: TInstance, property: K, handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>): () => void;
     /**
      * Bind properties from a Schema instance to a target object.
      * Changes will be automatically reflected on the target object.
      */
-    bindTo<TInstance extends Schema, TTarget>(from: TInstance, to: TTarget, properties?: string[], immediate?: boolean): () => void;
+    bindTo<TInstance, TTarget>(from: TInstance, to: TTarget, properties?: string[], immediate?: boolean): () => void;
     protected triggerChanges(allChanges: DataChange[]): void;
 }
 /**

package/build/encoder/StateView.d.ts

@@ -107,6 +107,23 @@ export declare class StateView {
      */
     private _markSubtreeVisible;
     protected addParentOf(childChangeTree: ChangeTree, tag: number): void;
+    /**
+     * Walk `tree`'s parent chain to root and insert an empty entry into
+     * `view.changes` for any ancestor not already present. Empty entries
+     * are skipped by `encodeView` (`changes.size === 0` continue), so no
+     * wire bytes are emitted — but the Map's insertion order now puts
+     * each ancestor BEFORE the descendant entry that the caller is about
+     * to write. Combined with `addParentOf`'s full-recursion walk on
+     * `view.add`, this preserves the global invariant that
+     * `view.changes` iteration order is topological.
+     *
+     * Iterative (not recursive) so the stack is bounded by tree depth
+     * regardless of call patterns. Stops the walk as soon as it hits an
+     * ancestor that's already in `view.changes` — at that point the
+     * remainder of the chain is guaranteed to also be present (invariant
+     * upheld by every prior caller).
+     */
+    private _touchAncestorsOf;
     remove(obj: Ref, tag?: number): this;
     remove(obj: Ref, tag?: number, _isClear?: boolean): this;
     has(obj: Ref): boolean;

package/build/index.cjs

@@ -1214,6 +1214,33 @@ const Metadata = {
     getStreamPriority(metadata, index) {
         return metadata?.[$streamPriorities]?.[index];
     },
+    /**
+     * Install a single field with full encoder wiring: accessor descriptor
+     * on the prototype + `metadata[$encoders]` slot for primitives. Shared
+     * between `Metadata.setFields` (build path) and
+     * `Reflection.makeEncodable` (Reflection upgrade path).
+     */
+    defineField(target, metadata, fieldIndex, fieldName, type) {
+        const normalized = getNormalizedType(type);
+        const { complexTypeKlass, childType } = resolveFieldType(normalized);
+        Metadata.addField(metadata, fieldIndex, fieldName, normalized, getPropertyDescriptor(fieldName, fieldIndex, childType, complexTypeKlass));
+        // Install accessor descriptor on the prototype (once per class field).
+        if (metadata[$descriptors][fieldName]) {
+            Object.defineProperty(target.prototype, fieldName, metadata[$descriptors][fieldName]);
+        }
+        // Pre-compute encoder function for primitive types.
+        if (typeof normalized === "string") {
+            if (!metadata[$encoders]) {
+                Object.defineProperty(metadata, $encoders, {
+                    value: [],
+                    enumerable: false,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            metadata[$encoders][fieldIndex] = encode[normalized];
+        }
+    },
     setFields(target, fields) {
         // for inheritance support
         const constructor = target.prototype.constructor;
@@ -1251,17 +1278,7 @@ const Metadata = {
             });
         }
         for (const field in fields) {
-            const type = getNormalizedType(fields[field]);
-            const { complexTypeKlass, childType } = resolveFieldType(type);
-            Metadata.addField(metadata, fieldIndex, field, type, getPropertyDescriptor(field, fieldIndex, childType, complexTypeKlass));
-            // Install accessor descriptor on the prototype (once per class field).
-            if (metadata[$descriptors][field]) {
-                Object.defineProperty(target.prototype, field, metadata[$descriptors][field]);
-            }
-            // Pre-compute encoder function for primitive types.
-            if (typeof type === "string") {
-                metadata[$encoders][fieldIndex] = encode[type];
-            }
+            Metadata.defineField(constructor, metadata, fieldIndex, field, fields[field]);
             fieldIndex++;
         }
         return target;
@@ -2093,11 +2110,24 @@ function checkInheritedFlags(tree, parent, parentIndex) {
         const refType = Metadata.isValidInstance(tree.ref)
             ? tree.ref.constructor
             : tree.ref[$childType];
+        // #218: nested Schema fields inherit visibility from a @view-gated
+        // parent regardless of whether the parent is a collection. The
+        // `parentIsCollection` constraint that used to live here blocked
+        // nested-Schema-field-of-@view-tagged-Schema from sharing visibility,
+        // forcing users to wrap the child in an ArraySchema as a workaround.
+        //
+        // #226 (4.0.25): items inside a non-default-tag `@view(N)` collection
+        // also inherit visibility from the parent collection, so items
+        // pushed/set after `view.add(state, N)` show up automatically.
+        // Default-tag `@view()` collections keep per-item gating —
+        // `view.add(item)` is still required to opt each one in.
+        // The `parentMetadata[parentIndex].tag` access is safe inside the
+        // `fieldHasViewTag` short-circuit (the metadata entry and its `tag`
+        // are guaranteed to exist when that flag is set).
         tree.isVisibilitySharedWithParent = (parentChangeTree.isFiltered
             && typeof refType !== "string"
-            && !fieldHasViewTag
             && !fieldHasStream
-            && parentIsCollection);
+            && (!fieldHasViewTag || (parentIsCollection && parentMetadata[parentIndex].tag !== DEFAULT_VIEW_TAG)));
     }
 }
 
@@ -5430,8 +5460,10 @@ registerType("stream", { constructor: StreamSchema });
  */
 class FieldBuilder {
     [$builder] = true;
-    // Internal configuration. Public so schema() and tests can read it, but not
-    // meant to be mutated by users directly.
+    // Internal configuration. Declared `private` (soft-private): hidden from
+    // editor autocomplete and from normal external `.field` access, but still
+    // reachable at runtime via element access (e.g. `builder['_noSync']`) for
+    // internal tooling/tests. Not meant to be mutated by end users.
     _type;
     _default = undefined;
     _hasDefault = false;
@@ -5444,6 +5476,7 @@ class FieldBuilder {
     _static = false;
     _stream = false;
     _optional = false;
+    _noSync = false;
     _streamPriority = undefined;
     constructor(type) {
         this._type = type;
@@ -5494,6 +5527,30 @@ class FieldBuilder {
         this._static = true;
         return this;
     }
+    /**
+     * Mark this field as **local-only** — it is typed and initialized on the
+     * instance (so `.default()` and the inferred instance type still apply),
+     * but is never registered for synchronization: it never enters change
+     * tracking, never goes over the wire, and decoders never receive it.
+     *
+     * Useful for server-side scratch state, per-peer UI state, or values you
+     * want on the class for typing convenience without paying any sync cost.
+     *
+     * Mutually exclusive with the sync-only modifiers (`.view()`, `.owned()`,
+     * `.unreliable()`, `.transient()`, `.static()`, `.stream()`) — combining
+     * them throws at `schema()` time.
+     *
+     * ```ts
+     * const Player = schema({
+     *     hp: t.uint8().default(100),          // synchronized
+     *     lastInputTick: t.number().noSync(),  // local-only
+     * }, 'Player');
+     * ```
+     */
+    noSync() {
+        this._noSync = true;
+        return this;
+    }
     /**
      * Opt a collection field into priority-batched streaming delivery —
      * ADDs drain at most `maxPerTick` per tick per view (or per broadcast
@@ -5548,6 +5605,11 @@ class FieldBuilder {
         this._optional = true;
         return this;
     }
+    /**
+     * @internal — snapshot of the builder's configuration consumed by
+     * `schema()`. `private` keeps it out of autocomplete; internal callers
+     * reach it via element access (`builder['toDefinition']()`).
+     */
     toDefinition() {
         return {
             type: this._type,
@@ -5562,6 +5624,7 @@ class FieldBuilder {
             static: this._static,
             stream: this._stream,
             optional: this._optional,
+            noSync: this._noSync,
             streamPriority: this._streamPriority,
         };
     }
@@ -5577,7 +5640,8 @@ function primitive(name) {
 }
 function resolveChild(child) {
     if (isBuilder(child)) {
-        return child._type;
+        // `_type` is private; element access bypasses the visibility check.
+        return child['_type'];
     }
     return child;
 }
@@ -5587,7 +5651,7 @@ const setFactory = ((child) => new FieldBuilder({ set: resolveChild(child) }));
 const collectionFactory = ((child) => new FieldBuilder({ collection: resolveChild(child) }));
 const streamFactory = ((child) => {
     const b = new FieldBuilder({ stream: resolveChild(child) });
-    b._stream = true;
+    b['_stream'] = true; // element access bypasses `private`
     return b;
 });
 const refFactory = ((ctor) => new FieldBuilder(ctor));
@@ -6016,6 +6080,36 @@ function deprecated(throws = true) {
         });
     };
 }
+/**
+ * Produce the auto-instantiated construction default for a builder type
+ * (empty collection or zero-arg Schema ref), or `undefined` when the type
+ * has no auto-default. Shared by synced and `.noSync()` field handling.
+ */
+function autoInstantiateDefault(rawType) {
+    if (rawType && typeof rawType === "object") {
+        if (rawType.array !== undefined) {
+            return new ArraySchema();
+        }
+        if (rawType.map !== undefined) {
+            return new MapSchema();
+        }
+        if (rawType.set !== undefined) {
+            return new SetSchema();
+        }
+        if (rawType.collection !== undefined) {
+            return new CollectionSchema();
+        }
+        if (rawType.stream !== undefined) {
+            return new StreamSchema();
+        }
+    }
+    else if (typeof rawType === "function" && Schema.is(rawType)) {
+        if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
+            return new rawType();
+        }
+    }
+    return undefined;
+}
 /**
  * Define a Schema class declaratively.
  *
@@ -6051,7 +6145,28 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
     for (const fieldName in fieldsAndMethods) {
         const value = fieldsAndMethods[fieldName];
         if (isBuilder(value)) {
-            const def = value.toDefinition();
+            const def = value['toDefinition'](); // private; element access bypasses visibility
+            if (def.noSync) {
+                // Local-only field: skip metadata registration entirely so it is
+                // never encoded/decoded, but still seed its construction default
+                // (honoring `.default()` and collection/ref auto-instantiation).
+                if (def.view !== undefined || def.owned || def.unreliable ||
+                    def.transient || def.static || def.stream) {
+                    throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .noSync() ` +
+                        `together with a sync-only modifier (.view/.owned/.unreliable/.transient/.static/.stream). ` +
+                        `A local-only field cannot be synchronized.`);
+                }
+                if (def.hasDefault) {
+                    defaultValues[fieldName] = def.default;
+                }
+                else if (!def.optional) {
+                    const autoDefault = autoInstantiateDefault(def.type);
+                    if (autoDefault !== undefined) {
+                        defaultValues[fieldName] = autoDefault;
+                    }
+                }
+                continue;
+            }
             fields[fieldName] = getNormalizedType(def.type);
             if (def.view !== undefined) {
                 viewTagFields[fieldName] = def.view;
@@ -6086,28 +6201,9 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             else if (!def.optional) {
                 // Auto-instantiate collection/Schema defaults when none is provided.
                 // `.optional()` opts out — field starts as undefined.
-                const rawType = def.type;
-                if (rawType && typeof rawType === "object") {
-                    if (rawType.array !== undefined) {
-                        defaultValues[fieldName] = new ArraySchema();
-                    }
-                    else if (rawType.map !== undefined) {
-                        defaultValues[fieldName] = new MapSchema();
-                    }
-                    else if (rawType.set !== undefined) {
-                        defaultValues[fieldName] = new SetSchema();
-                    }
-                    else if (rawType.collection !== undefined) {
-                        defaultValues[fieldName] = new CollectionSchema();
-                    }
-                    else if (rawType.stream !== undefined) {
-                        defaultValues[fieldName] = new StreamSchema();
-                    }
-                }
-                else if (typeof rawType === "function" && Schema.is(rawType)) {
-                    if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
-                        defaultValues[fieldName] = new rawType();
-                    }
+                const autoDefault = autoInstantiateDefault(def.type);
+                if (autoDefault !== undefined) {
+                    defaultValues[fieldName] = autoDefault;
                 }
             }
         }
@@ -7346,8 +7442,19 @@ class Encoder {
         // selected element is passed to `view.add()` which populates
         // view.changes with the stream-link ADD + element-field ADDs.
         this._emitStreamPriority(view);
-        // encode visibility-triggered changes collected by view.add()
-        for (const [refId, changes] of view.changes) {
+        //
+        // `view.changes` Map insertion order IS topological order:
+        //   - `view.add` walks the parent chain to root via `addParentOf`
+        //     (depth-first ancestor-first), inserting every ancestor's
+        //     entry before the descendant's.
+        //   - `view.remove` calls `_touchAncestorsOf` before its own
+        //     write to insert any missing ancestors at the front of the
+        //     chain — empty entries that get skipped by the size==0
+        //     check below but establish Map position.
+        // No per-encode topo sort needed.
+        //
+        for (const refId of view.changes.keys()) {
+            const changes = view.changes.get(refId);
             const changeTree = this.root.changeTrees[refId];
             if (changeTree === undefined) {
                 // detached instance, remove from view and skip.
@@ -8108,6 +8215,31 @@ Reflection.decode = function (bytes, it) {
     const state = new (typeContext.get(reflection.rootType || 0))();
     return new Decoder(state, typeContext);
 };
+Reflection.makeEncodable = function (ctor) {
+    const metadata = ctor[Symbol.metadata];
+    if (!metadata)
+        return ctor;
+    const numFields = metadata[$numFields];
+    if (numFields === undefined)
+        return ctor;
+    // Walk every field index across the inheritance chain. Repeat calls
+    // are cheap: defineField overwrites the same descriptor and re-stamps
+    // the same `metadata[$encoders]` slot (idempotent).
+    for (let i = 0; i <= numFields; i++) {
+        const field = metadata[i];
+        if (!field)
+            continue;
+        Metadata.defineField(ctor, metadata, i, field.name, field.type);
+    }
+    // Invalidate any cached encode descriptor — `getEncodeDescriptor`
+    // memoizes on the constructor. If something already constructed it
+    // (e.g. a prior `InputEncoder(...)` call that threw), drop the stale
+    // entry so the next read sees the upgraded metadata.
+    if (Object.prototype.hasOwnProperty.call(ctor, $encodeDescriptor)) {
+        delete ctor[$encodeDescriptor];
+    }
+    return ctor;
+};
 
 /**
  * Legacy callback system
@@ -8724,6 +8856,7 @@ const Callbacks = {
         else if ('decoder' in roomOrDecoder.serializer) {
             return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
         }
+        throw new Error('Invalid room or decoder');
     },
     getRawChanges(decoder, callback) {
         return getRawChangesCallback(decoder, callback);
@@ -9179,12 +9312,27 @@ class StateView {
         if (!this.isVisible(changeTree)) {
             // view must have all "changeTree" parent tree
             this.markVisible(changeTree);
-            // add parent's parent
+            // Recurse all the way to the root regardless of whether the
+            // parent is filtered. Walking the full chain is what makes
+            // `view.changes` topologically ordered by construction — any
+            // filtered ancestor up the chain is touched here, before the
+            // descendant's entry. The actual entry-write below is gated
+            // on `hasFilteredFields` so non-filtered ancestors don't
+            // emit redundant wire bytes (the decoder already knows them
+            // via the shared encode pass). Marking them visible is
+            // still useful: it makes this short-circuit fire on the next
+            // `view.add` instead of re-walking the chain.
             const parentChangeTree = changeTree.parent?.[$changes];
-            if (parentChangeTree && parentChangeTree.hasFilteredFields) {
+            if (parentChangeTree) {
                 this.addParentOf(changeTree, tag);
             }
         }
+        // Skip the entry-write for non-filtered ancestors: their refIds
+        // are already known to the decoder through the shared pass, and
+        // an extra ADD on a non-filtered field's index would only emit
+        // bytes for a no-op (`value === previousValue` on the decoder).
+        if (!changeTree.hasFilteredFields)
+            return;
         // add parent's tag properties
         if (changeTree.getChange(parentIndex) !== exports.OPERATION.DELETE) {
             let changes = this.changes.get(changeTree.ref[$refId]);
@@ -9196,6 +9344,45 @@ class StateView {
             changes.set(parentIndex, exports.OPERATION.ADD);
         }
     }
+    /**
+     * Walk `tree`'s parent chain to root and insert an empty entry into
+     * `view.changes` for any ancestor not already present. Empty entries
+     * are skipped by `encodeView` (`changes.size === 0` continue), so no
+     * wire bytes are emitted — but the Map's insertion order now puts
+     * each ancestor BEFORE the descendant entry that the caller is about
+     * to write. Combined with `addParentOf`'s full-recursion walk on
+     * `view.add`, this preserves the global invariant that
+     * `view.changes` iteration order is topological.
+     *
+     * Iterative (not recursive) so the stack is bounded by tree depth
+     * regardless of call patterns. Stops the walk as soon as it hits an
+     * ancestor that's already in `view.changes` — at that point the
+     * remainder of the chain is guaranteed to also be present (invariant
+     * upheld by every prior caller).
+     */
+    _touchAncestorsOf(tree) {
+        let cursor = tree.parent?.[$changes];
+        if (cursor === undefined)
+            return;
+        // Collect the missing prefix of the chain, deepest-first. Only
+        // FILTERED ancestors need entries — non-filtered ones never
+        // appear in `view.changes` (mirrors the addParentOf gate), so
+        // they don't need a Map slot reserved either.
+        const stack = [];
+        while (cursor !== undefined) {
+            if (cursor.hasFilteredFields) {
+                const refId = cursor.ref[$refId];
+                if (this.changes.has(refId))
+                    break;
+                stack.push(cursor);
+            }
+            cursor = cursor.parent?.[$changes];
+        }
+        // Insert root-first so Map order is topological.
+        for (let i = stack.length - 1; i >= 0; i--) {
+            this.changes.set(stack[i].ref[$refId], new Map());
+        }
+    }
     remove(obj, tag = DEFAULT_VIEW_TAG, _isClear = false) {
         const changeTree = obj[$changes];
         if (!changeTree) {
@@ -9256,6 +9443,11 @@ class StateView {
         const ref = changeTree.ref;
         const metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
         const refId = ref[$refId];
+        // Pre-insert any missing ancestors into view.changes so the Map's
+        // iteration order stays topological — the entries we're about to
+        // write (either on this obj, or on its parent collection below)
+        // must come AFTER every ancestor in the chain on the wire.
+        this._touchAncestorsOf(changeTree);
         let changes = this.changes.get(refId);
         if (changes === undefined) {
             changes = new Map();