@colyseus/schema 5.0.3 → 5.0.5

package/src/types/builder.ts

@@ -27,6 +27,8 @@ export interface BuilderDefinition {
     static?: boolean;
     stream?: boolean;
     optional?: boolean;
+    /** Local-only field: typed + initialized, but never registered for sync. */
+    noSync?: boolean;
     /** Declaration-scope priority callback for `.stream()` fields. */
     streamPriority?: (view: any, element: any) => number;
 }
@@ -64,21 +66,24 @@ export class FieldBuilder<
 > {
     readonly [$builder]: true = true;
 
-    // Internal configuration. Public so schema() and tests can read it, but not
-    // meant to be mutated by users directly.
-    _type: DefinitionType;
-    _default: any = undefined;
-    _hasDefault = false;
-    _view: number | undefined = undefined;
-    _owned = false;
-    _unreliable = false;
-    _transient = false;
-    _deprecated = false;
-    _deprecatedThrows = true;
-    _static = false;
-    _stream = false;
-    _optional = false;
-    _streamPriority: ((view: any, element: any) => number) | undefined = undefined;
+    // 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.
+    private _type: DefinitionType;
+    private _default: any = undefined;
+    private _hasDefault = false;
+    private _view: number | undefined = undefined;
+    private _owned = false;
+    private _unreliable = false;
+    private _transient = false;
+    private _deprecated = false;
+    private _deprecatedThrows = true;
+    private _static = false;
+    private _stream = false;
+    private _optional = false;
+    private _noSync = false;
+    private _streamPriority: ((view: any, element: any) => number) | undefined = undefined;
 
     constructor(type: DefinitionType) {
         this._type = type;
@@ -136,6 +141,31 @@ export class FieldBuilder<
         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 {
+        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
@@ -194,7 +224,12 @@ export class FieldBuilder<
         return this as unknown as FieldBuilder<T | undefined, HasDefault, true>;
     }
 
-    toDefinition(): BuilderDefinition {
+    /**
+     * @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']()`).
+     */
+    private toDefinition(): BuilderDefinition {
         return {
             type: this._type,
             default: this._default,
@@ -208,6 +243,7 @@ export class FieldBuilder<
             static: this._static,
             stream: this._stream,
             optional: this._optional,
+            noSync: this._noSync,
             streamPriority: this._streamPriority,
         };
     }
@@ -221,8 +257,33 @@ export function isBuilder(value: any): value is FieldBuilder<any> {
 // Factory helpers
 // ---------------------------------------------------------------------------
 
-function primitive<T>(name: RawPrimitiveType): () => FieldBuilder<T> {
-    return () => new FieldBuilder<T>(name);
+/**
+ * Primitive field factory. Calling it bare (`t.int8()`) yields the natural type
+ * for the wire codec (`number` for the int/float formats, plus `string` /
+ * `boolean` / `bigint`). Pass an explicit type argument to refine the inferred
+ * value at the TYPE level, while the wire encoding is unchanged:
+ *
+ *     moveX: t.int8<-1 | 0 | 1>(),       // typed -1|0|1, still encoded as int8
+ *     team:  t.string<"red" | "blue">(),
+ *
+ * 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).
+ *
+ * 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
+ * bytes arrive. Sound for server-authored state; for INPUT schemas the value
+ * comes from an untrusted client (the type reads `-1|0|1` while a peer can send
+ * any int8), so keep validating/clamping on the receiving side.
+ */
+interface PrimitiveFactory<TBase> {
+    (): FieldBuilder<TBase>;
+    <T extends TBase>(): FieldBuilder<T>;
+}
+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.
@@ -233,7 +294,8 @@ export type ChildType =
 
 function resolveChild(child: ChildType): DefinitionType {
     if (isBuilder(child)) {
-        return child._type;
+        // `_type` is private; element access bypasses the visibility check.
+        return child['_type'];
     }
     return child as DefinitionType;
 }
@@ -283,7 +345,7 @@ const collectionFactory: CollectionFactory = ((child: ChildType) =>
     new FieldBuilder({ collection: resolveChild(child) } as DefinitionType)) as CollectionFactory;
 const streamFactory: StreamFactory = ((child: ChildType) => {
     const b = new FieldBuilder({ stream: resolveChild(child) } as DefinitionType);
-    b._stream = true;
+    b['_stream'] = true; // element access bypasses `private`
     return b;
 }) as StreamFactory;