akanjs 3.1.0-rc.2 → 3.1.0-rc.20

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/href.ts

@@ -0,0 +1,35 @@
+export class Href {
+  static readonly #blocked = new Set(["javascript:", "vbscript:", "data:"]);
+
+  static #parse(href: string, base?: string): URL | null {
+    try {
+      return new URL(href, base);
+    } catch {
+      return null;
+    }
+  }
+
+  /** External is what the browser takes off-site: any absolute URL with a scheme, and `//`/`\\` network-path
+   * forms that name a host. javascript:, vbscript: and data: never count. */
+  static isExternal(href: string): boolean {
+    
+    const absolute = Href.#parse(href);
+    if (absolute) return !Href.#blocked.has(absolute.protocol);
+
+    const value = href.replace(/[\t\n\r]/g, "").replace(/^[\u0000-\u0020]+/, "");
+    return /^[\\/]{2}/.test(value) && !!Href.#parse(value, "https://localhost")?.hostname;
+  }
+
+  /** An explicit http(s) scheme in any case; `//host` and `httpbin/x` do not qualify. */
+  static hasWebScheme(href: string): boolean {
+    return /^https?:/i.test(href);
+  }
+
+  /** Canonical absolute URL for an external href: follows the browser on an http(s) document base; on a native
+   * `app://` base an absolute URL resolves as written and a network path resolves against https:. */
+  static toExternalUrl(href: string, base: string): string {
+    const baseUrl = Href.#parse(base);
+    if (baseUrl && /^https?:$/.test(baseUrl.protocol)) return Href.#parse(href, baseUrl.href)?.href ?? href;
+    return (Href.#parse(href) ?? Href.#parse(href, "https://localhost"))?.href ?? href;
+  }
+}

package/client/index.ts

@@ -7,6 +7,7 @@ export * from "./csrTypes";
 export * from "./decorators";
 export * from "./device";
 export * from "./frameConfig";
+export * from "./href";
 export * from "./locale";
 export * from "./makePageProto";
 export * from "./mcpView";

package/client/makePageProto.tsx

@@ -28,11 +28,12 @@ const getPageInfo = (): { locale: string; path: string } => {
   const activePath = Translator.getActivePath();
   if (activePath) return { locale: activeLocale ?? defaultLocale, path: activePath };
   if (getEnv().side !== "server") {
-    const [, firstSegment = "", ...rest] = csrLocation.pathname.split("/");
+    const pathname = Translator.getRenderPath() ?? csrLocation.pathname;
+    const [, firstSegment = "", ...rest] = pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
     
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
-    return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : csrLocation.pathname) };
+    return { locale, path: hasLocalePrefix ? `/${rest.join("/")}` : pathname };
   }
   const h = untrackedHeaders();
   

package/client/router.ts

@@ -1,6 +1,7 @@
 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 { Href } from "./href";
 import { isMcpView } from "./mcpView";
 
 export interface RouteOptions {
@@ -99,7 +100,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}` : ""}`;
 };
 
@@ -158,7 +159,8 @@ export const getPathInfo = (requestUrl: string, lang: string, prefix: string) =>
         ? pathWithSubRoute.slice(prefixLength)
         : pathWithSubRoute;
   const subRoute = prefix ? `/${prefix}` : "";
-  const pathname = path.startsWith("http") ? path : path === "/" ? `/${lang}${subRoute}` : `/${lang}${subRoute}${path}`;
+  
+  const pathname = Href.hasWebScheme(path) ? path : path === "/" ? `/${lang}${subRoute}` : `/${lang}${subRoute}${path}`;
   const href = `${pathname}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
   return { path, pathname, hash, search, href };
 };
@@ -453,7 +455,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

@@ -5,7 +5,7 @@ declare global {
   var __AKAN_RSC_NAVIGATE__:
     | ((
         href: string,
-        options?: { replace?: boolean; scrollToTop?: boolean; shallow?: boolean; pop?: boolean },
+        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;

package/client/transitionTypes.ts

@@ -1,6 +1,2 @@
 export const transitionTypes = ["none", "fade", "bottomUp", "stack", "scaleOut"] as const;
 export type TransitionType = (typeof transitionTypes)[number];
-
-/** The class `ui/styles.css` animates a page by when a navigation plays `transition` forward (push) or back (pop). */
-export const viewTransitionClassOf = (transition: Exclude<TransitionType, "none">, direction: "push" | "pop") =>
-  `akan-${transition}-${direction}` as const;

package/client/translator.ts

@@ -18,6 +18,8 @@ interface TranslatorState {
   activeLocale?: string;
   
   activePath?: string;
+  
+  renderPath?: string;
 }
 
 const TRANSLATOR_STATE_KEY = "__AKAN_TRANSLATOR_STATE__";
@@ -57,6 +59,20 @@ export class Translator {
   static getActivePath(): string | undefined {
     return getTranslatorState().activePath;
   }
+  static renderAt<T>(path: string | undefined, render: () => T): T {
+    if (!path) return render();
+    const state = getTranslatorState();
+    const outer = state.renderPath;
+    state.renderPath = path;
+    try {
+      return render();
+    } finally {
+      state.renderPath = outer;
+    }
+  }
+  static getRenderPath(): string | undefined {
+    return getTranslatorState().renderPath;
+  }
   static markHydrated() {
     delete getTranslatorState().activePath;
   }

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/viewportMeta.ts

@@ -7,6 +7,9 @@ export interface ThemeColorTag {
 
 /** Turns a root layout's `.viewport()` into the `viewport` and `theme-color` meta tags every document shell writes. */
 export class ViewportMeta {
+  static readonly #offMedia = "not all";
+  static readonly #ownAttr = "data-akan-theme-color";
+
   static content(viewport: RouteViewport | undefined, { native = false }: { native?: boolean } = {}): string {
     const parts = ["width=device-width", "initial-scale=1"];
     if (viewport?.fitCover ?? native) parts.push("viewport-fit=cover");
@@ -39,18 +42,30 @@ export class ViewportMeta {
     const tags = ViewportMeta.themeColors(viewport, theme);
     if (!tags.length) return;
     const existing = [...document.head.querySelectorAll<HTMLMetaElement>('meta[name="theme-color"]')];
-
-    for (const meta of existing.slice(tags.length)) meta.setAttribute("media", "not all");
-    tags.forEach((tag, idx) => {
-      const meta = existing[idx] ?? ViewportMeta.#ensureMeta("theme-color", true);
+    const live = existing.filter((meta) => meta.getAttribute("media") !== ViewportMeta.#offMedia);
+    const isCurrent =
+      live.length === tags.length &&
+      tags.every(
+        (tag, idx) => live[idx]?.content === tag.content && live[idx]?.getAttribute("media") === (tag.media ?? null),
+      );
+    if (isCurrent) return;
+    
+    for (const meta of existing) {
+      if (meta.hasAttribute(ViewportMeta.#ownAttr)) meta.remove();
+      else meta.setAttribute("media", ViewportMeta.#offMedia);
+    }
+    for (const tag of tags) {
+      const meta = document.createElement("meta");
+      meta.name = "theme-color";
       meta.content = tag.content;
       if (tag.media) meta.setAttribute("media", tag.media);
-      else meta.removeAttribute("media");
-    });
+      meta.setAttribute(ViewportMeta.#ownAttr, "");
+      document.head.appendChild(meta);
+    }
   }
 
-  static #ensureMeta(name: string, fresh = false): HTMLMetaElement {
-    const found = fresh ? null : document.head.querySelector<HTMLMetaElement>(`meta[name="${name}"]`);
+  static #ensureMeta(name: string): HTMLMetaElement {
+    const found = document.head.querySelector<HTMLMetaElement>(`meta[name="${name}"]`);
     if (found) return found;
     const meta = document.createElement("meta");
     meta.name = name;

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/codeAgentWire.ts

@@ -18,6 +18,8 @@ export interface CodeAgentSessionInfo {
   contextTokens: number | undefined;
   /** Absent when the model does no reasoning at all, which is not reasoning turned `off`. */
   effort: CodeAgentEffort | undefined;
+  /** Percent of the window that starts a compaction; absent leaves the engine's own, later threshold. */
+  autoCompactAt: number | undefined;
   /** Absent until the session has been asked something. */
   name: string | undefined;
   /** `await` keeps a question inside its turn; `suspend` ends the turn (`awaiting`) and the answer opens a new one. */
@@ -186,6 +188,8 @@ export type CodeAgentCommand =
   | { type: "abort" }
   | { type: "compact"; instructions?: string }
   | { type: "set_model"; provider: string; modelId: string }
+  /** `percent` in steps of 10; absent, or 100, restores the default. */
+  | { type: "set_auto_compact"; percent?: number }
   | { type: "fork"; entryId: string }
   | { type: "new_session" }
   /** Current state, plus every frame after `sinceSeq` when one is given. */
@@ -231,8 +235,11 @@ export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
         `session ${event.info.sessionId}`,
         event.info.model?.name ?? "no model",
         event.info.contextTokens ? `${Math.round(event.info.contextTokens / 1000)}k ctx` : "unknown ctx",
+        event.info.autoCompactAt ? `compacts at ${event.info.autoCompactAt}%` : "",
         event.info.profile,
-      ].join(" · ");
+      ]
+        .filter((part) => !!part)
+        .join(" · ");
     case "turn_start":
       return "turn start";
     case "turn_end":

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";