akanjs 3.0.0-alpha.70 → 3.0.0-alpha.72

package/common/TrustedProxy.ts

@@ -0,0 +1,134 @@
+import { normalizeIpAddress } from "./clientAddress";
+
+/**
+ * Whether the hop that connected is allowed to name the caller.
+ *
+ * `x-real-ip` and `x-forwarded-for` are just request headers: anyone can send them. They are the truth only when
+ * the peer that sent them is a proxy we put there — otherwise a client forges its own address and walks past
+ * every `.with(Ip)` guard, rate limit and audit line at once.
+ *
+ * The default trusts a private, loopback or link-local peer and nothing else, because that is exactly the shape
+ * of a proxy on the same network: an ingress, a service mesh, the dev machine. A gateway reachable from the
+ * internet sees a public peer, so a header from there is dropped rather than believed. `AKAN_TRUSTED_PROXIES`
+ * takes a comma-separated CIDR list for the case the proxy is not private — and `*` for "the deployment
+ * guarantees nothing untrusted can reach this port", which is the old behaviour, written down.
+ */
+export class TrustedProxy {
+  static #cidrs: { bytes: Uint8Array; bits: number }[] | null = null;
+  static #trustAll: boolean | null = null;
+
+  static configure(list: string | null | undefined) {
+    TrustedProxy.#trustAll = list?.trim() === "*";
+    TrustedProxy.#cidrs = (list ?? "")
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry && entry !== "*")
+      .flatMap((entry) => {
+        const parsed = TrustedProxy.#parseCidr(entry);
+        return parsed ? [parsed] : [];
+      });
+  }
+
+  static reset() {
+    TrustedProxy.#cidrs = null;
+    TrustedProxy.#trustAll = null;
+  }
+
+  static #load() {
+    if (TrustedProxy.#cidrs === null) TrustedProxy.configure(process.env.AKAN_TRUSTED_PROXIES);
+  }
+
+  static isTrusted(address: string | null | undefined): boolean {
+    if (!address) return false;
+    TrustedProxy.#load();
+    if (TrustedProxy.#trustAll) return true;
+    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    if (!bytes) return false;
+    if (TrustedProxy.#isLocalRange(bytes)) return true;
+    return (TrustedProxy.#cidrs ?? []).some((cidr) => TrustedProxy.#inRange(bytes, cidr));
+  }
+
+  /**
+   * The caller's address as recorded by a proxy, but only when the peer is one. Falls back to the peer itself,
+   * which is the right answer for a process nothing is proxying, and `null` when there is no peer either.
+   */
+  static clientAddress(headers: Headers, peerAddress: string | null | undefined): string | null {
+    if (TrustedProxy.isTrusted(peerAddress)) {
+      const realIp = headers.get("x-real-ip")?.trim();
+      if (realIp) return normalizeIpAddress(realIp);
+      const forwarded = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+      if (forwarded) return normalizeIpAddress(forwarded);
+    }
+    return peerAddress ? normalizeIpAddress(peerAddress) : null;
+  }
+
+  /** `10/8`, `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, and their IPv6 counterparts `::1`, `fc00::/7`, `fe80::/10`. */
+  static #isLocalRange(bytes: Uint8Array): boolean {
+    if (bytes.length === 4) {
+      const [a = 0, b = 0] = bytes;
+      if (a === 10 || a === 127) return true;
+      if (a === 192 && b === 168) return true;
+      if (a === 172 && b >= 16 && b <= 31) return true;
+      return a === 169 && b === 254;
+    }
+    const [first = 0, second = 0] = bytes;
+    if ((first & 0xfe) === 0xfc) return true;
+    if (first === 0xfe && (second & 0xc0) === 0x80) return true;
+    return bytes.every((byte, idx) => (idx === 15 ? byte === 1 : byte === 0));
+  }
+
+  static #parseCidr(entry: string): { bytes: Uint8Array; bits: number } | null {
+    const [address, prefix] = entry.split("/");
+    const bytes = TrustedProxy.#toBytes(address ?? "");
+    if (!bytes) return null;
+    const bits = prefix === undefined ? bytes.length * 8 : Number(prefix);
+    if (!Number.isInteger(bits) || bits < 0 || bits > bytes.length * 8) return null;
+    return { bytes, bits };
+  }
+
+  static #inRange(bytes: Uint8Array, cidr: { bytes: Uint8Array; bits: number }): boolean {
+    if (bytes.length !== cidr.bytes.length) return false;
+    const wholeBytes = cidr.bits >> 3;
+    for (let idx = 0; idx < wholeBytes; idx += 1) if (bytes[idx] !== cidr.bytes[idx]) return false;
+    const restBits = cidr.bits & 7;
+    if (!restBits) return true;
+    const mask = 0xff << (8 - restBits);
+    return ((bytes[wholeBytes] ?? 0) & mask) === ((cidr.bytes[wholeBytes] ?? 0) & mask);
+  }
+
+  static #toBytes(address: string): Uint8Array | null {
+    if (address.includes(".") && !address.includes(":")) {
+      const parts = address.split(".");
+      if (parts.length !== 4) return null;
+      const bytes = new Uint8Array(4);
+      for (const [idx, part] of parts.entries()) {
+        const value = Number(part);
+        if (!/^\d{1,3}$/.test(part) || value > 255) return null;
+        bytes[idx] = value;
+      }
+      return bytes;
+    }
+    return address.includes(":") ? TrustedProxy.#ipv6ToBytes(address) : null;
+  }
+
+  static #ipv6ToBytes(address: string): Uint8Array | null {
+
+    const bare = address.split("%")[0] ?? "";
+    const halves = bare.split("::");
+    if (halves.length > 2) return null;
+    const groupsOf = (text: string) => (text ? text.split(":").filter((group) => group !== "") : []);
+    const head = groupsOf(halves[0] ?? "");
+    const tail = halves.length === 2 ? groupsOf(halves[1] ?? "") : [];
+    const filled = halves.length === 2 ? 8 - head.length - tail.length : 0;
+    if (filled < 0 || head.length + tail.length + filled !== 8) return null;
+    const groups = [...head, ...new Array(filled).fill("0"), ...tail];
+    const bytes = new Uint8Array(16);
+    for (const [idx, group] of groups.entries()) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return null;
+      const value = Number.parseInt(group, 16);
+      bytes[idx * 2] = value >> 8;
+      bytes[idx * 2 + 1] = value & 0xff;
+    }
+    return bytes;
+  }
+}

package/common/clamp.ts

@@ -0,0 +1,2 @@
+/** Constrains a value to `[min, max]`. */
+export const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);

package/common/deepObjectify.ts

@@ -31,9 +31,10 @@ export const deepObjectify = <T = unknown>(obj: T | null | undefined, option: De
   } else if (obj && typeof obj === "object") {
     const val: Record<string, unknown> = {};
     const objRecord = obj as Record<string, unknown>;
-    Object.keys(obj).forEach((key) => {
+    
+    for (const key in objRecord) {
       if (typeof objRecord[key] !== "function") val[key] = objectifyChild(objRecord[key], option);
-    });
+    }
     return val as T;
   } else {
     return obj as unknown as T;

package/common/dynamicRecord.ts

@@ -0,0 +1,12 @@
+/**
+ * A generated surface read by a name computed at runtime.
+ *
+ * The framework's glue layers dispatch by name: a store action reaches `fetch[key]`, a resolver reaches
+ * `service[method]`, a `Load.*` component reads `init[names.pageOfModel]`. None of those keys exist in a type,
+ * because the type is generated from the model — so every one of them used to be spelled `as any`, which the
+ * guide bans and which also silences the *value* type on the way out.
+ *
+ * This says the same thing about the index and nothing about the value: `as DynamicRecord` to index, then the
+ * read carries its own `as T`. One alias so a reader can tell name-based dispatch from an untyped object.
+ */
+export type DynamicRecord<Value = unknown> = { [key: string]: Value };

package/common/index.ts

@@ -1,5 +1,6 @@
 export { applyMixins } from "./applyMixins";
 export { capitalize } from "./capitalize";
+export { clamp } from "./clamp";
 export {
   clientAddressFromHeaders,
   clientPortFromHeaders,
@@ -7,6 +8,7 @@ export {
   normalizeIpAddress,
 } from "./clientAddress";
 export { deepObjectify } from "./deepObjectify";
+export type { DynamicRecord } from "./dynamicRecord";
 export {
   type FileUploadCapability,
   fileUploadContract,
@@ -16,7 +18,6 @@ export { formatNumber } from "./formatNumber";
 export { formatPhone } from "./formatPhone";
 export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase";
-export { HttpClient } from "./httpClient";
 export { isDayjs } from "./isDayjs";
 export { isEmail } from "./isEmail";
 export { isPhoneNumber } from "./isPhoneNumber";
@@ -24,7 +25,22 @@ export { isQueryEqual } from "./isQueryEqual";
 export { isThenable } from "./isThenable";
 export { isValidDate } from "./isValidDate";
 export { decodeJwtPayload } from "./jwtDecode";
-export { Logger, type LoggerSink, type LoggerSinkEntry, type LogLevel } from "./Logger";
+export {
+  type LogAttrs,
+  type LogAttrValue,
+  type LogFormat,
+  Logger,
+  type LoggerEmitInput,
+  type LoggerSink,
+  type LoggerSinkEntry,
+  type LoggerSinkOptions,
+  type LogLevel,
+  type LogLevelInput,
+  type LogRecord,
+  logFormats,
+  logLevels,
+  logSeverity,
+} from "./Logger";
 export {
   type AkanI18nConfig,
   type AkanI18nConfigInput,
@@ -32,6 +48,13 @@ export {
   parseAkanI18nEnv,
   resolveAkanI18nConfig,
 } from "./localeConfig";
+export {
+  type LogContextReader,
+  type LogContextSnapshot,
+  type LogFlightRecorder,
+  readLogContext,
+  registerLogContextReader,
+} from "./logContext";
 export { lowerlize } from "./lowerlize";
 export {
   isMcpDescribableArg,
@@ -47,8 +70,11 @@ export { objectify } from "./objectify";
 export { pathGet } from "./pathGet";
 export { pathGetLoose } from "./pathGetLoose";
 export { pathSet } from "./pathSet";
+export { plainFieldsOf } from "./plainFieldsOf";
 export { randomPick } from "./randomPick";
 export { randomPicks } from "./randomPicks";
+export { isJsonContentType, originFromRequest } from "./requestOrigin";
+export { RestClient, type RestClientOptions, type RestRequestOptions } from "./restClient";
 export {
   assertUniqueRoutePatterns,
   compareRouteSpecificity,
@@ -76,6 +102,7 @@ export {
 export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
+export { TrustedProxy } from "./TrustedProxy";
 export type * from "./types";
 export {
   type WebsocketAuthAckData,

package/common/isValidDate.ts

@@ -10,5 +10,5 @@ export const isValidDate = (d: string | Date | Dayjs) => {
   if (typeof d === "string") {
     return dayjs(d, format).isValid();
   } else if (isDayjs(d)) return d.isValid();
-  else return d instanceof Date && !isNaN(d.getTime());
+  else return d instanceof Date && !Number.isNaN(d.getTime());
 };

package/common/logContext.ts

@@ -0,0 +1,27 @@
+import type { LogRecord } from "./Logger";
+
+/** A per-request ring the Logger hands every record to; the trace decides at its end whether any of it is shown. */
+export interface LogFlightRecorder {
+  minSev: number;
+  capture(record: LogRecord, written: boolean): void;
+}
+
+export interface LogContextSnapshot {
+  traceId: string | null;
+  endpoint: string | null;
+  origin: string | null;
+  flight?: LogFlightRecorder | null;
+  /** A per-request floor below the process level (`x-akan-debug`); `null` when the request asked for nothing. */
+  debugSev?: number | null;
+}
+
+export type LogContextReader = () => LogContextSnapshot | undefined;
+
+const slot: { __akanLogContextReader?: LogContextReader | null } =
+  typeof process === "undefined" ? {} : (process as unknown as { __akanLogContextReader?: LogContextReader | null });
+
+export const registerLogContextReader = (reader: LogContextReader | null) => {
+  slot.__akanLogContextReader = reader;
+};
+
+export const readLogContext = () => slot.__akanLogContextReader?.();

package/common/plainFieldsOf.ts

@@ -0,0 +1,13 @@
+/**
+ * Own and inherited enumerable data of an object as a plain record. An Akan model keeps its Date fields as
+ * enumerable prototype accessors, which `Object.keys` and a spread never reach; methods are non-enumerable and stay
+ * out either way.
+ */
+export const plainFieldsOf = (source: object): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const key in source) {
+    const value = (source as Record<string, unknown>)[key];
+    if (typeof value !== "function") out[key] = value;
+  }
+  return out;
+};

package/common/requestOrigin.ts

@@ -0,0 +1,32 @@
+/**
+ * The origin a caller actually saw, and whether a body claims to be JSON. Both read only headers and a URL, so
+ * they answer the same way for the cache layer, the CSRF gate, and anything else that has to compare origins.
+ */
+export const originFromRequest = (headers: Headers, url: URL): string => {
+  
+  const forwardedProto = headers.get("x-forwarded-proto")?.split(",")[0]?.trim();
+  const forwardedHost = headers.get("x-forwarded-host")?.split(",")[0]?.trim();
+  const host = forwardedHost ?? headers.get("host")?.split(",")[0]?.trim();
+  const proto = forwardedProto ?? url.protocol.slice(0, -1);
+  if (host && proto) {
+    try {
+      return new URL(`${proto}://${host}`).origin;
+    } catch {
+    }
+  }
+  return url.origin;
+};
+
+/**
+ * Whether a request body may be read as JSON.
+ *
+ * `Request.json()` parses whatever bytes it holds regardless of this header, and the three content types a
+ * cross-site form can send — `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` — are
+ * exactly the ones a browser sends with **no preflight**. Requiring the JSON type is therefore what puts a
+ * preflight in front of every mutation that carries a body.
+ */
+export const isJsonContentType = (contentType: string | null): boolean => {
+  if (!contentType) return false;
+  const essence = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+  return essence === "application/json" || essence.endsWith("+json");
+};

package/common/{httpClient.ts → restClient.ts}

@@ -1,39 +1,46 @@
-export interface HttpClientOptions {
+/**
+ * A plain REST client for a service that is not an Akan API: base url, headers, timeout, JSON in and out.
+ *
+ * Not `akanjs/fetch`'s `HttpClient`, which builds an Akan endpoint's path from its serialized args and restores
+ * an `Err` from the response. Two classes of the same name in one package meant an app importing both barrels
+ * got a collision, so this one is named for what it is.
+ */
+export interface RestClientOptions {
   baseUrl?: string;
   headers?: HeadersInit;
   timeout?: number;
 }
 
-export interface HttpRequestOptions extends Omit<RequestInit, "body" | "headers" | "method"> {
+export interface RestRequestOptions extends Omit<RequestInit, "body" | "headers" | "method"> {
   headers?: HeadersInit;
   timeout?: number;
 }
 
-export class HttpClient {
+export class RestClient {
   readonly baseUrl: string;
   readonly headers: Headers;
   readonly timeout: number | undefined;
 
-  constructor(options: string | HttpClientOptions = {}) {
+  constructor(options: string | RestClientOptions = {}) {
     const normalized = typeof options === "string" ? { baseUrl: options } : options;
     this.baseUrl = normalized.baseUrl?.replace(/\/+$/, "") ?? "";
     this.headers = new Headers(normalized.headers);
     this.timeout = normalized.timeout;
   }
 
-  async get<Returns>(url: string, options?: HttpRequestOptions): Promise<Returns> {
+  async get<Returns>(url: string, options?: RestRequestOptions): Promise<Returns> {
     return await this.#request<Returns>("GET", url, undefined, options);
   }
 
-  async post<Returns>(url: string, data?: unknown, options?: HttpRequestOptions): Promise<Returns> {
+  async post<Returns>(url: string, data?: unknown, options?: RestRequestOptions): Promise<Returns> {
     return await this.#request<Returns>("POST", url, data, options);
   }
 
-  async put<Returns>(url: string, data?: unknown, options?: HttpRequestOptions): Promise<Returns> {
+  async put<Returns>(url: string, data?: unknown, options?: RestRequestOptions): Promise<Returns> {
     return await this.#request<Returns>("PUT", url, data, options);
   }
 
-  async delete<Returns>(url: string, options?: HttpRequestOptions): Promise<Returns> {
+  async delete<Returns>(url: string, options?: RestRequestOptions): Promise<Returns> {
     return await this.#request<Returns>("DELETE", url, undefined, options);
   }
 
@@ -41,7 +48,7 @@ export class HttpClient {
     method: string,
     url: string,
     data?: unknown,
-    options: HttpRequestOptions = {},
+    options: RestRequestOptions = {},
   ): Promise<Returns> {
     const { body, headers } = this.#makeBody(data);
     const timeout = options.timeout ?? this.timeout;

package/constant/crystalize.ts

@@ -8,8 +8,10 @@ import {
 } from "akanjs/base";
 
 import type { FieldProps } from ".";
+import { ConstantRegistry } from "./constantRegistry";
 
 export type CrystalizeFunc<Model> = (self: GetStateObject<Model>, isChild?: boolean) => Model;
+export type Converter = (value: unknown) => unknown;
 
 /**
  * The relation instances one hydration pass has already built, by model class and then document id.
@@ -34,58 +36,76 @@ export const withSharedInstances = <T>(hydrate: () => T): T => {
   }
 };
 
-type ModelCls = Cls<{ set: (obj: object) => object }>;
+type ModelCls = new (obj?: object) => object;
 
 const relationIdOf = (value: object): string | null => {
   const id = (value as { id?: unknown }).id;
   return typeof id === "string" && id ? id : null;
 };
 
-const crystalizeModel = (field: FieldProps, value: object): object => {
-  const modelRef = field.modelRef as ModelCls;
+const modelConverterOf = (props: FieldProps): Converter => {
+  const modelRef = props.modelRef as unknown as ModelCls;
 
-  if (value instanceof modelRef) return value;
+  if (props.isScalar) return (value) => (value instanceof modelRef ? value : new modelRef(value as object));
+  return (value) => {
+    if (value instanceof modelRef) return value;
 
-  const id = field.isScalar ? null : relationIdOf(value);
-  if (!sharedInstances || !id) return new modelRef().set(value);
-  const byId = sharedInstances.get(modelRef) ?? new Map<string, object>();
-  if (!sharedInstances.has(modelRef)) sharedInstances.set(modelRef, byId);
-  const shared = byId.get(id) ?? new modelRef().set(value);
-  byId.set(id, shared);
-  return shared;
+    const id = relationIdOf(value as object);
+    if (!sharedInstances || !id) return new modelRef(value as object);
+    const byId = sharedInstances.get(modelRef as unknown as Cls) ?? new Map<string, object>();
+    if (!sharedInstances.has(modelRef as unknown as Cls)) sharedInstances.set(modelRef as unknown as Cls, byId);
+    const shared = byId.get(id) ?? new modelRef(value as object);
+    byId.set(id, shared);
+    return shared;
+  };
 };
 
-export const crystalize = (field: FieldProps, value: unknown): unknown => {
-  if (value === undefined || value === null) return value as undefined | null;
-  if (field.isArray && Array.isArray(value))
-    return value.map((v: unknown) =>
-      crystalize({ ...field, isArray: field.arrDepth > 1, arrDepth: field.arrDepth - 1 }, v),
-    );
-  const crystalizeValue = PrimitiveRegistry.has(field.modelRef)
-    ? (value: unknown) => (field.modelRef as unknown as typeof PrimitiveScalar)._parse(value as never)
-    : (value: unknown) => value as object;
-  if (field.isMap) {
-    const mapValueField = {
-      ...field,
-      modelRef: field.of ?? field.modelRef,
-      isMap: false,
-      isClass: !!field.of && !PrimitiveRegistry.has(field.of),
-      isScalar: !!field.of && PrimitiveRegistry.has(field.of),
-      isArray: false,
-      arrDepth: 0,
-    };
+const mapConverterOf = (props: FieldProps): Converter => {
+  const of = props.of as Cls | undefined;
+  const valueConverter: Converter = of
+    ? singleConverterOf({
+        ...props,
+        modelRef: of as FieldProps["modelRef"],
+        isMap: false,
+        isClass: !PrimitiveRegistry.has(of),
+        isScalar: PrimitiveRegistry.has(of) || ConstantRegistry.isScalar(of),
+        isArray: false,
+        arrDepth: 0,
+      })
+    : (value) => value;
+  return (value) => {
     
     const entries = value instanceof Map ? [...value.entries()] : Object.entries(value as Record<string, unknown>);
     return new Map(
-      entries.map(([key, val]: [string, unknown]) => [
-        key,
-        field.of
-          ? applyFnToArrayObjects(val, (v: never) => crystalize(mapValueField, v))
-          : applyFnToArrayObjects(val, crystalizeValue),
-      ]),
+      entries.map(([key, val]: [string, unknown]) => [key, applyFnToArrayObjects(val, valueConverter as never)]),
     );
+  };
+};
+
+const singleConverterOf = (props: FieldProps): Converter => {
+  if (props.isMap) return mapConverterOf(props);
+  if (props.isClass) return modelConverterOf(props);
+  
+  if ((props.modelRef as unknown) === Date) return (value) => dayjs(value as Date);
+  if (PrimitiveRegistry.has(props.modelRef as Cls))
+    return (value) => (props.modelRef as unknown as typeof PrimitiveScalar)._parse(value as never);
+  return (value) => value;
+};
+
+const converters = new WeakMap<FieldProps, Converter>();
+
+/** The converter for one field, compiled once per `FieldProps` — which `getProps()` freezes and shares per field. */
+export const converterOf = (props: FieldProps): Converter => {
+  const cached = converters.get(props);
+  if (cached) return cached;
+  const single = singleConverterOf(props);
+  let convert: Converter = (value) => (value === null || value === undefined ? value : single(value));
+  for (let depth = props.arrDepth; depth > 0; depth--) {
+    const inner: Converter = convert;
+    convert = (value: unknown): unknown => (Array.isArray(value) ? value.map(inner) : inner(value));
   }
-  if (field.isClass) return crystalizeModel(field, value as object);
-  if (field.modelRef === Date) return dayjs(value as Date);
-  return crystalizeValue(value);
+  converters.set(props, convert);
+  return convert;
 };
+
+export const crystalize = (field: FieldProps, value: unknown): unknown => converterOf(field)(value);

package/constant/dateSlot.ts

@@ -0,0 +1,62 @@
+import { type Dayjs, dayjs } from "akanjs/base";
+
+/**
+ * A Date field stores a native `Date` under a per-key symbol and builds the `Dayjs` its type promises on first
+ * read, memoized by that `Date`. A dayjs instance is ~300 bytes and eight getter calls at construction; a `Date`
+ * is 40 bytes. A listing carries every row's dates and reads a handful of them, so this is most of what a
+ * hydrated list used to cost — see `crystalize`.
+ *
+ * The slot is a function of the key, not the class (`Symbol.for`): `applyMixins` copies a light model's accessors
+ * onto the full model's prototype, so an accessor and the `set()` that fills its slot must agree on the slot
+ * whichever class defined either one.
+ */
+const slotByKey = new Map<string, symbol>();
+export const dateSlotOf = (key: string): symbol => {
+  const cached = slotByKey.get(key);
+  if (cached) return cached;
+  const slot = Symbol.for(`akan.date.${key}`);
+  slotByKey.set(key, slot);
+  return slot;
+};
+
+const dayjsByDate = new WeakMap<Date, Dayjs>();
+const lazyDayjsOf = (date: Date): Dayjs => {
+  const cached = dayjsByDate.get(date);
+  if (cached) return cached;
+  const value = dayjs(date);
+  dayjsByDate.set(date, value);
+  return value;
+};
+
+/** A caller's own `Date` is copied: the slot must not alias an object the caller can still mutate. */
+export const toDateValue = (value: unknown): Date | null | undefined => {
+  if (value === null || value === undefined) return value;
+  if (value instanceof Date) return new Date(value.getTime());
+  if (dayjs.isDayjs(value)) return value.toDate();
+  return new Date(value as string | number);
+};
+
+type DateSlotHolder = Record<symbol, Date | null | undefined>;
+
+/**
+ * Enumerable so `for...in` — `plainFieldsOf`, `immerify`, `deepObjectify` — still sees the field. immer calls a
+ * prototype setter with the draft as `this`, so a write through the accessor stays copy-on-write, and the getter
+ * writes nothing, so a read never marks a draft modified.
+ */
+export const dateAccessorOf = (key: string): PropertyDescriptor => {
+  const slot = dateSlotOf(key);
+  return {
+    enumerable: true,
+    configurable: true,
+    get(this: DateSlotHolder) {
+      const date = this[slot];
+      return date === null || date === undefined ? date : lazyDayjsOf(date);
+    },
+    set(this: DateSlotHolder, value: unknown) {
+      this[slot] = toDateValue(value);
+    },
+  };
+};
+
+export const isDateSlotField = (props: { modelRef: unknown; isArray: boolean; isMap: boolean }): boolean =>
+  props.modelRef === Date && !props.isArray && !props.isMap;

package/constant/getDefault.ts

@@ -2,11 +2,11 @@ import { DEFAULT_VALUE, FIELD_META, type PrimitiveScalar } from "akanjs/base";
 import type { FieldObject } from ".";
 import type { DefaultOf } from "./types";
 
-interface DefaultPlan {
+export interface DefaultPlan {
   /** Fields whose default is a value that can be shared: a primitive, `null`, or the field's own literal. */
   shared: Record<string, unknown>;
   /** Fields that have to be produced per call — a thunk, a fresh array, or a nested scalar record. */
-  perCall: [key: string, make: () => unknown][];
+  perCall: Map<string, () => unknown>;
 }
 
 const planCache = new WeakMap<FieldObject, DefaultPlan>();
@@ -17,28 +17,33 @@ const planCache = new WeakMap<FieldObject, DefaultPlan>();
  * sharing one. Only values that were already shared before this cache existed live in `shared`.
  */
 export const getDefault = <T>(fieldObj: FieldObject): DefaultOf<T> => {
-  let plan = planCache.get(fieldObj);
-  if (!plan) {
-    plan = buildPlan(fieldObj);
-    planCache.set(fieldObj, plan);
-  }
+  const plan = defaultPlanOf(fieldObj);
   const result: Record<string, unknown> = { ...plan.shared };
   for (const [key, make] of plan.perCall) result[key] = make();
   return result as DefaultOf<T>;
 };
 
+/** The per-field default rules, split as above; `HydrationPlan` reads them per field so a present value skips its thunk. */
+export const defaultPlanOf = (fieldObj: FieldObject): DefaultPlan => {
+  const cached = planCache.get(fieldObj);
+  if (cached) return cached;
+  const plan = buildPlan(fieldObj);
+  planCache.set(fieldObj, plan);
+  return plan;
+};
+
 const buildPlan = (fieldObj: FieldObject): DefaultPlan => {
   const shared: Record<string, unknown> = {};
-  const perCall: [string, () => unknown][] = [];
+  const perCall = new Map<string, () => unknown>();
   for (const [key, field] of Object.entries(fieldObj)) {
     if (field.fieldType === "hidden" || field.fieldType === "secret") shared[key] = null;
     else if (field.default !== undefined && field.default !== null) {
-      if (typeof field.default === "function") perCall.push([key, field.default as () => unknown]);
+      if (typeof field.default === "function") perCall.set(key, field.default as () => unknown);
       else shared[key] = field.default as object;
-    } else if (field.isArray) perCall.push([key, () => []]);
+    } else if (field.isArray) perCall.set(key, () => []);
     else if (field.nullable) shared[key] = null;
     else if (field.isClass) {
-      if (field.isScalar) perCall.push([key, () => getDefault(field.modelRef[FIELD_META])]);
+      if (field.isScalar) perCall.set(key, () => getDefault(field.modelRef[FIELD_META]));
       else shared[key] = null;
     } else shared[key] = (field.modelRef as unknown as typeof PrimitiveScalar)[DEFAULT_VALUE];
   }