akanjs 3.0.0-beta.16 → 3.0.0-beta.18

package/base/base.ts

@@ -166,7 +166,7 @@ export class DataList<Light extends { id: string }> {
     return this.values.flatMap(fn);
   }
   sort(fn: (a: Light, b: Light) => number) {
-    return new DataList(this.values.sort(fn));
+    return new DataList([...this.values].sort(fn));
   }
   filter(fn: (value: Light, idx: number) => boolean) {
     return new DataList(this.values.filter(fn));

package/client/csrTypes.ts

@@ -46,7 +46,7 @@ export interface PageConfig {
   ssr?: SsrRenderMode;
   /**
    * Opt in to guarded RSC page suffix commits when the page does not require
-   * head/metadata updates and the retained route chain head is invariant for
+   * head updates and the retained route chain head is invariant for
    * sibling navigations under the same layout.
    */
   rscPatchHeadSafe?: boolean;
@@ -109,7 +109,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
   node: Head | null | undefined;
-  hasExplicitLanguageAlternates: boolean;
   headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -163,53 +162,24 @@ export interface WebAppManifest {
   screenshots?: WebAppManifestIcon[];
   [key: string]: unknown;
 }
-export interface AkanMetadata {
-  title?: string;
-  description?: string;
-  robots?: string;
-  openGraph?: {
-    title?: string;
-    description?: string;
-    type?: string;
-    url?: string;
-    siteName?: string;
-    images?: string | string[];
-  };
-  twitter?: {
-    card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
-    title?: string;
-    description?: string;
-    images?: string | string[];
-  };
-  alternates?: {
-    canonical?: string;
-    languages?: Record<string, string>;
-  };
-}
-export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
   default?: PageRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
-  gaTrackingId?: string;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;

package/client/frameConfig.ts

@@ -165,8 +165,8 @@ export function resolvePageState({
         : (config.gesture ?? false),
     cache: config.cache ?? false,
     ssr: config.ssr ?? "stream",
-    topSafeAreaColor: config.topSafeAreaColor ?? "var(color-background, Canvas)",
-    bottomSafeAreaColor: config.bottomSafeAreaColor ?? "var(color-background, Canvas)",
+    topSafeAreaColor: config.topSafeAreaColor ?? defaultPageState.topSafeAreaColor,
+    bottomSafeAreaColor: config.bottomSafeAreaColor ?? defaultPageState.bottomSafeAreaColor,
   };
 }
 

package/client/route/RootLayoutDefinition.ts

@@ -12,7 +12,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
   #reconnect?: boolean;
   #wsConnect?: boolean;
   #layoutStyle?: "mobile" | "web";
-  #gaTrackingId?: string;
 
   fonts(fonts: ReactFont[]) {
     this.#fonts = fonts;
@@ -38,10 +37,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
     this.#layoutStyle = style;
     return this;
   }
-  gaTrackingId(id: string) {
-    this.#gaTrackingId = id;
-    return this;
-  }
 
   protected override extendModule(module: PageModule & LayoutModule): PageModule & LayoutModule {
     return {
@@ -52,7 +47,6 @@ export class RootLayoutDefinition<Args extends RouteArgsShape = Record<never, ne
       ...(this.#reconnect !== undefined ? { reconnect: this.#reconnect } : {}),
       ...(this.#wsConnect !== undefined ? { wsConnect: this.#wsConnect } : {}),
       ...(this.#layoutStyle ? { layoutStyle: this.#layoutStyle } : {}),
-      ...(this.#gaTrackingId ? { gaTrackingId: this.#gaTrackingId } : {}),
     };
   }
 }

package/client/route/RouteDefinition.ts

@@ -9,7 +9,7 @@ import {
 import { parseAkanI18nEnv } from "akanjs/common";
 import { deserialize } from "akanjs/constant";
 import type { ReactNode } from "react";
-import type { AkanMetadata, Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
+import type { Head, LayoutModule, PageConfig, PageModule } from "../csrTypes";
 import { AkanNotFoundError } from "../router";
 import { RouteArgError, type RouteArgInfo, type RouteArgInput, type RouteBaseArgs } from "./routeArgs";
 
@@ -19,7 +19,6 @@ export type RouteKind = "page" | "layout" | "rootLayout";
 export const routeDefinitionMarker = Symbol.for("akan.routeDefinition");
 
 type HeadStage<Args> = Head | ((args: Args) => PromiseOrObject<Head | null | undefined>);
-type MetadataStage<Args> = AkanMetadata | ((args: Args) => PromiseOrObject<AkanMetadata | null | undefined>);
 
 interface RouteRenderProps {
   params: Record<string, string>;
@@ -46,7 +45,6 @@ export abstract class RouteDefinition<
   #config?: PageConfig;
 
   #head?: HeadStage<never>;
-  #metadata?: MetadataStage<never>;
   #loading?: (args: never) => PromiseOrObject<ReactNode>;
   #render?: (args: never) => PromiseOrObject<ReactNode>;
 
@@ -58,10 +56,6 @@ export abstract class RouteDefinition<
     this.#head = head as HeadStage<never>;
     return this;
   }
-  metadata(metadata: MetadataStage<RouteBaseArgs & Args>) {
-    this.#metadata = metadata as MetadataStage<never>;
-    return this;
-  }
   loading(render: (args: RouteBaseArgs & Args & Extra) => PromiseOrObject<ReactNode>) {
     this.#loading = render as (args: never) => PromiseOrObject<ReactNode>;
     return this;
@@ -136,7 +130,6 @@ export abstract class RouteDefinition<
     if (!render)
       throw new Error(`[route-convention] a ${this.kind}() chain ends with .render(), and this one has none`);
     const head = this.#head;
-    const metadata = this.#metadata;
     const loading = this.#loading;
     const module: PageModule & LayoutModule = {
       default: (async (props: RouteRenderProps) => await render(this.#argsOf(props) as never)) as never,
@@ -146,11 +139,6 @@ export abstract class RouteDefinition<
         : typeof head === "function"
           ? { generateHead: async (props: RouteRenderProps) => await head(this.#argsOf(props) as never) }
           : { head }),
-      ...(metadata === undefined
-        ? {}
-        : typeof metadata === "function"
-          ? { generateMetadata: async (props: RouteRenderProps) => await metadata(this.#argsOf(props) as never) }
-          : { metadata }),
       ...(loading
         ? {
             Loading: ((props: RouteRenderProps) =>

package/common/CodeTranscript.ts

@@ -4,6 +4,7 @@ import type {
   CodeAgentQuestion,
   CodeAgentSessionInfo,
   CodeAgentStopReason,
+  CodeAgentSubagent,
   CodeAgentToolOutcome,
   CodeAgentToolSummary,
 } from "akanjs/common";
@@ -46,6 +47,7 @@ export class CodeTranscript {
   #approval: CodeAgentApprovalRequest | undefined;
   #stopReason: CodeAgentStopReason | undefined;
   #queue = { steering: 0, followUp: 0 };
+  #subagents: CodeAgentSubagent[] = [];
   #openAssistant: string | undefined;
   #openThinking: string | undefined;
   #nextId = 0;
@@ -104,6 +106,11 @@ export class CodeTranscript {
     return this.#queue;
   }
 
+  /** The sub-agents running right now. Not a transcript row: they are a state, and the state is the list. */
+  get subagents() {
+    return this.#subagents;
+  }
+
   /** Bumped on every applied event, so a view can tell "changed" from "same" without comparing arrays. */
   get revision() {
     return this.#revision;
@@ -202,11 +209,16 @@ export class CodeTranscript {
         return;
       case "notice":
         return this.#notice(event.level, event.message);
+      case "subagent":
+        this.#subagents = event.agents;
+        return;
       case "error":
         return this.#notice("error", event.message);
       case "idle":
         this.#streaming = false;
         this.#queue = { steering: 0, followUp: 0 };
+
+        this.#subagents = [];
         this.#closeStreams(false);
         return;
       case "host":

package/common/codeAgentProfile.ts

@@ -21,6 +21,22 @@ export type CodeAgentApprovalPolicy = "never" | "writes" | "commands" | "all";
  */
 export type CodeAgentInteractionMode = "await" | "suspend";
 
+export interface CodeAgentModelInfo {
+  id: string;
+  name: string;
+  contextWindow?: number;
+  /** Whether this is the one the session is running on, which a listing has to mark rather than repeat. */
+  current: boolean;
+}
+
+/** One provider of the model catalogue, and whether a credential for it has been configured. */
+export interface CodeAgentProviderInfo {
+  id: string;
+  name: string;
+  authorized: boolean;
+  models: CodeAgentModelInfo[];
+}
+
 export interface CodeAgentMcpServerRef {
   name: string;
   transport: "stdio" | "http";
@@ -29,6 +45,44 @@ export interface CodeAgentMcpServerRef {
   args?: string[];
   url?: string;
   env?: Record<string, string>;
+  /** Sent on every http request. A server behind a static token needs nothing else. */
+  headers?: Record<string, string>;
+  /**
+   * What to use when the server answers `401` and asks for OAuth.
+   *
+   * Everything here is optional because the spec is discoverable: the challenge names the resource metadata,
+   * that names the authorization server, and most hosted servers register a client on demand. It is for the
+   * ones that do not — a provider issuing client ids by hand, or one whose scopes cannot be guessed.
+   */
+  oauth?: { clientId?: string; clientSecret?: string; scope?: string };
+}
+
+/**
+ * Where a server stands with its credential.
+ *
+ * `required` is not a failure: it is a server that answered correctly and said who may talk to it. Reporting
+ * it as unreachable would send someone to debug a server that is working exactly as designed.
+ */
+export type CodeAgentMcpAuthState = "none" | "authorized" | "required";
+
+/**
+ * One declared MCP server, as the session found it.
+ *
+ * A server that answered and one that was never reachable are both here: an integration that is silently
+ * absent is indistinguishable from one the model simply chose not to use, and the tool names are the only
+ * evidence of which of the two happened.
+ */
+export interface CodeAgentMcpStatus {
+  name: string;
+  transport: "stdio" | "http";
+  /** The command line or the url — what tells two entries of the same shape apart without opening the file. */
+  target: string;
+  /** Published tool names, already prefixed with the server the way the model sees them. */
+  tools: string[];
+  /** Why it published none, when it published none. */
+  error?: string;
+  /** Whether a credential was needed, and whether one was held. */
+  auth?: CodeAgentMcpAuthState;
 }
 
 export interface CodeAgentSubagentBudget {

package/common/codeAgentWire.ts

@@ -154,6 +154,23 @@ export interface CodeAgentApprovalRequest {
   policy: CodeAgentApprovalPolicy;
 }
 
+/**
+ * One sub-agent the `task` tool is currently running.
+ *
+ * `tokens` is read at the moment the frame is made, so a host that draws this rail sees the child's spend
+ * climb rather than learning it only once the child is gone — which is the number that decides whether to
+ * let it keep going. A finished sub-agent leaves the list: what it did is already in the tool row it closed.
+ */
+export interface CodeAgentSubagent {
+  /** The `task` call that opened it, so a host can line the row up with the tool row above. */
+  id: string;
+  kind: string;
+  /** The three-to-five words the model named the task with. */
+  description: string;
+  startedAt: number;
+  tokens: number;
+}
+
 export type CodeAgentEventBody =
   | { type: "session"; info: CodeAgentSessionInfo }
   | { type: "turn_start"; turnId: string }
@@ -180,6 +197,15 @@ export type CodeAgentEventBody =
   | { type: "retry"; attempt: number; maxAttempts: number; delayMs: number; message: string }
   | { type: "queue"; steering: string[]; followUp: string[] }
   | { type: "notice"; level: "info" | "warning" | "error"; message: string }
+  /**
+   * Every sub-agent running right now, whole rather than as a delta.
+   *
+   * A list is re-sent on every change and on a slow tick while any child runs, so a host that missed a frame
+   * converges on the next one instead of holding a row for a child that finished. It is the one thing a turn
+   * does that the transcript cannot show: a `task` call is one tool row that stays open for minutes while its
+   * child spends tokens nobody watching sees spent.
+   */
+  | { type: "subagent"; agents: CodeAgentSubagent[] }
   | { type: "error"; message: string; fatal: boolean }
   | { type: "idle" }
   /**
@@ -236,6 +262,7 @@ export const codeAgentEventPersistence: { [key in CodeAgentEventType]: "live" |
   retry: "live",
   queue: "live",
   notice: "live",
+  subagent: "live",
   error: "persist",
   idle: "live",
   host: "live",
@@ -380,6 +407,10 @@ export const codeAgentEventLabel = (event: CodeAgentEventBody): string => {
       return `queued ${event.steering.length} steering, ${event.followUp.length} follow-up`;
     case "notice":
       return `[${event.level}] ${event.message}`;
+    case "subagent":
+      return event.agents.length
+        ? event.agents.map((agent) => `${agent.kind} · ${agent.description}`).join(" | ")
+        : "no sub-agent running";
     case "error":
       return `error: ${event.message}`;
     case "idle":

package/common/index.ts

@@ -21,9 +21,13 @@ export {
   type CodeAgentApprovalPolicy,
   type CodeAgentBuiltinTool,
   type CodeAgentInteractionMode,
+  type CodeAgentMcpAuthState,
   type CodeAgentMcpServerRef,
+  type CodeAgentMcpStatus,
+  type CodeAgentModelInfo,
   type CodeAgentPresetName,
   type CodeAgentProfile,
+  type CodeAgentProviderInfo,
   type CodeAgentSubagentBudget,
   codeAgentDeniedPaths,
   codeAgentPresets,
@@ -49,6 +53,7 @@ export {
   type CodeAgentStartOptions,
   type CodeAgentState,
   type CodeAgentStopReason,
+  type CodeAgentSubagent,
   type CodeAgentToolOp,
   type CodeAgentToolOutcome,
   type CodeAgentToolSummary,

package/common/routeConvention.ts

@@ -13,9 +13,7 @@ export const PAGE_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "default",
   "pageConfig",
   "head",
-  "metadata",
   "generateHead",
-  "generateMetadata",
   "Loading",
 ]);
 export const LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([...PAGE_ROUTE_EXPORTS, "NotFound", "Error"]);
@@ -27,7 +25,6 @@ export const ROOT_LAYOUT_ROUTE_EXPORTS: ReadonlySet<string> = new Set([
   "reconnect",
   "wsConnect",
   "layoutStyle",
-  "gaTrackingId",
 ]);
 /** Root-layout exports that are plain config rather than components, so a PascalCase check cannot allow them. */
 export const RESERVED_ROUTE_CONFIG_EXPORTS: ReadonlySet<string> = new Set(

package/constant/constantRegistry.ts

@@ -238,16 +238,15 @@ export class ConstantRegistry {
       PurifiedModel<Model>
     >;
   }
-  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static serialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.serialize(singleModelRef as Cls, v)) as unknown as Value;
     } else if (modelRef === Map && value instanceof Map) {
+      if (!of) throw new Error("A Map needs its value type (of) to serialize");
       return Object.fromEntries(
-        [...value.entries()].map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.serialize(value as Cls, value)];
-        }),
+        [...value.entries()].map(([key, entry]: [string, unknown]) => [key, ConstantRegistry.serialize(of, entry)]),
       ) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._serialize(value as PrimitiveValue) as unknown as Value;
@@ -255,17 +254,15 @@ export class ConstantRegistry {
       return serialize(modelRef as ConstantCls, 0, value, "object", { nullable }) as unknown as Value;
     } else throw new Error(`No serialize function for modelRef: ${modelRef}`);
   }
-  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false): Value {
+  static deserialize<Value>(modelRef: Cls | Cls[], value: Value, nullable: boolean = false, of?: Cls | Cls[]): Value {
     if (Array.isArray(value) && Array.isArray(modelRef)) {
       const singleModelRef = modelRef.at(0);
       if (!singleModelRef) throw new Error("No model ref found");
       return value.map((v: object) => ConstantRegistry.deserialize(singleModelRef as Cls, v)) as unknown as Value;
-    } else if (modelRef === Map && value instanceof Map) {
-      return new Map(
-        Object.entries(value).map(([key, value]: [string, unknown]) => {
-          return [key, ConstantRegistry.deserialize(value as Cls, value)];
-        }),
-      ) as unknown as Value;
+    } else if (modelRef === Map && value !== null && typeof value === "object") {
+      if (!of) throw new Error("A Map needs its value type (of) to deserialize");
+      const entries: [string, unknown][] = value instanceof Map ? [...value.entries()] : Object.entries(value);
+      return new Map(entries.map(([key, entry]) => [key, ConstantRegistry.deserialize(of, entry)])) as unknown as Value;
     } else if (PrimitiveRegistry.has(modelRef as Cls)) {
       return (modelRef as typeof PrimitiveScalar)._parse(value as PrimitiveValue) as unknown as Value;
     } else if (ConstantRegistry.modelRefNameMap.has(modelRef as Cls)) {

package/document/dataLoader.ts

@@ -11,7 +11,12 @@ type BatchLoadFn<Key, Value> = (
 ) => PromiseLike<ReadonlyArray<Value | Error>> | ReadonlyArray<Value | Error>;
 
 interface DataLoaderOptions<Key, CacheKey> {
-  cache?: boolean;
+  /**
+   * How long a loaded key is answered from memory: `false` (the default) remembers nothing past its own batch,
+   * a number keeps each key for that many milliseconds, and `true` keeps it for the life of the loader. A model's
+   * loaders live as long as the process, so anything but `false` serves a stale document after it changes.
+   */
+  cache?: boolean | number;
   cacheKeyFn?: (key: Key) => CacheKey;
   batch?: boolean;
   batchScheduleFn?: (callback: () => void) => void;
@@ -27,20 +32,27 @@ interface BatchItem<Key, Value> {
 
 /** Minimal DataLoader-compatible batch loader used by Akan document resolvers. */
 export class DataLoader<Key, Value, CacheKey = Key> {
+  static readonly #minSweepSize = 1024;
   readonly name?: string;
   readonly #batchLoadFn: BatchLoadFn<Key, Value>;
-  readonly #cache: boolean;
+  readonly #ttl: number;
   readonly #cacheKeyFn: (key: Key) => CacheKey;
   readonly #batch: boolean;
   readonly #batchScheduleFn: (callback: () => void) => void;
   readonly #maxBatchSize: number;
-  readonly #promiseCache = new Map<CacheKey, Promise<Value>>();
+  readonly #promiseCache = new Map<CacheKey, { promise: Promise<Value>; expiresAt: number }>();
+  #sweepAt = DataLoader.#minSweepSize;
   #queue: BatchItem<Key, Value>[] = [];
   #scheduled = false;
 
   constructor(batchLoadFn: BatchLoadFn<Key, Value>, options: DataLoaderOptions<Key, CacheKey> = {}) {
     this.#batchLoadFn = batchLoadFn;
-    this.#cache = options.cache !== false;
+    this.#ttl =
+      options.cache === true
+        ? Number.POSITIVE_INFINITY
+        : typeof options.cache === "number" && options.cache > 0
+          ? options.cache
+          : 0;
     this.#cacheKeyFn = options.cacheKeyFn ?? ((key) => key as unknown as CacheKey);
     this.#batch = options.batch !== false;
     this.#batchScheduleFn = options.batchScheduleFn ?? ((callback) => queueMicrotask(callback));
@@ -50,17 +62,21 @@ export class DataLoader<Key, Value, CacheKey = Key> {
 
   load(key: Key): Promise<Value> {
     const cacheKey = this.#cacheKeyFn(key);
-    if (this.#cache) {
-      const cached = this.#promiseCache.get(cacheKey);
-      if (cached) return cached;
-    }
+    const cached = this.#cached(cacheKey);
+    if (cached) return cached;
 
     const promise = new Promise<Value>((resolve, reject) => {
       this.#queue.push({ key, resolve, reject });
       if (this.#batch) this.#schedule();
       else this.#dispatch();
     });
-    if (this.#cache) this.#promiseCache.set(cacheKey, promise);
+    if (this.#ttl > 0) {
+      this.#remember(cacheKey, promise);
+      
+      promise.catch(() => {
+        if (this.#promiseCache.get(cacheKey)?.promise === promise) this.#promiseCache.delete(cacheKey);
+      });
+    }
     return promise;
   }
 
@@ -80,13 +96,30 @@ export class DataLoader<Key, Value, CacheKey = Key> {
   }
 
   prime(key: Key, value: Value | Error): this {
-    if (!this.#cache) return this;
+    if (this.#ttl <= 0) return this;
     const cacheKey = this.#cacheKeyFn(key);
-    if (this.#promiseCache.has(cacheKey)) return this;
-    this.#promiseCache.set(cacheKey, value instanceof Error ? Promise.reject(value) : Promise.resolve(value));
+    if (this.#cached(cacheKey)) return this;
+    this.#remember(cacheKey, value instanceof Error ? Promise.reject(value) : Promise.resolve(value));
     return this;
   }
 
+  #cached(cacheKey: CacheKey): Promise<Value> | undefined {
+    if (this.#ttl <= 0) return undefined;
+    const entry = this.#promiseCache.get(cacheKey);
+    if (!entry) return undefined;
+    if (entry.expiresAt > Date.now()) return entry.promise;
+    this.#promiseCache.delete(cacheKey);
+    return undefined;
+  }
+
+  #remember(cacheKey: CacheKey, promise: Promise<Value>) {
+    this.#promiseCache.set(cacheKey, { promise, expiresAt: Date.now() + this.#ttl });
+    if (this.#promiseCache.size < this.#sweepAt) return;
+    const now = Date.now();
+    for (const [key, entry] of this.#promiseCache) if (entry.expiresAt <= now) this.#promiseCache.delete(key);
+    this.#sweepAt = Math.max(DataLoader.#minSweepSize, this.#promiseCache.size * 2);
+  }
+
   #schedule() {
     if (this.#scheduled) return;
     this.#scheduled = true;
@@ -159,7 +192,7 @@ export const createLoader = <Key, Value>(model: LoaderModel, fieldName = "id", d
       });
       return data as unknown as Promise<Value[]>;
     },
-    { name: "dataloader", cache: false },
+    { name: "dataloader" },
   );
 };
 export const createArrayLoader = <K, V>(model: LoaderModel, fieldName = "id", defaultQuery: QueryOf<unknown> = {}) => {
@@ -194,7 +227,7 @@ export const createArrayElementLoader = <K, V>(
       });
       return data as unknown as Promise<V[]>;
     },
-    { name: "dataloader", cache: false },
+    { name: "dataloader" },
   );
 };
 
@@ -214,7 +247,7 @@ export const createQueryLoader = <Key, Value>(
       });
       return data as unknown as Promise<Value[]>;
     },
-    { name: "dataloader", cache: false },
+    { name: "dataloader" },
   );
 };
 

package/document/loaderInfo.ts

@@ -15,25 +15,46 @@ export type ModelCls<
     _libsOnSchema: (schema: SchemaOf<any, any>) => void;
   }
 >;
+export interface LoaderOption {
+  /** `false` by default; a number of milliseconds, or `true` for as long as the process runs. */
+  cache?: boolean | number;
+}
+
 export class LoaderInfo<Doc = any, Key extends keyof Doc = keyof Doc, QueryArg = Doc[Key]> {
   type: LoaderType;
   field: Key | Key[];
   defaultQuery: QueryOf<unknown>;
+  cache: boolean | number;
   queryArg: QueryArg | undefined;
-  constructor(type: LoaderType, field: Key | Key[], defaultQuery: QueryOf<unknown> = {}) {
+  constructor(
+    type: LoaderType,
+    field: Key | Key[],
+    defaultQuery: QueryOf<unknown> = {},
+    { cache = false }: LoaderOption = {},
+  ) {
     this.type = type;
     this.field = field;
     this.defaultQuery = defaultQuery;
+    this.cache = cache;
   }
 }
 
 export const makeLoaderBuilder = <Doc>() => ({
-  byField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key>("field", fieldName, defaultQuery),
-  byArrayField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key>("arrayField", fieldName, defaultQuery),
-  byQuery: <Key extends keyof Doc & string>(queryKeys: readonly Key[], defaultQuery: QueryOf<unknown> = {}) =>
-    new LoaderInfo<Doc, Key, Pick<Doc, Key>>("query", queryKeys as Key[], defaultQuery),
+  byField: <Key extends keyof Doc & string>(
+    fieldName: Key,
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key>("field", fieldName, defaultQuery, option),
+  byArrayField: <Key extends keyof Doc & string>(
+    fieldName: Key,
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key>("arrayField", fieldName, defaultQuery, option),
+  byQuery: <Key extends keyof Doc & string>(
+    queryKeys: readonly Key[],
+    defaultQuery: QueryOf<unknown> = {},
+    option: LoaderOption = {},
+  ) => new LoaderInfo<Doc, Key, Pick<Doc, Key>>("query", queryKeys as Key[], defaultQuery, option),
 });
 
 export type LoaderBuilder<Doc = any> = (builder: ReturnType<typeof makeLoaderBuilder<Doc>>) => {

package/fetch/client/fetchClient.ts

@@ -544,7 +544,7 @@ export class FetchClient {
 
     const anyCruGuards = signal.cruGuards ?? signal.createGuards ?? signal.updateGuards ?? signal.removeGuards;
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
-    if (anyCruGuards) {
+    if (signal.getGuards) {
       this.#setHandlerFactory(names.viewModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.viewModel, `${refName}View`),
       );
@@ -557,6 +557,8 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
+    }
+    if (signal.getGuards && anyCruGuards) {
       this.#setHandlerFactory(names.editModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.editModel, `${refName}Edit`),
       );
@@ -569,17 +571,17 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      if (updateGuards) {
-        this.#setHandlerFactory(
-          names.mergeModel,
-          () =>
-            (async (modelOrId: string | { id: string }, data: UnknownRecord, option?: FetchPolicy) => {
-              const id = typeof modelOrId === "string" ? modelOrId : modelOrId.id;
-              const updateFn = this.#requireHandler(names.updateModel, names.mergeModel);
-              return await updateFn(id, data, option);
-            }) as FetchHandler,
-        );
-      }
+    }
+    if (updateGuards) {
+      this.#setHandlerFactory(
+        names.mergeModel,
+        () =>
+          (async (modelOrId: string | { id: string }, data: UnknownRecord, option?: FetchPolicy) => {
+            const id = typeof modelOrId === "string" ? modelOrId : modelOrId.id;
+            const updateFn = this.#requireHandler(names.updateModel, names.mergeModel);
+            return await updateFn(id, data, option);
+          }) as FetchHandler,
+      );
     }
 
     this.#setHandlerFactory(