@colyseus/schema 5.0.3 → 5.0.5

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

@@ -2110,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)));
     }
 }
 
@@ -5447,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;
@@ -5461,6 +5476,7 @@ class FieldBuilder {
     _static = false;
     _stream = false;
     _optional = false;
+    _noSync = false;
     _streamPriority = undefined;
     constructor(type) {
         this._type = type;
@@ -5511,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
@@ -5565,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,
@@ -5579,6 +5624,7 @@ class FieldBuilder {
             static: this._static,
             stream: this._stream,
             optional: this._optional,
+            noSync: this._noSync,
             streamPriority: this._streamPriority,
         };
     }
@@ -5586,15 +5632,13 @@ class FieldBuilder {
 function isBuilder(value) {
     return value != null && value[$builder] === true;
 }
-// ---------------------------------------------------------------------------
-// Factory helpers
-// ---------------------------------------------------------------------------
 function primitive(name) {
-    return () => new FieldBuilder(name);
+    return (() => new FieldBuilder(name));
 }
 function resolveChild(child) {
     if (isBuilder(child)) {
-        return child._type;
+        // `_type` is private; element access bypasses the visibility check.
+        return child['_type'];
     }
     return child;
 }
@@ -5604,7 +5648,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));
@@ -6033,6 +6077,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.
  *
@@ -6068,7 +6142,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;
@@ -6103,28 +6198,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;
                 }
             }
         }
@@ -7363,8 +7439,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.
@@ -8766,6 +8853,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);
@@ -9221,12 +9309,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]);
@@ -9238,6 +9341,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) {
@@ -9298,6 +9440,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();