akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/fetch/client/fetchClient.ts

@@ -1,4 +1,4 @@
-import { getEnv, getWsPrefix, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
+import { getApiPrefix, getEnv, getWsPrefix, PrimitiveRegistry, type PromiseOrObject } from "akanjs/base";
 import {
   capitalize,
   type FetchPolicy,
@@ -30,22 +30,13 @@ import { FetchHandle } from "./fetchHandle";
 import { HttpClient } from "./httpClient";
 import type { ErrorConstructor } from "./remoteError";
 import { SliceInitHandle } from "./sliceInitHandle";
+import { expandQueryArgs, normalizeQueryArgs } from "./sliceQueryArgs";
 import { WsClient } from "./wsClient";
 
 type FetchHandler = (...args: unknown[]) => PromiseOrObject<unknown>;
 type FetchHandlerFactory = () => FetchHandler;
 type UnknownRecord = Record<string, unknown>;
 
-const isNullableArg = (arg: SerializedArg) => arg.nullable ?? arg.type === "search";
-
-const normalizeQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => {
-  let length = Math.min(queryArgs.length, args.length);
-  while (length > 0 && isNullableArg(args[length - 1]) && queryArgs[length - 1] == null) length--;
-  return queryArgs.slice(0, length);
-};
-
-const expandQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => args.map((_, idx) => queryArgs[idx]);
-
 export type FetchProxy<
   FetchType = unknown,
   SliceMetaObj extends Record<string, SliceMeta> = Record<never, never>,
@@ -84,7 +75,6 @@ type ClientSignalMap<SigType extends { fetch: any }> = {
     : never;
 };
 
-/** Runtime fetch client that registers serialized Akan signals as HTTP/WebSocket methods. */
 export class FetchClient {
   static {
     ConstantRegistry.setScalar(agentTurnConstant.refName, agentTurnConstant);
@@ -96,7 +86,6 @@ export class FetchClient {
   readonly handler: Record<string, FetchHandler>;
   readonly slice: Record<string, SliceMeta> = {};
   readonly sortKeyMap = new Map<string, string[]>();
-  /** refName → sort key → the field map that key orders by. Read by live insertion, which has to place a row. */
   readonly sortValueMap = new Map<string, { [key: string]: { [path: string]: 1 | -1 } }>();
   readonly filterQueryMap = new Map<string, { [queryKey: string]: SerializedArg[] }>();
   readonly #originWs = new Map<string, WsClient>();
@@ -119,12 +108,7 @@ export class FetchClient {
     this.handler = this.#makeHandlerProxy();
     this.applySignal(serializedSignal);
   }
-  /**
-   * Every signal any client in this process has applied, which is the whole callable surface of the app.
-   *
-   * A copy, because this is the registry each client merges its own signals into and a reader that mutated it
-   * would change what the next client applies. Read by the agent catalogue, which needs the argument schemas.
-   */
+  /** A copy of every signal any client in this process applied, so a reader cannot change what the next applies. */
   static get sharedSerializedSignal(): { [key: string]: SerializedSignal } {
     return { ...sharedSignalRegistry.signal };
   }
@@ -173,6 +157,10 @@ export class FetchClient {
         }
       : signal;
   }
+  /** For calls neither the caller nor the endpoint budgets; `false` waits as long as the runtime will (minutes). */
+  setTimeout(timeout?: number | false) {
+    this.http.setTimeout(timeout);
+  }
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
@@ -197,10 +185,11 @@ export class FetchClient {
           this.#registerSlice(refName, suffix, slice, signal.prefix);
       }
       if (signal.filter) {
-
+        
         const filter = this.serializedSignal[refName]?.filter ?? signal.filter;
-        this.#registerFilterSortKey(refName, filter.sortKeys, filter.sorts);
-        this.#registerFilterQuery(refName, filter.filter);
+        this.sortKeyMap.set(refName, filter.sortKeys);
+        if (filter.sorts) this.sortValueMap.set(refName, filter.sorts);
+        this.filterQueryMap.set(refName, filter.filter);
       }
     }
     return this;
@@ -225,16 +214,10 @@ export class FetchClient {
   #getOrCreateHandler(key: string): FetchHandler | undefined {
     const current = this.#handlerStore[key];
     if (current) return current;
+    if (!this.#handlerFactory.has(key)) this.#syncSharedRegistry();
     const factory = this.#handlerFactory.get(key);
-    if (factory) {
-      const handler = factory();
-      this.#handlerStore[key] = handler;
-      return handler;
-    }
-    this.#syncSharedRegistry();
-    const syncedFactory = this.#handlerFactory.get(key);
-    if (!syncedFactory) return undefined;
-    const handler = syncedFactory();
+    if (!factory) return undefined;
+    const handler = factory();
     this.#handlerStore[key] = handler;
     return handler;
   }
@@ -269,7 +252,7 @@ export class FetchClient {
     this.ws.setJwt(jwt);
     for (const ws of this.#originWs.values()) ws.setJwt(jwt);
   }
-
+  
   #resolveWs(origin?: string) {
     if (!origin) return this.ws;
     const target = origin.replace(/\/+$/, "");
@@ -295,29 +278,32 @@ export class FetchClient {
     }
     return this.jwt ? { Authorization: `Bearer ${this.jwt}` } : {};
   }
-  #registerFilterSortKey(refName: string, sortKeys: string[], sorts?: { [key: string]: { [path: string]: 1 | -1 } }) {
-    this.sortKeyMap.set(refName, sortKeys);
-    if (sorts) this.sortValueMap.set(refName, sorts);
-  }
-  #registerFilterQuery(refName: string, filter: { [queryKey: string]: SerializedArg[] }) {
-    this.filterQueryMap.set(refName, filter);
+  #baseUrlOf(endpoint: SerializedEndpoint, origin?: string) {
+    if (endpoint.globalPrefix !== false) return origin;
+    const base = (origin ?? this.origin).replace(/\/$/, "");
+    const apiPrefix = getApiPrefix();
+    return base.endsWith(apiPrefix) ? base.slice(0, -apiPrefix.length) : base;
   }
   #makeHttpFn(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     const argLength = endpoint.args.length;
     const serializerMap = this.#makeArgSerializer(endpoint.args);
     const parseReturn = this.#makeReturnParser(endpoint.returns);
     const { bodyArgs, uploadArgs } = FetchClient.classifyHttpArgs(endpoint.args);
+    const requestOf = (argData: unknown[]) => {
+      const args = argData.slice(0, argLength);
+      const option = argData[argLength] as FetchPolicy | undefined;
+      const argMap = new Map(serializerMap.entries().map(([key, serializer], idx) => [key, serializer(args[idx])]));
+      return { option, argMap, url: FetchClient.makeHttpUrl(key, endpoint, prefix, argMap) };
+    };
     switch (endpoint.type) {
-      case "query": {
-        const queryFn = async (...argData: unknown[]) => {
-          const args = argData.slice(0, argLength);
-          const option = argData[argLength] as FetchPolicy | undefined;
-          const argMap = new Map(serializerMap.entries().map(([key, serializer], idx) => [key, serializer(args[idx])]));
-          const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
+      case "query":
+        return async (...argData: unknown[]) => {
+          const { option, argMap, url } = requestOf(argData);
           const headers = this.#makeAuthHeaders(option);
-          const baseUrl = option?.origin;
-
-          const requestQuery = () => this.http.get(url, { headers, baseUrl });
+          const baseUrl = this.#baseUrlOf(endpoint, option?.origin);
+          const timeout = option?.timeout ?? endpoint.timeout;
+          
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -327,38 +313,27 @@ export class FetchClient {
           const payload = claim.owned ? response : FetchClient.#deepCopy(response);
           return parseReturn(payload, { crystalize: option?.crystalize ?? true });
         };
-        return queryFn;
-      }
-      case "mutation": {
-        const mutationFn = async (...argData: unknown[]) => {
-          const args = argData.slice(0, argLength);
-          const option = argData[argLength] as FetchPolicy | undefined;
-          const argMap = new Map(serializerMap.entries().map(([key, serializer], idx) => [key, serializer(args[idx])]));
-          const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
+      case "mutation":
+        return async (...argData: unknown[]) => {
+          const { option, argMap, url } = requestOf(argData);
           const body = HttpClient.makeBody(bodyArgs, uploadArgs, argMap);
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeAuthHeaders(option),
-            baseUrl: option?.origin,
+            baseUrl: this.#baseUrlOf(endpoint, option?.origin),
+            timeout: option?.timeout ?? endpoint.timeout,
           });
-          const parsedReturn = parseReturn(response, { crystalize: option?.crystalize ?? true });
-          return parsedReturn;
+          return parseReturn(response, { crystalize: option?.crystalize ?? true });
         };
-        return mutationFn;
-      }
       default:
         throw new Error(`Unsupported endpoint type: ${endpoint.type}`);
     }
   }
   #registerEndpoint(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     switch (endpoint.type) {
-      case "query": {
-        this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
-        return;
-      }
-      case "mutation": {
+      case "query":
+      case "mutation":
         this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
-      }
       case "pubsub": {
         this.#setHandlerFactory(`subscribe${capitalize(key)}`, () => {
           const roomArgs = endpoint.args.filter((arg) => arg.type === "room");
@@ -454,11 +429,10 @@ export class FetchClient {
       modelId: `${refName}Id`,
       lightModel: `light${capRefName}`,
     };
-    
     const createGuards = signal.createGuards ?? signal.cruGuards;
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
     const removeGuards = signal.removeGuards ?? signal.cruGuards;
-
+    
     const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) => ({
       ...(signal.mcp?.[verb] === false ? { mcp: false as const } : {}),
       ...(signal.agents?.[verb] === false ? { agents: false as const } : {}),
@@ -515,12 +489,8 @@ export class FetchClient {
   #registerModelBaseEndpoint(refName: string, signal: SerializedSignal) {
     const capRefName = capitalize(refName);
     const names = {
-      createModel: `create${capRefName}`,
       updateModel: `update${capRefName}`,
-      removeModel: `remove${capRefName}`,
       model: refName,
-      modelId: `${refName}Id`,
-      lightModel: `light${capRefName}`,
       viewModel: `view${capRefName}`,
       getModelView: `get${capRefName}View`,
       editModel: `edit${capRefName}`,
@@ -535,42 +505,28 @@ 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`),
       );
-      this.#setHandlerFactory(
-        names.getModelView,
-        () =>
-          (async (id: string, option?: FetchPolicy) => {
-            const modelFn = this.#requireHandler(names.model, names.getModelView);
-            const modelObj = await modelFn(id, { ...option, crystalize: false });
-            return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
-          }) as FetchHandler,
-      );
+      this.#setHandlerFactory(names.getModelView, () => this.#makeModelObjFn(refName, names.getModelView));
+    }
+    if (signal.getGuards && anyCruGuards) {
       this.#setHandlerFactory(names.editModel, () =>
         this.#makeModelHandleFn(refName, names.model, names.editModel, `${refName}Edit`),
       );
+      this.#setHandlerFactory(names.getModelEdit, () => this.#makeModelObjFn(refName, names.getModelEdit));
+    }
+    if (updateGuards) {
       this.#setHandlerFactory(
-        names.getModelEdit,
+        names.mergeModel,
         () =>
-          (async (id: string, option?: FetchPolicy) => {
-            const modelFn = this.#requireHandler(names.model, names.getModelEdit);
-            const modelObj = await modelFn(id, { ...option, crystalize: false });
-            return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
+          (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(
@@ -590,16 +546,21 @@ export class FetchClient {
           formData.append(fields.type, refName);
           if (parentId) formData.append(fields.parentId, parentId);
           const url = FetchClient.makeHttpUrl(cap.endpointKey, endpoint, cap.prefix, new Map());
-          return await this.http.post(url, formData, { headers: this.#makeAuthHeaders(option) });
+          return await this.http.post(url, formData, {
+            headers: this.#makeAuthHeaders(option),
+            baseUrl: this.#baseUrlOf(endpoint),
+          });
         }) as FetchHandler,
     );
   }
 
-  /**
-   * `view<Model>` and `edit<Model>` differ only in the key their payload lands under, so they share one read.
-   * The full model is built lazily for the same reason a slice's list is: a route that only hands the payload to
-   * `Load.View` never reads it, and `ViewAt` is stamped once so two reads agree.
-   */
+  #makeModelObjFn(refName: string, callerKey: string) {
+    return (async (id: string, option?: FetchPolicy) => {
+      const modelObj = await this.#requireHandler(refName, callerKey)(id, { ...option, crystalize: false });
+      return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
+    }) as FetchHandler;
+  }
+
   #makeModelHandleFn(refName: string, modelKey: string, callerKey: string, payloadKey: string) {
     return ((id: string, option?: FetchPolicy) => {
       const cnst = ConstantRegistry.getDatabase(refName);
@@ -635,7 +596,7 @@ export class FetchClient {
       insight: `${refName}Insight${capSuffix}`,
       live: `${refName}Live${capSuffix}`,
     };
-
+    
     const mcp = {
       ...(slice.mcp === false ? { mcp: false as const } : {}),
       ...(slice.agents === false ? { agents: false as const } : {}),
@@ -679,7 +640,7 @@ export class FetchClient {
     };
 
     const endpoint = FetchClient.getEndpointFromSlice(refName, suffix, slice);
-
+    
     Object.entries(endpoint).forEach(([key, value]) => {
       this.#registerEndpoint(key, value, prefix);
     });
@@ -827,7 +788,15 @@ export class FetchClient {
       connect = false,
       base,
       Err,
-    }: { origin?: string; connect?: boolean; base?: FetchProxy; Err?: ErrorConstructor } = {},
+      timeout,
+    }: {
+      origin?: string;
+      connect?: boolean;
+      base?: FetchProxy;
+      Err?: ErrorConstructor;
+      /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+      timeout?: number | false;
+    } = {},
   ): {
     sig: ClientSignalMap<SigType>;
     fetch: SigType["fetch"];
@@ -838,6 +807,7 @@ export class FetchClient {
     const proxy =
       shared ??
       FetchClient.#makeProxy<unknown, Record<string, SliceMeta>>(new FetchClient(origin, {}, serializedSignal, Err));
+    if (timeout !== undefined) proxy.instance.setTimeout(timeout);
     if (connect) proxy.instance.connect();
     const sig = {} as any;
     Object.entries(serializedSignal).forEach(([refName, serializedSignal]) => {
@@ -865,7 +835,7 @@ export class FetchClient {
           if (handler) return handler;
         }
         const value = (instance as unknown as Record<PropertyKey, unknown>)[prop];
-
+        
         return typeof value === "function" ? value.bind(instance) : value;
       },
     }) as FetchProxy<FetchType, SliceMetaObj>;

package/fetch/client/fetchHandle.ts

@@ -1,18 +1,10 @@
 type FieldFactories<Handle> = { [Key in keyof Handle]: () => Handle[Key] };
 
-/**
- * A fetch result that is both awaitable and destructurable.
- *
- * `await` gives the object the helper has always given, so every existing call site reads unchanged. Reading a
- * field off the un-awaited result gives that field's own promise instead, so a route can hand each one to the
- * section that renders it and let the slowest arrive last rather than holding the whole page.
- */
+/** Awaitable as the shape a helper always gave, and destructurable into one promise per field. */
 export class FetchHandle {
   /**
-   * @param requests the calls already in flight. Each gets a swallowing handler so a field nobody reads cannot
-   *   surface as an unhandled rejection; the handle's own `then` is what reports one.
-   * @param settle builds the awaited shape — its own fields stay lazy, so awaiting costs nothing extra.
-   * @param fields one factory per field of the un-awaited shape, memoized on first read.
+   * Each of `requests` gets a swallowing handler, so a field nobody reads cannot surface as an unhandled rejection;
+   * `fields` factories are memoized on first read.
    */
   static of<Awaited extends object, Handle extends object>(
     requests: Promise<unknown>[],
@@ -39,7 +31,7 @@ export class FetchHandle {
         },
       });
     }
-
+    
     return Object.defineProperties(handle, {
       
       then: { value: (...args: unknown[]) => Reflect.apply(resolve().then, resolve(), args) },

package/fetch/client/httpClient.ts

@@ -24,14 +24,7 @@ const transportErrorKeyMap = {
 const serverUnreachableKey = "base.error.serverUnreachable";
 const unexpectedResponseKey = "base.error.unexpectedResponse";
 const transportDetailLimit = 200;
-/**
- * How long a call waits before giving up.
- *
- * Nothing else bounds it: a gateway answers a dead upstream with a 504, but a solo process has no gateway and a
- * severed connection produces no response at all — the request then sits until the browser's own limit, which is
- * minutes. The dictionary already has the wording for a slow server (`gatewayTimeout`), so this is the client
- * side of an answer that only existed for one deployment shape.
- */
+
 const DEFAULT_TIMEOUT_MS = 30_000;
 
 export class HttpClient {
@@ -49,13 +42,14 @@ export class HttpClient {
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
   }
-  #resolveBaseUrl(baseUrl?: string) {
-    return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
+  /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+  setTimeout(timeout?: number | false) {
+    this.#timeout = timeout;
   }
   #resolveUrl(url: string, options: FetchOptions) {
-    return `${this.#resolveBaseUrl(options.baseUrl)}${url}`;
+    return `${(options.baseUrl ?? this.baseUrl).replace(/\/$/, "")}${url}`;
   }
-
+  
   #makeHeaders(headers: Record<string, string>, options: FetchOptions) {
     return { Accept: "application/json", ...this.#headers, ...headers, ...options.headers };
   }
@@ -67,7 +61,7 @@ export class HttpClient {
     );
   }
   #makeReqContent(data: FormData | Record<string, unknown>): { body: BodyInit; headers: Record<string, string> } {
-
+    
     if (data instanceof FormData) return { body: data, headers: {} };
     return { body: JSON.stringify(data), headers: { "Content-Type": "application/json" } };
   }
@@ -108,30 +102,22 @@ export class HttpClient {
 
   async #request<Returns>(url: string, init: RequestInit, options: FetchOptions = {}): Promise<Returns> {
     const res = await this.#fetch(url, this.#withTimeout(init, options));
-    return await this.#readJsonResponse<Returns>(res);
+    const body = await this.#readBody(res);
+    if (res.ok) return body as Returns;
+    throw this.#restoreError(body, res.status);
   }
 
-  /**
-   * An upload gets no deadline of its own: a large file on a slow uplink is a long request that is working, and
-   * the request body is the only thing this side can tell that from. Everything else takes the default unless
-   * the caller named one.
-   */
   #withTimeout(init: RequestInit, options: FetchOptions): RequestInit {
     const timeout = options.timeout ?? (init.body instanceof FormData ? false : (this.#timeout ?? DEFAULT_TIMEOUT_MS));
     if (timeout === false || !Number.isFinite(timeout) || timeout <= 0) return init;
     return { ...init, signal: AbortSignal.timeout(timeout) };
   }
 
-  /**
-   * `fetch` rejects only when no response arrived at all — a refused connection, a DNS failure, a socket
-   * dropped mid-flight. That is the server being unreachable, not an error this API reported, so it is
-   * restored as one rather than surfacing the runtime's own `TypeError: Failed to fetch`.
-   */
   async #fetch(url: string, init: RequestInit) {
     try {
       return await fetch(url, init);
     } catch (error) {
-
+      
       if (error instanceof Error && error.name === "TimeoutError")
         throw this.#restoreError({ error: transportErrorKeyMap[408], data: { status: 408 } }, 408);
       if (error instanceof Error && error.name === "AbortError") throw error;
@@ -139,17 +125,6 @@ export class HttpClient {
     }
   }
 
-  async #readJsonResponse<Returns>(res: Response): Promise<Returns> {
-    const body = await this.#readBody(res);
-    if (res.ok) return body as Returns;
-    throw this.#restoreError(body, res.status);
-  }
-
-  /**
-   * A proxy answers a restarting upstream with a page of its own — nginx's `504 Gateway Time-out` HTML,
-   * the federation gateway's plain-text 503. That body is not this API's, so parsing it would surface the
-   * parser's complaint (`Unexpected token '<'`) instead of the fact that the server is down.
-   */
   async #readBody(res: Response) {
     if (jsonContentType.test(res.headers.get("content-type") ?? "")) {
       try {
@@ -189,9 +164,9 @@ export class HttpClient {
     searchArgs.forEach((arg) => {
       const argValue = argMap.get(arg.name);
       if (argValue === null || argValue === undefined) return;
-
+      
       if (arg.refName === "Any") {
-
+        
         const encoded = JSON.stringify(argValue);
         if (encoded !== undefined) searchParams.set(arg.name, encoded);
       } else if (arg.arrDepth && Array.isArray(argValue))
@@ -203,45 +178,37 @@ export class HttpClient {
     const searchPath = searchParams.size > 0 ? `?${searchParams.toString()}` : "";
     const paramedPath = path.replace(/:(\w+)/g, (match, p1) => {
       const value = argMap.get(p1);
-      return value === null || value === undefined ? match : String(value);
+      return value === null || value === undefined ? match : encodeURIComponent(String(value));
     });
     return `${paramedPath}${searchPath}`;
   }
-
+  
   static #toUploadValues(argValue: unknown): (Blob | string)[] {
     if (Array.isArray(argValue)) return argValue as (Blob | string)[];
     if (typeof FileList !== "undefined" && argValue instanceof FileList) return Array.from(argValue);
     return [argValue as Blob | string];
   }
   static makeBody(bodyArgs: SerializedArg[], uploadArgs: SerializedArg[], argMap: Map<string, unknown>) {
-    if (uploadArgs.length > 0) {
-      const formData = new FormData();
-      uploadArgs.forEach((arg) => {
-        const argValue = argMap.get(arg.name);
-        if (arg.nullable && (argValue === null || argValue === undefined)) return;
-        if (!arg.nullable && (argValue === null || argValue === undefined))
-          throw new Error(`Argument ${arg.name} is required`);
-        HttpClient.#toUploadValues(argValue).forEach((value) => {
-          formData.append(arg.name, value);
-        });
-      });
-      bodyArgs.forEach((arg) => {
-        const argValue = argMap.get(arg.name);
-        if (arg.nullable && (argValue === null || argValue === undefined)) return;
-        if (!arg.nullable && (argValue === null || argValue === undefined))
-          throw new Error(`Argument ${arg.name} is required`);
-        formData.append(arg.name, typeof argValue === "string" ? argValue : JSON.stringify(argValue));
-      });
-      return formData;
-    } else {
-      const body: Record<string, unknown> = {};
-      bodyArgs.forEach((arg) => {
-        const argValue = argMap.get(arg.name);
-        if (!arg.nullable && (argValue === null || argValue === undefined))
-          throw new Error(`Argument ${arg.name} is required`);
-        body[arg.name] = argValue;
+    const valueOf = (arg: SerializedArg) => {
+      const argValue = argMap.get(arg.name);
+      if (!arg.nullable && (argValue === null || argValue === undefined))
+        throw new Error(`Argument ${arg.name} is required`);
+      return argValue;
+    };
+    if (!uploadArgs.length) return Object.fromEntries(bodyArgs.map((arg) => [arg.name, valueOf(arg)]));
+    const formData = new FormData();
+    uploadArgs.forEach((arg) => {
+      const argValue = valueOf(arg);
+      if (argValue === null || argValue === undefined) return;
+      HttpClient.#toUploadValues(argValue).forEach((value) => {
+        formData.append(arg.name, value);
       });
-      return body;
-    }
+    });
+    bodyArgs.forEach((arg) => {
+      const argValue = valueOf(arg);
+      if (argValue === null || argValue === undefined) return;
+      formData.append(arg.name, typeof argValue === "string" ? argValue : JSON.stringify(argValue));
+    });
+    return formData;
   }
 }

package/fetch/client/remoteError.ts

@@ -22,14 +22,8 @@ export interface ErrorConstructor {
 }
 
 /**
- * Rebuilds what a remote process reported: the caller's own `Err` when this client was given one, and a
- * duck-typed `Error` carrying the same payload otherwise.
- *
- * The `toJSON` is what makes the second case rethrowable. A server process that calls another with `{ origin }`
- * and lets the failure propagate is answered by `SignalContext.try`, which forwards a payload only when the
- * thrown value carries both `statusCode` and `toJSON`; anything else is this repo's own bug and is generalized
- * to `Internal Server Error`. Without it the hop loses the dictionary key and its data, and the browser toasts
- * the generalization instead of the sentence the remote endpoint chose.
+ * The caller's own `Err` when given one, else a duck-typed `Error` with the same payload, whose `toJSON` lets
+ * `SignalContext.try` forward the remote key and data rather than generalize to `Internal Server Error`.
  */
 export const restoreRemoteError = (
   body: unknown,

package/fetch/client/sliceInitHandle.ts

@@ -21,11 +21,8 @@ export interface SliceInitInput {
 }
 
 /**
- * The two calls a slice's `init` makes and the three values callers read off them.
- *
- * The list does not wait for the aggregate: `x<Slice>List` resolves as soon as the rows land, while
- * `x<Slice>Init` — which carries `lastPageOf<Model>` and therefore needs the count — waits for both. Every
- * derived value is memoized, so the awaited shape and the un-awaited handle hand out the same instances.
+ * `x<Slice>List` resolves when the rows land; `x<Slice>Init` needs the count (`lastPageOf<Model>`) and waits for
+ * both. Derived values are memoized, so the awaited shape and the handle share instances.
  */
 export class SliceInitHandle {
   readonly #input: SliceInitInput;
@@ -78,7 +75,7 @@ export class SliceInitHandle {
       [`pageOf${capRefName}`]: page,
       [`lastPageOf${capRefName}`]: lastPage,
       [`limitOf${capRefName}`]: limit,
-
+      
       [`hasMoreOf${capRefName}`]: !!limit && modelObjList.length >= limit,
       [`queryArgsOf${capRefName}`]: queryArgs,
       [`sortOf${capRefName}`]: sort,

package/fetch/client/sliceQueryArgs.ts

@@ -0,0 +1,11 @@
+import type { SerializedArg } from "akanjs/signal";
+
+const isNullableArg = (arg: SerializedArg) => arg.nullable ?? arg.type === "search";
+
+export const normalizeQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => {
+  let length = Math.min(queryArgs.length, args.length);
+  while (length > 0 && isNullableArg(args[length - 1]) && queryArgs[length - 1] == null) length--;
+  return queryArgs.slice(0, length);
+};
+
+export const expandQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => args.map((_, idx) => queryArgs[idx]);