@colyseus/schema 5.0.4 → 5.0.6

package/build/types/HelperTypes.d.ts

@@ -97,6 +97,28 @@ export type ToJSON<T> = NonFunctionProps<{
 } & {
     [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
 }>;
+/**
+ * The plain DATA shape of a Schema instance type `T`: its synchronized fields
+ * with all `Schema` machinery stripped (`assign`, `clone`, `toJSON`, the
+ * change-tracking state, the internal symbol keys, …), so a plain object literal
+ * satisfies it. Field types — including narrowed primitives like
+ * `t.int8<-1 | 0 | 1>()` — are preserved exactly.
+ *
+ * Use it to type code that operates on schema-shaped *plain objects* rather than
+ * decoded instances: deterministic simulation / physics steps, synthesized or
+ * buffered input commands, plain DTOs, etc.
+ *
+ * ```ts
+ * function applyInput(state: Player, cmd: Data<MoveInput>) { … }
+ * applyInput(player, { moveX: 1, jump: false, dt });   // plain literal — OK
+ * ```
+ *
+ * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
+ * structural projection: nested Schema / collection fields keep their instance
+ * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
+ * `NonFunctionProps` pass leaves behind.
+ */
+export type Data<T> = Omit<T, keyof Schema>;
 export type IsNever<T> = [T] extends [never] ? true : false;
 /**
  * Type helper for .assign() method - allows assigning values in a flexible way

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.6",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -71,7 +71,7 @@ export { t, FieldBuilder, isBuilder, type BuilderDefinition, type ChildType } fr
 export { TypeContext } from "./types/TypeContext.js";
 
 // Helper types for type inference
-export type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderInitProps } from "./types/HelperTypes.js";
+export type { InferValueType, InferSchemaInstanceType, AssignableProps, BuilderInitProps, Data } from "./types/HelperTypes.js";
 
 export { getDecoderStateCallbacks, type CallbackProxy, type SchemaCallback, type CollectionCallback, type SchemaCallbackProxy } from "./decoder/strategy/getDecoderStateCallbacks.js";
 export { Callbacks, StateCallbackStrategy } from "./decoder/strategy/Callbacks.js";

package/src/types/HelperTypes.ts

@@ -143,6 +143,29 @@ export type ToJSON<T> = NonFunctionProps<
     & { [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>> }
 >;
 
+/**
+ * The plain DATA shape of a Schema instance type `T`: its synchronized fields
+ * with all `Schema` machinery stripped (`assign`, `clone`, `toJSON`, the
+ * change-tracking state, the internal symbol keys, …), so a plain object literal
+ * satisfies it. Field types — including narrowed primitives like
+ * `t.int8<-1 | 0 | 1>()` — are preserved exactly.
+ *
+ * Use it to type code that operates on schema-shaped *plain objects* rather than
+ * decoded instances: deterministic simulation / physics steps, synthesized or
+ * buffered input commands, plain DTOs, etc.
+ *
+ * ```ts
+ * function applyInput(state: Player, cmd: Data<MoveInput>) { … }
+ * applyInput(player, { moveX: 1, jump: false, dt });   // plain literal — OK
+ * ```
+ *
+ * Unlike {@link ToJSON} (a recursive *serialization* shape), this is a flat
+ * structural projection: nested Schema / collection fields keep their instance
+ * types, and it does not retain the non-method `Schema` members that `ToJSON`'s
+ * `NonFunctionProps` pass leaves behind.
+ */
+export type Data<T> = Omit<T, keyof Schema>;
+
 // Helper type to check if T is exactly 'never' (meaning no InitProps was provided)
 export type IsNever<T> = [T] extends [never] ? true : false;
 

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.