@colyseus/schema 5.0.4 → 5.0.5

package/build/types/builder.d.ts

@@ -162,6 +162,31 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
     private toDefinition;
 }
 export declare function isBuilder(value: any): value is FieldBuilder<any>;
+/**
+ * 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>;
+}
 export type ChildType = RawPrimitiveType | Constructor<Schema> | FieldBuilder<any>;
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
@@ -195,21 +220,21 @@ interface RefFactory {
     <C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
 }
 export declare const t: Readonly<{
-    string: () => FieldBuilder<string, false, false>;
-    number: () => FieldBuilder<number, false, false>;
-    boolean: () => FieldBuilder<boolean, false, false>;
-    int8: () => FieldBuilder<number, false, false>;
-    uint8: () => FieldBuilder<number, false, false>;
-    int16: () => FieldBuilder<number, false, false>;
-    uint16: () => FieldBuilder<number, false, false>;
-    int32: () => FieldBuilder<number, false, false>;
-    uint32: () => FieldBuilder<number, false, false>;
-    int64: () => FieldBuilder<number, false, false>;
-    uint64: () => FieldBuilder<number, false, false>;
-    float32: () => FieldBuilder<number, false, false>;
-    float64: () => FieldBuilder<number, false, false>;
-    bigint64: () => FieldBuilder<bigint, false, false>;
-    biguint64: () => FieldBuilder<bigint, false, false>;
+    string: PrimitiveFactory<string>;
+    number: PrimitiveFactory<number>;
+    boolean: PrimitiveFactory<boolean>;
+    int8: PrimitiveFactory<number>;
+    uint8: PrimitiveFactory<number>;
+    int16: PrimitiveFactory<number>;
+    uint16: PrimitiveFactory<number>;
+    int32: PrimitiveFactory<number>;
+    uint32: PrimitiveFactory<number>;
+    int64: PrimitiveFactory<number>;
+    uint64: PrimitiveFactory<number>;
+    float32: PrimitiveFactory<number>;
+    float64: PrimitiveFactory<number>;
+    bigint64: PrimitiveFactory<bigint>;
+    biguint64: PrimitiveFactory<bigint>;
     /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
     ref: RefFactory;
     array: ArrayFactory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.4",
+  "version": "5.0.5",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {

package/src/types/builder.ts

@@ -257,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.