Add generic type narrowing to primitive field factories; v5.0.5

`t.int8<-1 | 0 | 1>()` / `t.string<"red" | "blue">()` etc. refine the
inferred field type while the wire codec is unchanged. Implemented as an
overloaded `PrimitiveFactory<TBase>` (bare call → concrete `FieldBuilder<TBase>`;
explicit type arg → `FieldBuilder<T>`) rather than a defaulted generic, which
would be captured as `any` during `schema()`'s self-referential inference.
Type-level assertion only — the decoder still writes raw bytes, so input
schemas must keep validating on receipt.

Assisted-by: Claude Opus 4.7

Author: endel

CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project are documented in this file. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [5.0.5]
+
+### Added
+- Generic type narrowing on the primitive field factories. Pass an explicit
+  type argument to `t.int8()` / `t.string()` / etc. to refine the inferred
+  field type, while the wire encoding is unchanged:
+
+  ```ts
+  const MoveInput = schema({
+      moveX: t.int8<-1 | 0 | 1>(),         // typed -1 | 0 | 1, still a 1-byte int8
+      team:  t.string<"red" | "blue">(),   // typed "red" | "blue", still a string
+  });
+  ```
+
+  Each `t.<primitive>()` now has two call signatures: the bare call returns the
+  natural type for the codec (`t.int8()` → `number`), and an explicit type
+  argument returns `FieldBuilder<T>`. This is an overload pair rather than a
+  defaulted generic (`<T extends TBase = TBase>()`): 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), so
+  the bare form must stay a concrete `FieldBuilder<TBase>`.
+
+  The refinement is a **type-level assertion only** — the wire still carries the
+  codec's full range and the decoder writes whatever bytes arrive. Sound for
+  server-authored state; for input schemas (untrusted client) keep validating /
+  clamping on receipt.
+
 ## [5.0.4]
 
 ### Added

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": {

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.