akanjs 3.1.0-rc.4 → 3.1.0-rc.6

package/base/baseEnv.ts

@@ -81,8 +81,11 @@ const globalWithPrefix = globalThis as typeof globalThis & { __AKAN_PREFIX__?: R
 export const normalizeRoutePrefix = (value: string | undefined | null): string | undefined => {
   const trimmed = value?.trim();
   if (!trimmed) return undefined;
-  const normalized = `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
-  return normalized === "/" ? undefined : normalized;
+  let start = 0;
+  let end = trimmed.length;
+  while (start < end && trimmed[start] === "/") start += 1;
+  while (end > start && trimmed[end - 1] === "/") end -= 1;
+  return start === end ? undefined : `/${trimmed.slice(start, end)}`;
 };
 
 /**

package/client/device.ts

@@ -11,7 +11,7 @@ type DebugPayload = Record<string, unknown>;
 
 const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessEnvLike };
 
-const debugSessionId = Math.random().toString(36).slice(2, 8);
+const debugSessionId = crypto.getRandomValues(new Uint32Array(1))[0].toString(36);
 let debugSeq = 0;
 
 const FRAME_TRACE_LIMIT = 2000;

package/client/frameConfig.ts

@@ -1,4 +1,4 @@
-import { isRecord } from "akanjs/common";
+import { isRecord, trimSlashes } from "akanjs/common";
 import type { PageConfig, PageSafeAreaConfig, PageState, ResponsiveInset, SsrRenderMode } from "./csrTypes";
 import { transitionTypes } from "./transitionTypes";
 
@@ -246,7 +246,7 @@ const getPlatformFrameProfile = (platform: DevicePlatform): PageConfig => {
 };
 
 const getRouteRoleFrameDefaults = (path: string, platform: DevicePlatform, basePath?: string): PageConfig => {
-  const normalizedBasePath = basePath?.replace(/^\/+|\/+$/g, "");
+  const normalizedBasePath = trimSlashes(basePath ?? "");
   const depth = path
     .split("/")
     .filter(Boolean)

package/client/router.ts

@@ -1,5 +1,5 @@
 import { getEnv } from "akanjs/base";
-import { getBasePathFromPathname, Logger, parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
+import { getBasePathFromPathname, Logger, parseAkanI18nEnv, parseBasePaths, trimSlashes } from "akanjs/common";
 import { csrLocation } from "./csrLocation";
 import { isMcpView } from "./mcpView";
 
@@ -99,7 +99,7 @@ const normalizeRoutePath = (path: string | undefined) => {
   if (!normalized) return undefined;
   const [pathWithoutHash, hash = ""] = normalized.split("#");
   const [pathname, search = ""] = pathWithoutHash.split("?");
-  const routePath = `/${pathname.replace(/^\/+|\/+$/g, "")}`;
+  const routePath = `/${trimSlashes(pathname)}`;
   return `${routePath === "/" ? "/" : routePath}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
 };
 
@@ -453,7 +453,7 @@ class Router {
       const h = requestHeaders();
       const req = getRequest();
       const reqPathname = req ? new URL(req.url).pathname : "";
-      const langFromPath = reqPathname.split("/").filter(Boolean)[0];
+      const langFromPath = reqPathname.split("/").find(Boolean);
       const lang = (h.get("x-locale") ?? langFromPath ?? this.#lang) as string;
       const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
       const { pathname, href: fullHref } = getPathInfo(href, lang, shouldExposeBasePath() ? basePath : "");

package/client/rscNavigation.ts

@@ -3,7 +3,10 @@ declare global {
   var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
   var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
   var __AKAN_RSC_NAVIGATE__:
-    | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean; shallow?: boolean }) => Promise<void>)
+    | ((
+        href: string,
+        options?: { replace?: boolean; scrollToTop?: boolean; scrollY?: number; shallow?: boolean },
+      ) => Promise<void>)
     | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
   var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;

package/client/types.ts

@@ -102,8 +102,9 @@ const slugFontPart = (value: string) =>
   value
     .trim()
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "font";
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .join("-") || "font";
 
 export interface ModelsProps<M extends { id: string }> {
   className?: string;

package/client/webManifest.ts

@@ -1,8 +1,10 @@
+import { trimSlashes } from "akanjs/common";
+
 /** Where an SSR document links its root layout's `.manifest()`; the server answers it from that layout. */
 export const webManifestHref = (basePath?: string | null) =>
   basePath ? `/${basePath}/manifest.webmanifest` : "/manifest.webmanifest";
 
-const trimSlashes = (value: string) => value.trim().replace(/^\/+|\/+$/g, "");
+const trimBasePath = (value: string) => trimSlashes(value.trim());
 
 /** The basePath a `/manifest.webmanifest` request asks for: by a visible prefix, else by the request's basePath. */
 export const getWebManifestBasePath = (
@@ -12,9 +14,9 @@ export const getWebManifestBasePath = (
 ): string | null | undefined => {
   const segments = pathname.trim().split("/").filter(Boolean);
   if (segments.at(-1) !== "manifest.webmanifest" || segments.length > 2) return undefined;
-  const known = basePaths.map(trimSlashes);
+  const known = basePaths.map(trimBasePath);
   if (segments.length === 2) return known.includes(segments[0] ?? "") ? (segments[0] ?? null) : undefined;
-  const fromHeader = trimSlashes(headerBasePath ?? "");
+  const fromHeader = trimBasePath(headerBasePath ?? "");
   return known.includes(fromHeader) ? fromHeader : null;
 };
 

package/common/TrustedProxy.ts

@@ -3,8 +3,12 @@ import { clientAddressFromHeaders, normalizeIpAddress } from "./clientAddress";
 export class TrustedProxy {
   static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
   static #trustAll: boolean | null = null;
+  
+  static readonly #verdicts = new Map<string, boolean>();
+  static readonly #verdictLimit = 1024;
 
   static configure(list: string | null | undefined) {
+    TrustedProxy.#verdicts.clear();
     TrustedProxy.#trustAll = list?.trim() === "*";
     TrustedProxy.#cidrs = (list ?? "")
       .split(",")
@@ -19,6 +23,7 @@ export class TrustedProxy {
   static reset() {
     TrustedProxy.#cidrs = null;
     TrustedProxy.#trustAll = null;
+    TrustedProxy.#verdicts.clear();
   }
 
   static #load() {
@@ -29,6 +34,15 @@ export class TrustedProxy {
     if (!address) return false;
     TrustedProxy.#load();
     if (TrustedProxy.#trustAll) return true;
+    const known = TrustedProxy.#verdicts.get(address);
+    if (known !== undefined) return known;
+    const verdict = TrustedProxy.#judge(address);
+    if (TrustedProxy.#verdicts.size >= TrustedProxy.#verdictLimit) TrustedProxy.#verdicts.clear();
+    TrustedProxy.#verdicts.set(address, verdict);
+    return verdict;
+  }
+
+  static #judge(address: string): boolean {
     const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
     if (!bytes) return false;
     if (TrustedProxy.#isLocalRange(bytes)) return true;

package/common/index.ts

@@ -199,6 +199,7 @@ export { sleep } from "./sleep";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
 export { TrustedProxy } from "./TrustedProxy";
 export { toError } from "./toError";
+export { trimSlashes, trimTrailingSlashes } from "./trimSlashes";
 export {
   type TunnelAgentIdentity,
   type TunnelAttachedFrame,

package/common/interpolateTranslation.ts

@@ -1,7 +1,21 @@
 /** A `{name}` placeholder whose value is absent is left as written, never replaced by "undefined". */
 export const interpolateTranslation = (message: string, data: Record<string, unknown> | undefined) => {
   if (!data) return message;
-  return message.replace(/{([^}]+)}/g, (placeholder, name: string) =>
-    data[name] === undefined ? placeholder : String(data[name]),
-  );
+  
+  let result = "";
+  let copied = 0;
+  let open = message.indexOf("{");
+  while (open !== -1) {
+    const close = message.indexOf("}", open + 1);
+    if (close === -1) break;
+    if (close === open + 1) {
+      open = message.indexOf("{", close);
+      continue;
+    }
+    const value = data[message.slice(open + 1, close)];
+    result += message.slice(copied, open) + (value === undefined ? message.slice(open, close + 1) : String(value));
+    copied = close + 1;
+    open = message.indexOf("{", copied);
+  }
+  return result + message.slice(copied);
 };

package/common/isEmail.ts

@@ -1 +1 @@
-export const isEmail = (email?: string | null) => !!email && /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,8})+$/.test(email);
+export const isEmail = (email?: string | null) => !!email && /^\w+(?:[.-]\w+)*@\w+(?:[.-]\w+)*\.\w{2,8}$/.test(email);

package/common/localeConfig.ts

@@ -28,14 +28,20 @@ export function resolveAkanI18nConfig(input: AkanI18nConfigInput = {}): AkanI18n
   return { defaultLocale, locales };
 }
 
+let lastParsed: { defaultLocale?: string; locales?: string; config: AkanI18nConfig } | null = null;
+
 export function parseAkanI18nEnv(
   env: Record<string, string | undefined> = {
     AKAN_PUBLIC_DEFAULT_LOCALE: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_DEFAULT_LOCALE : undefined,
     AKAN_PUBLIC_LOCALES: typeof process !== "undefined" ? process.env.AKAN_PUBLIC_LOCALES : undefined,
   },
 ): AkanI18nConfig {
-  return resolveAkanI18nConfig({
-    defaultLocale: env.AKAN_PUBLIC_DEFAULT_LOCALE,
-    locales: env.AKAN_PUBLIC_LOCALES?.split(","),
-  });
+  const defaultLocale = env.AKAN_PUBLIC_DEFAULT_LOCALE;
+  const locales = env.AKAN_PUBLIC_LOCALES;
+  if (lastParsed && lastParsed.defaultLocale === defaultLocale && lastParsed.locales === locales)
+    return lastParsed.config;
+  const resolved = resolveAkanI18nConfig({ defaultLocale, locales: locales?.split(",") });
+  const config = Object.freeze({ ...resolved, locales: Object.freeze(resolved.locales) as unknown as string[] });
+  lastParsed = { defaultLocale, locales, config };
+  return config;
 }

package/common/markdownSpans.ts

@@ -9,7 +9,7 @@ export type MarkdownSpan =
   | { kind: "plain"; text: string };
 
 const inline =
-  /(!?)\[([^\]]*)\]\(((?:[^\s()]|\([^\s()]*\))+)\)|`([^`]+)`|\*\*([\s\S]+?)\*\*|\*([^*\n]+?)\*|~~([\s\S]+?)~~/g;
+  /(!?)\[([^[\]]*)\]\(((?:[^\s()]|\([^\s()]*\))+)\)|`([^`]+)`|\*\*([\s\S]+?)\*\*|\*([^*\n]+?)\*|~~([\s\S]+?)~~/g;
 
 export class MarkdownSpans {
   static of(text: string): MarkdownSpan[] {

package/common/restClient.ts

@@ -1,3 +1,5 @@
+import { trimTrailingSlashes } from "./trimSlashes";
+
 export interface RestClientOptions {
   baseUrl?: string;
   headers?: HeadersInit;
@@ -16,7 +18,7 @@ export class RestClient {
 
   constructor(options: string | RestClientOptions = {}) {
     const normalized = typeof options === "string" ? { baseUrl: options } : options;
-    this.baseUrl = normalized.baseUrl?.replace(/\/+$/, "") ?? "";
+    this.baseUrl = trimTrailingSlashes(normalized.baseUrl ?? "");
     this.headers = new Headers(normalized.headers);
     this.timeout = normalized.timeout;
   }

package/common/routeConvention.ts

@@ -1,3 +1,5 @@
+import { trimSlashes, trimTrailingSlashes } from "./trimSlashes";
+
 const ROUTE_SOURCE_RE = /^\.\/(.+)\.(tsx|ts|jsx|js)$/;
 const SOURCE_EXT_RE = /\.(tsx|ts|jsx|js)$/;
 const RESERVED_ROUTE_FILES = new Set(["_layout", "_index", "_overrides"]);
@@ -97,9 +99,7 @@ export function validateSubRoutePageKey(
   basePaths: Iterable<string>,
   options: ValidateSubRoutePageKeyOptions = {},
 ): void {
-  const allowedBasePaths = [
-    ...new Set([...basePaths].map((basePath) => basePath.trim().replace(/^\/+|\/+$/g, "")).filter(Boolean)),
-  ];
+  const allowedBasePaths = [...new Set([...basePaths].map((basePath) => trimSlashes(basePath.trim())).filter(Boolean))];
   if (allowedBasePaths.length === 0) return;
 
   const match = ROUTE_SOURCE_RE.exec(key);
@@ -165,7 +165,7 @@ export function tryParseRouteModuleKey(key: string): ParsedRouteModuleKey | null
 
 export function normalizeRoutePattern(segments: string[]): string {
   const parts = segments.map(routeSegmentToPatternPart).filter((part) => part.length > 0);
-  return `/${parts.join("/")}`.replace(/\/+$/, "") || "/";
+  return trimTrailingSlashes(`/${parts.join("/")}`) || "/";
 }
 
 export function routeSegmentToPatternPart(segment: string): string {

package/common/trimSlashes.ts

@@ -0,0 +1,11 @@
+export const trimTrailingSlashes = (value: string) => {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+};
+
+export const trimSlashes = (value: string) => {
+  let start = 0;
+  while (start < value.length && value[start] === "/") start += 1;
+  return trimTrailingSlashes(value.slice(start));
+};

package/common/types.ts

@@ -6,7 +6,7 @@ export interface RetryPolicy extends BackoffPolicy {
   attempts?: number;
 }
 
-export interface FetchPolicy<Returns = unknown> {
+export interface FetchPolicy<_Returns = unknown> {
   cache?: boolean | number;
   crystalize?: boolean;
   origin?: string;

package/constant/fieldInfo.ts

@@ -276,7 +276,7 @@ export type FieldInfoObjectToFieldObject<Obj extends FieldInfoObject> = {
 
 export class ConstantField<
   FieldType extends ConstantFieldKind = ConstantFieldKind,
-  Value extends ConstantFieldTypeInput | null = any,
+  _Value extends ConstantFieldTypeInput | null = any,
   FieldValue = any,
   MapValue = any,
   Nullable extends boolean = boolean,
@@ -472,7 +472,7 @@ type FieldOption<
       >
     >[];
 
-export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ...infer Rest]
+export type PlainTypeToFieldType<PlainType> = PlainType extends [infer First, ...unknown[]]
   ? PlainTypeToFieldType<First>[]
   : PlainType extends number
     ? typeof Int | typeof Float

package/constant/fieldPlan.ts

@@ -0,0 +1,80 @@
+import { FIELD_META, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+
+import type { ConstantField, FieldObject } from "./fieldInfo";
+
+/**
+ * What a response does with a field: leaves it out (`hidden` / `secret`), computes it (`resolve`), copies it (a
+ * primitive or a Map), walks into it (an embedded scalar), or loads what it points at (a relation).
+ */
+export type FieldPlanKind = "masked" | "computed" | "value" | "scalar" | "relation";
+
+export interface FieldPlanEntry {
+  key: string;
+  field: ConstantField;
+  kind: FieldPlanKind;
+  /** Points at another stored model, so an input carries its id; independent of `kind`, as `serialize` reads it. */
+  isRelationRef: boolean;
+  /** The scalar class of a primitive field, which `serialize` calls straight; `null` for everything else. */
+  primitive: typeof PrimitiveScalar | null;
+  serializeOption: { nullable: boolean; key: string };
+}
+interface PlanOwner {
+  [FIELD_META]: FieldObject;
+}
+
+export class FieldPlan {
+  static #byClass = new WeakMap<object, FieldPlan>();
+  static #generation = 0;
+  static #computingAsync = new Set<FieldPlan>();
+  static of(cls: PlanOwner): FieldPlan {
+    const cached = FieldPlan.#byClass.get(cls);
+    if (cached) return cached;
+    const plan = new FieldPlan(cls[FIELD_META]);
+    FieldPlan.#byClass.set(cls, plan);
+    return plan;
+  }
+  static reset(cls: object) {
+    FieldPlan.#byClass.delete(cls);
+    FieldPlan.#generation += 1;
+  }
+
+  readonly entries: readonly FieldPlanEntry[];
+  #resolvesAsync: { value: boolean; generation: number } | null = null;
+  constructor(fieldObj: FieldObject) {
+    this.entries = Object.entries(fieldObj).map(([key, field]) => ({
+      key,
+      field,
+      kind: FieldPlan.#kindOf(field),
+      isRelationRef: field.isClass && !field.isScalar,
+      primitive: PrimitiveRegistry.has(field.modelRef) ? (field.modelRef as unknown as typeof PrimitiveScalar) : null,
+      serializeOption: { nullable: field.nullable, key },
+    }));
+  }
+
+  static #kindOf(field: ConstantField): FieldPlanKind {
+    if (field.fieldType === "hidden" || field.fieldType === "secret") return "masked";
+    if (field.fieldType === "resolve") return "computed";
+    if (!field.isClass) return "value";
+    return field.isScalar ? "scalar" : "relation";
+  }
+
+  /** Whether resolving a value of this class awaits anything: a relation, a resolve field, or one in a scalar below. */
+  get resolvesAsync(): boolean {
+    if (this.#resolvesAsync?.generation === FieldPlan.#generation) return this.#resolvesAsync.value;
+    
+    if (FieldPlan.#computingAsync.has(this)) return true;
+    FieldPlan.#computingAsync.add(this);
+    try {
+      const value = this.entries.some(
+        ({ kind, field }) =>
+          kind === "computed" ||
+          kind === "relation" ||
+          (kind === "scalar" && FieldPlan.of(field.modelRef as unknown as PlanOwner).resolvesAsync),
+      );
+      this.#resolvesAsync = { value, generation: FieldPlan.#generation };
+      return value;
+    } finally {
+      FieldPlan.#computingAsync.delete(this);
+    }
+  }
+}

package/constant/index.ts

@@ -3,10 +3,13 @@ export * from "./constantRegistry";
 export * from "./crystalize";
 export * from "./dateSlot";
 export * from "./fieldInfo";
+export * from "./fieldPlan";
 export * from "./fieldQueryMeta";
 export * from "./getDefault";
 export * from "./hydrationPlan";
 export * from "./immerify";
+export * from "./inputParser";
+export * from "./invalidInputError";
 export * from "./labelOf";
 export * from "./mask";
 export * from "./purify";

package/constant/inputParser.ts

@@ -0,0 +1,148 @@
+import {
+  Any,
+  type Cls,
+  dayjs,
+  type EnumInstance,
+  FIELD_META,
+  Float,
+  getNonArrayModel,
+  ID,
+  Int,
+  PrimitiveRegistry,
+  type PrimitiveScalar,
+} from "akanjs/base";
+
+import { ConstantRegistry } from "./constantRegistry";
+import type { ConstantField, FieldObject } from "./fieldInfo";
+import { FieldPlan, type FieldPlanEntry } from "./fieldPlan";
+import { defaultPlanOf } from "./getDefault";
+import { InvalidInputError } from "./invalidInputError";
+import { deserialize } from "./serialize";
+
+type ModelCls = Cls & { [FIELD_META]: FieldObject };
+type Parse = (value: unknown, path: string) => unknown;
+
+interface ParseOption {
+  key: string;
+  nullable?: boolean;
+  enum?: EnumInstance;
+}
+
+const isString = (value: unknown) => typeof value === "string";
+const isNumber = (value: unknown) => typeof value === "number";
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export class InputParser {
+  
+  static readonly #wireTypes = new Map<unknown, (value: unknown) => boolean>([
+    [String, isString],
+    [ID, isString],
+    [Int, isNumber],
+    [Float, isNumber],
+    [Boolean, (value) => typeof value === "boolean"],
+    [Date, (value) => isString(value) || isNumber(value) || value instanceof Date || dayjs.isDayjs(value)],
+  ]);
+
+  static parse(argRef: Cls, arrDepth: number, value: unknown, option: ParseOption) {
+    if (PrimitiveRegistry.has(argRef)) return deserialize(argRef, arrDepth, value, option);
+    const { key, nullable = false } = option;
+    if (value === null || value === undefined) {
+      if (nullable) return null;
+      throw new InvalidInputError(key, null);
+    }
+    return InputParser.#walk(value, arrDepth, key, (item, path) => InputParser.#value(argRef, item, path));
+  }
+
+  static #walk(value: unknown, arrDepth: number, path: string, parse: Parse): unknown {
+    if (!arrDepth) return parse(value, path);
+    if (!Array.isArray(value)) throw new InvalidInputError(path, "array");
+    return value.map((item, idx) => InputParser.#walk(item, arrDepth - 1, `${path}.${idx}`, parse));
+  }
+
+  static #value(ref: Cls, value: unknown, path: string, enumRef?: EnumInstance): unknown {
+    if (value === null || value === undefined) {
+      if (ref === Any) return value ?? null;
+      throw new InvalidInputError(path, null);
+    }
+    if (PrimitiveRegistry.has(ref)) return InputParser.#primitive(ref as typeof PrimitiveScalar, value, path, enumRef);
+    if (ConstantRegistry.isScalar(ref)) return InputParser.#scalar(ref as ModelCls, value, path);
+    return InputParser.#model(ref as ModelCls, value, path);
+  }
+
+  static #primitive(primitive: typeof PrimitiveScalar, value: unknown, path: string, enumRef?: EnumInstance) {
+    const hasWireType = InputParser.#wireTypes.get(primitive);
+    if (hasWireType && !hasWireType(value)) throw new InvalidInputError(path, primitive.refName);
+    let parsed: unknown;
+    try {
+      parsed = primitive._parse(value as never);
+    } catch {
+      throw new InvalidInputError(path, primitive.refName);
+    }
+    if (enumRef && !enumRef.has(parsed as never))
+      throw new InvalidInputError(path, `one of ${enumRef.values.join(", ")}`);
+    return parsed;
+  }
+
+  static #scalar(ref: ModelCls, value: unknown, path: string) {
+    if (!isRecord(value)) throw new InvalidInputError(path, "object");
+    const defaults = defaultPlanOf(ref[FIELD_META]);
+    const parsed: Record<string, unknown> = {};
+    for (const entry of FieldPlan.of(ref).entries) {
+      if (entry.kind === "computed") continue;
+      const fieldPath = `${path}.${entry.key}`;
+      const raw = value[entry.key];
+      if (raw !== undefined) parsed[entry.key] = InputParser.#field(entry, raw, fieldPath);
+      else if (InputParser.#isRequired(entry.field)) throw new InvalidInputError(fieldPath, null);
+      else {
+        const make = defaults.perCall.get(entry.key);
+        parsed[entry.key] = make ? make() : defaults.shared[entry.key];
+      }
+    }
+    return parsed;
+  }
+
+  static #model(ref: ModelCls, value: unknown, path: string) {
+    if (!isRecord(value)) throw new InvalidInputError(path, "object");
+    const parsed: Record<string, unknown> = {};
+    for (const entry of FieldPlan.of(ref).entries) {
+      if (entry.kind === "computed") continue;
+      const fieldPath = `${path}.${entry.key}`;
+      const raw = value[entry.key];
+      if (raw !== undefined) parsed[entry.key] = InputParser.#field(entry, raw, fieldPath);
+      else if (InputParser.#isRequired(entry.field)) throw new InvalidInputError(fieldPath, null);
+    }
+    return parsed;
+  }
+
+  static #field({ field, isRelationRef }: FieldPlanEntry, value: unknown, path: string): unknown {
+    if (value === null) {
+      if (field.nullable || (field.modelRef as Cls) === Any) return null;
+      throw new InvalidInputError(path, null);
+    }
+    return InputParser.#walk(value, field.arrDepth, path, (item, itemPath) => {
+      if (field.isMap) return InputParser.#map(field.of as Cls | Cls[], item, itemPath);
+      if (isRelationRef) return InputParser.#value(ID, item, itemPath);
+      return InputParser.#value(field.modelRef, item, itemPath, field.enum);
+    });
+  }
+
+  static #map(of: Cls | Cls[], value: unknown, path: string) {
+    if (!isRecord(value)) throw new InvalidInputError(path, "object");
+    const [valueRef, valueArrDepth] = getNonArrayModel(of);
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        InputParser.#walk(item, valueArrDepth, `${path}.${key}`, (entry, entryPath) =>
+          InputParser.#value(valueRef as Cls, entry, entryPath),
+        ),
+      ]),
+    );
+  }
+
+  static #isRequired(field: ConstantField) {
+    if (field.nullable || (field.modelRef as Cls) === Any) return false;
+    if (field.default !== null && field.default !== undefined) return false;
+    return !(field.isClass && field.isScalar);
+  }
+}

package/constant/invalidInputError.ts

@@ -0,0 +1,13 @@
+/** A body value the request schema refuses: `path` names it from the argument down (`data.items.2.price`). */
+export class InvalidInputError extends Error {
+  readonly path: string;
+  readonly reason: "missing" | "invalid";
+  /** What the field takes — a type name, `object`, `array`, or the enum's values; `null` when it is missing. */
+  readonly expected: string | null;
+  constructor(path: string, expected: string | null) {
+    super(expected ? `Invalid input at ${path}: expected ${expected}` : `Missing input at ${path}`);
+    this.path = path;
+    this.reason = expected ? "invalid" : "missing";
+    this.expected = expected;
+  }
+}