@colyseus/schema 5.0.5 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.5",
+  "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;