@typeonce/ritmo-math 0.11.0 → 0.13.0

package/src/Scalar.ts

@@ -36,13 +36,14 @@
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
 import * as internal from "./internal/scalar.ts"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import type * as Result from "@typeonce/ritmo/Result"
 
 /**
  * Finite number brand.
  *
  * Values of this type are guaranteed not to be `NaN`, `Infinity`, or
- * `-Infinity` when they come from a validator (`result`, `decode`). The
+ * `-Infinity` when they come from a constructor (`result`, `option`) or a `codec`. The
  * arithmetic helpers here and in `Vector2` keep the brand without
  * re-validating, so their results are finite only while they stay within
  * `±Number.MAX_VALUE`: game-sized values never come close, but validate
@@ -85,27 +86,46 @@ export type InterpolationError = {
   readonly end: number
 }
 
+/**
+ * The constructors, guard, and schema of one scalar brand.
+ *
+ * @category Constructors
+ */
+export interface Constructor<Value> {
+  /** Validates one number and returns an explicit success/failure result. */
+  readonly result: (raw: number) => Result.Result<Value, Error>
+  /** Validates one number and returns `null` on failure. */
+  readonly option: (raw: number) => Value | null
+  /** Whether any value is a number of this brand. */
+  readonly is: (raw: unknown) => raw is Value
+  /** The Standard Schema for `Descriptor.ConstructedComponent(...)`: the saved form is the number itself. */
+  readonly codec: StandardSchema<number, Value>
+}
+
 /**
  * Constructor for {@link Finite}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.Finite.codec)`.
  *
  * @category Constructors
  */
-export const Finite = internal.Finite
+export const Finite: Constructor<Finite> = internal.Finite
 /**
  * Constructor for {@link NonNegative}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.NonNegative.codec)`.
  *
  * @category Constructors
  */
-export const NonNegative = internal.NonNegative
+export const NonNegative: Constructor<NonNegative> = internal.NonNegative
 /**
  * Constructor for {@link Positive}: `result` (explicit failure), `option`
- * (`null` on failure), and `is` (a type guard).
+ * (`null` on failure), `is` (a type guard), and `codec`, for
+ * `Descriptor.ConstructedComponent(Scalar.Positive.codec)`.
  *
  * @category Constructors
  */
-export const Positive = internal.Positive
+export const Positive: Constructor<Positive> = internal.Positive
 
 /**
  * Clamps one finite value between two finite bounds.

package/src/Size2.ts

@@ -31,6 +31,7 @@
  * Pure readers and raw views over already-validated size values.
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import * as internal from "./internal/size2.ts"
 import type * as Result from "@typeonce/ritmo/Result"
 import type * as Scalar from "./Scalar.ts"
@@ -67,16 +68,6 @@ export type Error = {
   readonly input: Raw
 }
 
-/**
- * Failure produced by `decode` when the input does not have the raw shape.
- *
- * @category Size Types
- */
-export type DecodeError = {
-  readonly tag: "Size2/Malformed"
-  readonly input: unknown
-}
-
 /**
  * Validates one raw size and returns an explicit result.
  *
@@ -84,13 +75,20 @@ export type DecodeError = {
  */
 export const result: (raw: Raw) => Result.Result<Size2, Error> = internal.result
 /**
- * Validates untrusted input of any shape, for example a value read from a
- * save file. Descriptors built from this module use it when restoring
- * snapshots.
+ * The codec of `Size2` (a Standard Schema, see `Descriptor.Codec`): give it to
+ * `Descriptor.ConstructedComponent(...)` so raw input and saves are validated.
+ * Its saved form is the raw shape, so it needs no `encode`. To put a `Size2`
+ * inside your own object schema, use {@link is} with your library's guard
+ * schema (`Schema.declare`, `z.custom`).
+ *
+ * @example
+ * ```ts
+ * const Position = Descriptor.ConstructedComponent(Size2.codec)("Game/Position")
+ * ```
  *
  * @category Construction
  */
-export const decode: (raw: unknown) => Result.Result<Size2, Error | DecodeError> = internal.decode
+export const codec: StandardSchema<Raw, Size2> = internal.codec
 /**
  * Validates one raw size and returns `null` on failure.
  *
@@ -98,11 +96,12 @@ export const decode: (raw: unknown) => Result.Result<Size2, Error | DecodeError>
  */
 export const option: (raw: Raw) => Size2 | null = internal.option
 /**
- * Checks whether one raw size already satisfies the size invariants.
+ * Whether any value is a valid `Size2`: a guard, also for building a
+ * `Size2` field in your own schema (`Schema.declare(Size2.is)`).
  *
  * @category Construction
  */
-export const is: (raw: Raw) => raw is Raw & Size2 = internal.is
+export const is: (raw: unknown) => raw is Size2 = internal.is
 /**
  * Converts one branded size back to a fresh raw object.
  *

package/src/Vector2.ts

@@ -36,6 +36,7 @@
  * Immutable vector math and normalization helpers on already-validated values.
  */
 import type * as Brand from "@typeonce/ritmo/Brand"
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
 import * as internal from "./internal/vector2.ts"
 import type * as Result from "@typeonce/ritmo/Result"
 import type * as Scalar from "./Scalar.ts"
@@ -72,16 +73,6 @@ export type Error = {
   readonly input: Raw
 }
 
-/**
- * Failure produced by `decode` when the input does not have the raw shape.
- *
- * @category Vector Types
- */
-export type DecodeError = {
-  readonly tag: "Vector2/Malformed"
-  readonly input: unknown
-}
-
 /**
  * Explicit failure produced when a zero-length vector cannot be normalized.
  *
@@ -103,13 +94,20 @@ export type NormalizeError = {
  */
 export const result: (raw: Raw) => Result.Result<Vector2, Error> = internal.result
 /**
- * Validates untrusted input of any shape, for example a value read from a
- * save file. Descriptors built from this module use it when restoring
- * snapshots.
+ * The codec of `Vector2` (a Standard Schema, see `Descriptor.Codec`): give it to
+ * `Descriptor.ConstructedComponent(...)` so raw input and saves are validated.
+ * Its saved form is the raw shape, so it needs no `encode`. To put a `Vector2`
+ * inside your own object schema, use {@link is} with your library's guard
+ * schema (`Schema.declare`, `z.custom`).
+ *
+ * @example
+ * ```ts
+ * const Position = Descriptor.ConstructedComponent(Vector2.codec)("Game/Position")
+ * ```
  *
  * @category Construction
  */
-export const decode: (raw: unknown) => Result.Result<Vector2, Error | DecodeError> = internal.decode
+export const codec: StandardSchema<Raw, Vector2> = internal.codec
 /**
  * Validates one raw vector and returns `null` on failure.
  *
@@ -117,11 +115,12 @@ export const decode: (raw: unknown) => Result.Result<Vector2, Error | DecodeErro
  */
 export const option: (raw: Raw) => Vector2 | null = internal.option
 /**
- * Checks whether one raw vector already satisfies the vector invariants.
+ * Whether any value is a valid `Vector2`: a guard, also for building a
+ * `Vector2` field in your own schema (`Schema.declare(Vector2.is)`).
  *
  * @category Construction
  */
-export const is: (raw: Raw) => raw is Raw & Vector2 = internal.is
+export const is: (raw: unknown) => raw is Vector2 = internal.is
 /**
  * Converts one branded vector back to a fresh raw object.
  *

package/src/index.ts

@@ -2,9 +2,9 @@
  * Math for game code.
  *
  * Validated values (`Scalar`, `Vector2`, `Size2`, `Aabb`) expose
- * Result-returning constructors, so they plug into
- * `Descriptor.ConstructedComponent(...)` / `ConstructedResource(...)` and are
- * validated once at the boundary. `InputAxis` normalizes directional input.
+ * Result-returning constructors, a guard (`is`), and one `codec` each, so
+ * they plug into `Descriptor.ConstructedComponent(Vector2.codec)` /
+ * `ConstructedResource(Random.codec)` and are validated once at the boundary. `InputAxis` normalizes directional input.
  *
  * Hot-path helpers work on plain numbers every frame: `Vec2` arithmetic,
  * `Box2` edges, `Collide2` swept circle collision, a `SpatialGrid` broad

package/src/internal/aabb.ts

@@ -1,3 +1,4 @@
+import { codecOf } from "./codec.ts"
 import * as Result from "@typeonce/ritmo/Result"
 import * as Size2 from "../Size2.ts"
 import * as Vector2 from "../Vector2.ts"
@@ -36,7 +37,7 @@ export const option = (raw: Aabb.Raw): Aabb.Aabb | null => {
   return next.ok ? next.value : null
 }
 
-export const is = (raw: Aabb.Raw): raw is Aabb.Raw & Aabb.Aabb => result(raw).ok
+export const is = (raw: unknown): raw is Aabb.Aabb => decode(raw).ok
 
 export const position = (aabb: Aabb.Aabb): Vector2.Vector2 => aabb.position
 export const size = (aabb: Aabb.Aabb): Size2.Size2 => aabb.size
@@ -66,10 +67,15 @@ export const overlapsVertically = (first: Aabb.Aabb, second: Aabb.Aabb): boolean
 export const translate = (aabb: Aabb.Aabb, delta: Vector2.Vector2): Aabb.Aabb =>
   make(Vector2.add(aabb.position, delta), aabb.size)
 
-export const decode = (raw: unknown): Result.Result<Aabb.Aabb, Aabb.Error | Aabb.DecodeError> => {
+/** Untrusted input without the raw shape. */
+type Malformed = { readonly tag: "Aabb/Malformed"; readonly input: unknown }
+
+export const decode = (raw: unknown): Result.Result<Aabb.Aabb, Aabb.Error | Malformed> => {
   if (typeof raw !== "object" || raw === null) return Result.failure({ tag: "Aabb/Malformed", input: raw })
   const { position, size } = raw as Record<string, unknown>
   return isVector2Shape(position) && isSize2Shape(size)
     ? result({ position, size })
     : Result.failure({ tag: "Aabb/Malformed", input: raw })
 }
+
+export const codec = codecOf<Aabb.Raw, Aabb.Aabb>(decode, "a box { x, y, width, height } of finite numbers with a non-negative size")

package/src/internal/codec.ts

@@ -0,0 +1,21 @@
+import type { StandardSchema } from "@typeonce/ritmo/Descriptor"
+import type * as Result from "@typeonce/ritmo/Result"
+
+/**
+ * The codec of one math type, from its decode: a Standard Schema whose saved
+ * form is the raw shape. The value is already plain data, so it needs no
+ * `encode`.
+ */
+export const codecOf = <Raw, Value>(
+  decode: (raw: unknown) => Result.Result<Value, unknown>,
+  expected: string
+): StandardSchema<Raw, Value> => ({
+  "~standard": {
+    version: 1,
+    vendor: "ritmo-math",
+    validate: (raw) => {
+      const value = decode(raw)
+      return value.ok ? { value: value.value } : { issues: [{ message: `Expected ${expected}` }] }
+    }
+  }
+})

package/src/internal/scalar.ts

@@ -1,18 +1,33 @@
-import * as Brand from "@typeonce/ritmo/Brand"
 import * as Result from "@typeonce/ritmo/Result"
 import type * as Scalar from "../Scalar.ts"
+import { codecOf } from "./codec.ts"
 
-const finiteBrand = Brand.refine<Scalar.Finite, number, Scalar.Error>((value) =>
+// A branded number's constructors, guard, and codec, from its check.
+const refine = <Value extends number>(
+  validate: (raw: number) => Result.Result<Value, Scalar.Error>,
+  expected: string
+): Scalar.Constructor<Value> => ({
+  result: validate,
+  option: (raw) => {
+    const result = validate(raw)
+    return result.ok ? result.value : null
+  },
+  is: (raw): raw is Value => typeof raw === "number" && validate(raw).ok,
+  codec: codecOf<number, Value>((raw) => typeof raw === "number" ? validate(raw) : Result.failure(raw), expected)
+})
+
+export const Finite = refine<Scalar.Finite>((value) =>
   Number.isFinite(value)
     ? Result.success(value as Scalar.Finite)
     : Result.failure({
         tag: "Scalar/NotFinite",
         value
-      })
+      }),
+  "a finite number"
 )
 
-const nonNegativeBrand = Brand.refine<Scalar.NonNegative, number, Scalar.Error>((value) => {
-  const finite = finiteBrand.result(value)
+export const NonNegative = refine<Scalar.NonNegative>((value) => {
+  const finite = Finite.result(value)
   if (!finite.ok) {
     return finite
   }
@@ -23,10 +38,10 @@ const nonNegativeBrand = Brand.refine<Scalar.NonNegative, number, Scalar.Error>(
         tag: "Scalar/Negative",
         value
       })
-})
+}, "a finite number, 0 or more")
 
-const positiveBrand = Brand.refine<Scalar.Positive, number, Scalar.Error>((value) => {
-  const finite = finiteBrand.result(value)
+export const Positive = refine<Scalar.Positive>((value) => {
+  const finite = Finite.result(value)
   if (!finite.ok) {
     return finite
   }
@@ -37,11 +52,7 @@ const positiveBrand = Brand.refine<Scalar.Positive, number, Scalar.Error>((value
         tag: "Scalar/NonPositive",
         value
       })
-})
-
-export const Finite = finiteBrand
-export const NonNegative = nonNegativeBrand
-export const Positive = positiveBrand
+}, "a finite number above 0")
 
 export const clamp = (value: number, min: number, max: number): Scalar.Finite =>
   Math.min(Math.max(value, min), max) as Scalar.Finite

package/src/internal/size2.ts

@@ -1,3 +1,4 @@
+import { codecOf } from "./codec.ts"
 import * as Result from "@typeonce/ritmo/Result"
 import * as Scalar from "../Scalar.ts"
 import type * as Size2 from "../Size2.ts"
@@ -28,7 +29,7 @@ export const option = (raw: Size2.Raw): Size2.Size2 | null => {
   return next.ok ? next.value : null
 }
 
-export const is = (raw: Size2.Raw): raw is Size2.Raw & Size2.Size2 => result(raw).ok
+export const is = (raw: unknown): raw is Size2.Size2 => decode(raw).ok
 
 export const toRaw = (size: Size2.Size2): Size2.Raw => ({
   width: size.width,
@@ -44,5 +45,10 @@ export const height = (size: Size2.Size2): Scalar.NonNegative => size.height
 export const isRawShape = (raw: unknown): raw is Size2.Raw =>
   typeof raw === "object" && raw !== null && typeof (raw as Record<string, unknown>)["width"] === "number" && typeof (raw as Record<string, unknown>)["height"] === "number"
 
-export const decode = (raw: unknown): Result.Result<Size2.Size2, Size2.Error | Size2.DecodeError> =>
+/** Untrusted input without the raw shape. */
+type Malformed = { readonly tag: "Size2/Malformed"; readonly input: unknown }
+
+export const decode = (raw: unknown): Result.Result<Size2.Size2, Size2.Error | Malformed> =>
   isRawShape(raw) ? result(raw) : Result.failure({ tag: "Size2/Malformed", input: raw })
+
+export const codec = codecOf<Size2.Raw, Size2.Size2>(decode, "a size { width, height } of non-negative finite numbers")

package/src/internal/vector2.ts

@@ -1,3 +1,4 @@
+import { codecOf } from "./codec.ts"
 import * as Result from "@typeonce/ritmo/Result"
 import * as Scalar from "../Scalar.ts"
 import type * as Vector2 from "../Vector2.ts"
@@ -28,7 +29,7 @@ export const option = (raw: Vector2.Raw): Vector2.Vector2 | null => {
   return next.ok ? next.value : null
 }
 
-export const is = (raw: Vector2.Raw): raw is Vector2.Raw & Vector2.Vector2 => result(raw).ok
+export const is = (raw: unknown): raw is Vector2.Vector2 => decode(raw).ok
 
 export const toRaw = (vector: Vector2.Vector2): Vector2.Raw => ({
   x: vector.x,
@@ -111,5 +112,10 @@ export const normalizeXYOrZero = (x: number, y: number): {
 export const isRawShape = (raw: unknown): raw is Vector2.Raw =>
   typeof raw === "object" && raw !== null && typeof (raw as Record<string, unknown>)["x"] === "number" && typeof (raw as Record<string, unknown>)["y"] === "number"
 
-export const decode = (raw: unknown): Result.Result<Vector2.Vector2, Vector2.Error | Vector2.DecodeError> =>
+/** Untrusted input without the raw shape. */
+type Malformed = { readonly tag: "Vector2/Malformed"; readonly input: unknown }
+
+export const decode = (raw: unknown): Result.Result<Vector2.Vector2, Vector2.Error | Malformed> =>
   isRawShape(raw) ? result(raw) : Result.failure({ tag: "Vector2/Malformed", input: raw })
+
+export const codec = codecOf<Vector2.Raw, Vector2.Vector2>(decode, "a vector { x, y } of finite numbers")