@colyseus/schema 5.0.2 → 5.0.4

package/build/index.js

@@ -1218,6 +1218,33 @@
         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;
@@ -1255,17 +1282,7 @@
                 });
             }
             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;
@@ -2097,11 +2114,24 @@
             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)));
         }
     }
 
@@ -5434,8 +5464,10 @@
      */
     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;
@@ -5448,6 +5480,7 @@
         _static = false;
         _stream = false;
         _optional = false;
+        _noSync = false;
         _streamPriority = undefined;
         constructor(type) {
             this._type = type;
@@ -5498,6 +5531,30 @@
             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
@@ -5552,6 +5609,11 @@
             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,
@@ -5566,6 +5628,7 @@
                 static: this._static,
                 stream: this._stream,
                 optional: this._optional,
+                noSync: this._noSync,
                 streamPriority: this._streamPriority,
             };
         }
@@ -5581,7 +5644,8 @@
     }
     function resolveChild(child) {
         if (isBuilder(child)) {
-            return child._type;
+            // `_type` is private; element access bypasses the visibility check.
+            return child['_type'];
         }
         return child;
     }
@@ -5591,7 +5655,7 @@
     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));
@@ -6020,6 +6084,36 @@
             });
         };
     }
+    /**
+     * 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.
      *
@@ -6055,7 +6149,28 @@
         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;
@@ -6090,28 +6205,9 @@
                 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;
                     }
                 }
             }
@@ -7350,8 +7446,19 @@
             // 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.
@@ -8112,6 +8219,31 @@
         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
@@ -8728,6 +8860,7 @@
             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);
@@ -9183,12 +9316,27 @@
             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]);
@@ -9200,6 +9348,45 @@
                 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) {
@@ -9260,6 +9447,11 @@
             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();