akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/types/document/database.d.ts

@@ -1,26 +1,34 @@
-import type { MergedValues, PromiseOrObject } from "akanjs/base";
+import type { MergedValues } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import type { DocumentModel, QueryOf } from "akanjs/constant";
-import type { CacheAdaptor, CacheSetOptions } from "akanjs/service";
+import type { CacheAdaptor, CacheSetOptions, CacheValue } from "akanjs/service";
 import type { DataLoader } from "./dataLoader.d.ts";
 import type { DocumentUpdateInput } from "./documentQuery.d.ts";
 import type { ExtractQuery, ExtractSort, FilterInstance } from "./filterMeta.d.ts";
-import type { CRUDEventType, Mdl, SaveEventType, UpdateResult } from "./into.d.ts";
+import type { Mdl, SaveEventListener, SaveEventType, UpdateResult } from "./into.d.ts";
 import type { DataInputOf, FindQueryOption, ListQueryOption } from "./types.d.ts";
 export declare class CacheDatabase<T = unknown> {
     private readonly refName;
     private readonly cache;
     private logger;
     constructor(refName: string, cache: CacheAdaptor);
-    set(topic: string, key: string, value: string | number | Buffer, option?: CacheSetOptions): Promise<void>;
-    get<T extends string | number | Buffer>(topic: string, key: string): Promise<T | undefined>;
+    set(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    get<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
     delete(topic: string, key: string): Promise<void>;
+    getDel<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<T | undefined>;
+    setIfAbsent(topic: string, key: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    incr(topic: string, key: string, by?: number, option?: CacheSetOptions): Promise<number>;
+    hset(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<void>;
+    hget<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hdelete(topic: string, key: string, subKey: string): Promise<void>;
+    hkeys(topic: string, key: string): Promise<string[]>;
+    hentries<T extends CacheValue = CacheValue>(topic: string, key: string): Promise<[string, T][]>;
+    hclear(topic: string, key: string): Promise<void>;
+    hgetDel<T extends CacheValue = CacheValue>(topic: string, key: string, subKey: string): Promise<T | undefined>;
+    hsetIfAbsent(topic: string, key: string, subKey: string, value: CacheValue, option?: CacheSetOptions): Promise<boolean>;
+    hincr(topic: string, key: string, subKey: string, by?: number, option?: CacheSetOptions): Promise<number>;
 }
-/**
- * What `update<Filter>` returns. The patch cannot be a trailing parameter — a filter's own args may be optional,
- * and no tuple type puts a required element after those — and leading it reads backwards. So it lands here, on a
- * terminal `.set()` that mirrors the `UPDATE … SET …` it compiles to.
- */
+/** What `update<Filter>` returns: the patch cannot trail a filter's optional args, so it lands on `.set()`. */
 export interface UpdateChain<Doc = any> {
     set(update: DocumentUpdateInput<Doc>): Promise<UpdateResult>;
 }
@@ -63,7 +71,7 @@ type QueryMethodMap<Query, Doc, Insight, _FindQueryOption, _ListQueryOption, _Qu
     ], _QueryOfDoc> : never : never;
 };
 export type QueryMethodPart<Query, Sort, Obj, Doc, Insight, _FindQueryOption = FindQueryOption<Sort, Obj>, _ListQueryOption = ListQueryOption<Sort, Obj>, _QueryOfDoc = QueryOf<Doc>> = MergedValues<QueryMethodMap<Query, Doc, Insight, _FindQueryOption, _ListQueryOption, _QueryOfDoc>>;
-type DatabaseModelWithQuerySort<T extends string, Input, Doc, Obj, Insight, Query, Sort, _CapitalizedRefName extends string = Capitalize<T>, _QueryOfDoc = QueryOf<Doc>, _DocumentObj = DocumentModel<Obj>, _DataInput = DataInputOf<Input, _DocumentObj>, _FindQueryOption = FindQueryOption<Sort, Obj>, _ListQueryOption = ListQueryOption<Sort, Obj>> = {
+export type DatabaseInstanceWithQuerySort<T extends string = string, Input = any, Doc = any, Obj = any, Insight = any, Query = ExtractQuery<FilterInstance>, Sort = ExtractSort<FilterInstance>, _CapitalizedRefName extends string = Capitalize<T>, _QueryOfDoc = QueryOf<Doc>, _DocumentObj = DocumentModel<Obj>, _DataInput = DataInputOf<Input, _DocumentObj>, _FindQueryOption = FindQueryOption<Sort, Obj>, _ListQueryOption = ListQueryOption<Sort, Obj>> = {
     logger: Logger;
     __model: Mdl<Doc, Obj, _DocumentObj>;
     __cache: CacheDatabase<T>;
@@ -90,8 +98,8 @@ type DatabaseModelWithQuerySort<T extends string, Input, Doc, Obj, Insight, Quer
     clone(data: _DataInput & {
         id: string;
     }): Promise<Doc>;
-    listenPre: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => () => void;
-    listenPost: (type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => () => void;
+    listenPre: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
+    listenPost: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
 } & {
     [key in _CapitalizedRefName]: Mdl<Doc, Obj, _DocumentObj>;
 } & {
@@ -111,6 +119,5 @@ type DatabaseModelWithQuerySort<T extends string, Input, Doc, Obj, Insight, Quer
 } & {
     [K in `remove${_CapitalizedRefName}`]: (id: string) => Promise<Doc>;
 } & QueryMethodPart<Query, Sort, Obj, Doc, Insight, _FindQueryOption, _ListQueryOption, _QueryOfDoc>;
-export type DatabaseInstanceWithQuerySort<T extends string = string, Input = any, Doc = any, Obj = any, Insight = any, Query = ExtractQuery<FilterInstance>, Sort = ExtractSort<FilterInstance>, _CapitalizedRefName extends string = Capitalize<T>, _QueryOfDoc = QueryOf<Doc>, _DocumentObj = DocumentModel<Obj>, _DataInput = DataInputOf<Input, _DocumentObj>, _FindQueryOption = FindQueryOption<Sort, Obj>, _ListQueryOption = ListQueryOption<Sort, Obj>> = DatabaseModelWithQuerySort<T, Input, Doc, Obj, Insight, Query, Sort, _CapitalizedRefName, _QueryOfDoc, _DocumentObj, _DataInput, _FindQueryOption, _ListQueryOption>;
 export type DatabaseInstance<T extends string = string, Input = any, Doc = any, Obj = any, Insight = any, Filter extends FilterInstance = FilterInstance, _CapitalizedRefName extends string = Capitalize<T>, _QueryOfDoc = QueryOf<Doc>, _Query = ExtractQuery<Filter>, _Sort = ExtractSort<Filter>, _DocumentObj = DocumentModel<Obj>, _DataInput = DataInputOf<Input, _DocumentObj>, _FindQueryOption = FindQueryOption<_Sort, Obj>, _ListQueryOption = ListQueryOption<_Sort, Obj>> = DatabaseInstanceWithQuerySort<T, Input, Doc, Obj, Insight, _Query, _Sort, _CapitalizedRefName, _QueryOfDoc, _DocumentObj, _DataInput, _FindQueryOption, _ListQueryOption>;
 export {};

package/types/document/documentQuery.d.ts

@@ -36,7 +36,8 @@ export type DocumentQueryNode = {
 } & DocumentSearchOptions);
 /** The four real SQL columns. Everything else lives inside `_doc`, which is what makes the two compile differently. */
 export declare const baseDocumentColumns: Set<string>;
-export type DocumentQueryOperator = "eq" | "ne" | "oneOf" | "notOneOf" | "gt" | "gte" | "lt" | "lte" | "between" | "exists" | "missing" | "empty" | "has" | "contains";
+declare const documentQueryOperators: readonly ["eq", "ne", "oneOf", "notOneOf", "gt", "gte", "lt", "lte", "between", "exists", "missing", "empty", "has", "contains"];
+export type DocumentQueryOperator = (typeof documentQueryOperators)[number];
 /** The operator-object shorthand's keys: `{ status: { oneOf: [...] } }` reaches the same operators as `q.oneOf`. */
 export declare const queryOperatorKeys: Set<string>;
 export type DocumentQueryValue = DocumentPrimitive | DocumentPrimitive[] | DocumentQueryNode | undefined | Record<string, unknown>;
@@ -148,3 +149,7 @@ export declare const documentQueryHelper: {
 };
 export declare const encodeDocumentValue: (value: unknown) => unknown;
 export declare const sanitizeJson: (value: unknown) => unknown;
+export declare const convertAggregateMatch: (query: unknown) => {
+    [k: string]: unknown;
+};
+export {};

package/types/document/documentSchema.d.ts

@@ -14,15 +14,10 @@ export interface DocumentIndexBuilder<Schema> {
     where(where: DocumentQuery | ((q: DocumentQueryHelper) => DocumentQuery)): DocumentIndexBuilder<Schema>;
     done(): Schema;
 }
-/**
- * `previous` is the document as it was before this write, and is absent on a create.
- *
- * A hook that has to answer "did this leave the set it was in" cannot do it from the new value alone — a soft
- * delete and a field edit that moves a row out of a filter both look like an ordinary document afterwards. It is a
- * trailing optional parameter, so a listener that ignores it is unaffected.
- */
+/** `previous` is the document before this write (absent on a create), for a hook asking whether it left a set. */
 export type DocumentSaveHook<Doc = unknown> = (this: Doc, next?: () => void, type?: CRUDEventType, previous?: Doc) => PromiseOrObject<void>;
 export declare class DocumentSchema<Doc = unknown> {
+    #private;
     readonly preHooks: Map<SaveEventType, DocumentSaveHook<Doc>[]>;
     readonly postHooks: Map<SaveEventType, DocumentSaveHook<Doc>[]>;
     readonly indexes: DocumentIndexDescriptor[];
@@ -37,3 +32,4 @@ export declare class DocumentSchema<Doc = unknown> {
 export type SchemaOf<Mdl = unknown, Doc = unknown> = DocumentSchema<Doc> & {
     readonly __model?: Mdl;
 };
+export declare const getDefaultSchemaOptions: <TSchema, TDocument>() => DocumentSchema<TDocument>;

package/types/document/filterMeta.d.ts

@@ -19,10 +19,7 @@ export declare const getFilterInfoByKey: <ArgNames extends string[] = [], Args e
 export declare const setFilterInfoByKey: <ArgNames extends string[] = [], Args extends any[] = any[], Model = any>(modelRef: Cls<Model>, key: string, filterInfo: FilterInfo<ArgNames, Args, Model>) => void;
 export declare const getFilterSortByKey: (modelRef: FilterCls, key: string) => unknown;
 export declare const fillMissingFilterArgs: (filterInfo: FilterInfo, args: unknown[]) => any[];
-/**
- * Splits a generated filter method's arguments into the filter's own args and the trailing query option.
- * Shared by the database and service resolvers so the two cannot drift into disagreeing about what an option is.
- */
+/** Shared by the database and service resolvers, so the two cannot disagree about what a query option is. */
 export declare const splitFilterArgs: (filterInfo: FilterInfo, args: unknown[]) => {
     queryArgs: any[];
     queryOption: Record<string, unknown>;
@@ -42,10 +39,8 @@ export declare const getFilterArgInfos: (filterInfo: FilterInfo) => FilterArgInf
 export declare class FilterQueryError extends Error {
 }
 /**
- * Compiles a `(queryKey, args)` pair into the query its filter declares — the root slice's whole contract.
- * Every arg is parsed by the type the filter declared for it, so a Date arg reaches the query as a Dayjs and
- * an id that is not one is refused here rather than becoming a query that matches nothing. Args past the
- * declared ones are dropped: the caller names a filter, never a query.
+ * The root slice's contract: each arg is parsed by its declared type (an invalid id is refused rather than matching
+ * nothing), and args past the declared ones are dropped — the caller names a filter, never a query.
  */
 export declare const resolveFilterQuery: (filterRef: FilterCls, queryKey?: string | null, args?: unknown[] | null) => QueryOf<any>;
 export declare const assertFilterFitsCrud: (refName: string, queryKey: string, className: string) => void;

package/types/document/index.d.ts

@@ -9,5 +9,4 @@ export * from "./into.d.ts";
 export * from "./loaderInfo.d.ts";
 export * from "./noDocumentError.d.ts";
 export * from "./queryEvaluator.d.ts";
-export * from "./schema.d.ts";
 export * from "./types.d.ts";

package/types/document/into.d.ts

@@ -8,6 +8,7 @@ import { type LoaderBuilder, type ModelCls } from "./loaderInfo.d.ts";
 import type { DocumentProjection } from "./types.d.ts";
 export type CRUDEventType = "create" | "update" | "remove";
 export type SaveEventType = "save" | CRUDEventType;
+export type SaveEventListener<Doc> = (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>;
 interface DefaultMdlStats<TDocument, TSchema, _Partial extends Partial<TSchema> = Partial<TSchema>, _FilterQuery extends DocumentQuery<TSchema> = DocumentQuery<TSchema>, _Projection = DocumentProjection<TSchema>> {
     pickOneAndWrite: (query: _FilterQuery, rawData: _Partial) => Promise<TDocument>;
     pickAndWrite: (docId: string, rawData: _Partial) => Promise<TDocument>;
@@ -15,8 +16,8 @@ interface DefaultMdlStats<TDocument, TSchema, _Partial extends Partial<TSchema>
     pickById: (docId: string | undefined, projection?: _Projection) => Promise<TDocument>;
     sample: (query: _FilterQuery, size?: number) => Promise<TDocument[]>;
     sampleOne: (query: _FilterQuery) => Promise<TDocument | null>;
-    listenPre: (eventType: SaveEventType, listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>) => () => void;
-    listenPost: (eventType: SaveEventType, listener: (doc: TDocument, type: CRUDEventType, previous?: TDocument) => PromiseOrObject<void>) => () => void;
+    listenPre: (eventType: SaveEventType, listener: SaveEventListener<TDocument>) => () => void;
+    listenPost: (eventType: SaveEventType, listener: SaveEventListener<TDocument>) => () => void;
 }
 export interface UpdateResult {
     acknowledged: boolean;

package/types/document/loaderInfo.d.ts

@@ -9,17 +9,22 @@ export type ModelCls<Statics = Record<never, never>, LoaderMap extends {
     _onSchema: (schema: SchemaOf<any, any>) => void;
     _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 declare 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 }?: LoaderOption);
 }
 export declare const makeLoaderBuilder: <Doc>() => {
-    byField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery?: QueryOf<unknown>) => LoaderInfo<Doc, Key, Doc[Key]>;
-    byArrayField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery?: QueryOf<unknown>) => LoaderInfo<Doc, Key, Doc[Key]>;
-    byQuery: <Key extends keyof Doc & string>(queryKeys: readonly Key[], defaultQuery?: QueryOf<unknown>) => LoaderInfo<Doc, Key, Pick<Doc, Key>>;
+    byField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery?: QueryOf<unknown>, option?: LoaderOption) => LoaderInfo<Doc, Key, Doc[Key]>;
+    byArrayField: <Key extends keyof Doc & string>(fieldName: Key, defaultQuery?: QueryOf<unknown>, option?: LoaderOption) => LoaderInfo<Doc, Key, Doc[Key]>;
+    byQuery: <Key extends keyof Doc & string>(queryKeys: readonly Key[], defaultQuery?: QueryOf<unknown>, option?: LoaderOption) => LoaderInfo<Doc, Key, Pick<Doc, Key>>;
 };
 export type LoaderBuilder<Doc = any> = (builder: ReturnType<typeof makeLoaderBuilder<Doc>>) => {
     [key: string]: LoaderInfo<Doc, any, any>;

package/types/document/noDocumentError.d.ts

@@ -1,11 +1,6 @@
 /**
- * A `pick` or a `get` that matched nothing. Typed so a caller can tell "you asked for something that is not
- * there" from "we broke" — an agent-facing transport in particular must not log a stack and answer "the server
- * failed" every time a model guesses an id.
- *
- * The message is unchanged from the bare `Error` this replaces, because callers already match on it, and the
- * `statusCode` does not reach the HTTP layer: `isExceptionLike` wants a `toJSON` too, so a missing document
- * stays a 500 there until someone decides framework-wide that it should be a 404.
+ * A `pick` or `get` that matched nothing, so a caller can tell a missing document from a failure. Callers match on
+ * the message; `statusCode` does not reach HTTP (`isExceptionLike` also wants a `toJSON`), where it stays a 500.
  */
 export declare class NoDocumentError extends Error {
     readonly statusCode = 404;

package/types/document/queryEvaluator.d.ts

@@ -1,10 +1,7 @@
 import { type DocumentQuery } from "./documentQuery.d.ts";
 /**
- * A document as the database stores it: base columns as written, everything else inside one JSON payload.
- *
- * Membership is evaluated against this rather than against a hydrated model because that is what the SQL the
- * evaluator has to agree with actually reads. A hydrated instance has already had defaults filled, dates turned
- * back into `Dayjs`, and absent optional keys materialized as `undefined` — every one of which changes an answer.
+ * A document as stored: base columns plus one JSON payload. Evaluated against this, not a hydrated model, whose filled
+ * defaults, `Dayjs` dates and materialized `undefined` keys would each change an answer the SQL gives.
  */
 export interface DocumentRowView {
     id: unknown;
@@ -18,32 +15,18 @@ export type QueryFieldMap = Record<string, {
     getProps?: () => Record<string, unknown>;
 } & Record<string, unknown>>;
 /**
- * Answers "does this document match this query" in memory, reproducing what the SQL compiler would have asked the
- * database. Live sync routes a change to the rooms whose query it belongs to, and asking the database once per room
- * is not a thing that can be afforded on a write path.
- *
- * Every rule here mirrors a specific SQLite behaviour rather than a reasonable JavaScript reading of the same
- * operator, because the only property that matters is agreeing with `QueryCompiler` — a disagreement shows up as a
- * list that is quietly wrong, never as an error. `queryEvaluator.parity.test.ts` asks both and compares.
+ * Answers "does this document match this query" in memory for live sync, mirroring SQLite rather than JavaScript: a
+ * disagreement with `QueryCompiler` is a quietly wrong list, never an error (`queryEvaluator.parity.test.ts`).
  */
 export declare class DocumentQueryEvaluator {
     #private;
     constructor(fields?: QueryFieldMap);
     /**
-     * Why this query cannot be evaluated in memory, or null when it can.
-     *
-     * Three things are genuinely out of reach. `raw` carries SQL only the database can run, and `search` compiles to
-     * an fts5 JOIN whose bm25 ranking has no in-memory equivalent. `exists`/`missing` on a `_doc` field ask whether
-     * the key is in the stored JSON at all, and a document read back has already had every declared nullable field
-     * materialized as `null` (`SqlDocumentStore.decodeDocumentPayload`) — so a value in hand cannot tell an absent
-     * key from a stored null, and answering anyway would be wrong for exactly the rows the operator exists to find.
-     * `empty` covers both cases and is evaluable, which is the operator the guide already directs callers to.
-     *
-     * Callers decide what to do about it — this reports, it does not throw, because refusing a boot is a policy the
-     * signal layer owns.
+     * Why a query cannot be evaluated in memory, or null: `raw` SQL, an fts5 `search`, or `exists`/`missing` on a
+     * `_doc` field (a read-back document has its nullable fields materialized as `null`). Refusing is the signal's call.
      */
     static unevaluableReason(query: DocumentQuery | undefined): string | null;
     /** Splits a saved document into the row shape above, mirroring `SqlDocumentStore.toRow`. */
-    static rowViewOf(doc: Record<string, unknown>): DocumentRowView;
+    static rowViewOf({ id, createdAt, updatedAt, removedAt, ...payload }: Record<string, unknown>): DocumentRowView;
     evaluate(query: DocumentQuery | undefined, row: DocumentRowView): boolean;
 }

package/types/document/types.d.ts

@@ -33,4 +33,3 @@ export interface FindQueryOption<Sort = never, Obj = any> {
     sample?: boolean;
     select?: DocumentProjection<Obj>;
 }
-export type { SchemaOf } from "./documentSchema.d.ts";

package/types/fetch/client/fetchClient.d.ts

@@ -17,7 +17,6 @@ type ClientSignalMap<SigType extends {
 }> = {
     [K in keyof SigType as SigType[K] extends DatabaseSignal<any, any, any, any> ? K : never]: SigType[K] extends DatabaseSignal<any, any, infer SlceCls, any> ? ClientSignal<SlceCls["baseName"], SlceCls, SlceCls["srv"]["cnst"]> : never;
 };
-/** Runtime fetch client that registers serialized Akan signals as HTTP/WebSocket methods. */
 export declare class FetchClient {
     #private;
     private ErrorCls?;
@@ -28,7 +27,6 @@ export declare class FetchClient {
     readonly handler: Record<string, FetchHandler>;
     readonly slice: Record<string, SliceMeta>;
     readonly sortKeyMap: 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: Map<string, {
         [key: string]: {
             [path: string]: 1 | -1;
@@ -44,17 +42,14 @@ export declare class FetchClient {
     constructor(origin: string, handler?: Record<string, FetchHandler>, serializedSignal?: {
         [key: string]: SerializedSignal;
     }, ErrorCls?: ErrorConstructor | undefined);
-    /**
-     * 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;
     };
     static resetSharedRegistry(): void;
     static resetSharedClient(): void;
+    /** For calls neither the caller nor the endpoint budgets; `false` waits as long as the runtime will (minutes). */
+    setTimeout(timeout?: number | false): void;
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
     applySignal(serializedSignal: {
         [key: string]: SerializedSignal;
@@ -88,11 +83,13 @@ export declare class FetchClient {
         fetch: any;
     }>(constant: object, serializedSignal: {
         [key: string]: SerializedSignal;
-    }, { origin, connect, base, Err, }?: {
+    }, { origin, connect, base, Err, 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"];

package/types/fetch/client/fetchHandle.d.ts

@@ -1,19 +1,11 @@
 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 declare 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>[], settle: () => Promise<Awaited>, fields: FieldFactories<Handle>): PromiseLike<Awaited> & Handle;
     /** The awaited shape's fields stay lazy for the same reason the handle's do: a caller reads one, not all. */

package/types/fetch/client/httpClient.d.ts

@@ -15,6 +15,8 @@ export declare class HttpClient {
     private ErrorCls?;
     constructor(baseUrl: string, options?: HttpClientOptions);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
+    /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+    setTimeout(timeout?: number | false): void;
     get<Returns = unknown>(url: string, options?: FetchOptions): Promise<Returns>;
     send<Returns = unknown>(method: HttpMutationMethod, url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;
     put<Returns = unknown>(url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;
@@ -22,6 +24,8 @@ export declare class HttpClient {
     delete<Returns = unknown>(url: string, options?: FetchOptions): Promise<Returns>;
     static makePath(key: string, paramArgs: SerializedArg[], prefix?: string): string;
     static makeUrl(path: string, searchArgs: SerializedArg[], argMap: Map<string, unknown>): string;
-    static makeBody(bodyArgs: SerializedArg[], uploadArgs: SerializedArg[], argMap: Map<string, unknown>): Record<string, unknown> | FormData;
+    static makeBody(bodyArgs: SerializedArg[], uploadArgs: SerializedArg[], argMap: Map<string, unknown>): FormData | {
+        [k: string]: unknown;
+    };
 }
 export {};

package/types/fetch/client/remoteError.d.ts

@@ -19,13 +19,7 @@ export interface ErrorConstructor {
     fromJSON: (payload: ErrorResponsePayload) => RestoredError;
 }
 /**
- * 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 declare const restoreRemoteError: (body: unknown, fallbackStatusCode: number, ErrorCls?: ErrorConstructor) => RestoredError;

package/types/fetch/client/sliceInitHandle.d.ts

@@ -16,11 +16,8 @@ export interface SliceInitInput {
     insight: new (obj?: unknown) => object;
 }
 /**
- * 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 declare class SliceInitHandle {
     #private;

package/types/fetch/client/sliceQueryArgs.d.ts

@@ -0,0 +1,3 @@
+import type { SerializedArg } from "akanjs/signal";
+export declare const normalizeQueryArgs: (queryArgs: unknown[], args: SerializedArg[]) => unknown[];
+export declare const expandQueryArgs: (queryArgs: unknown[], args: SerializedArg[]) => unknown[];

package/types/fetch/client/wsClient.d.ts

@@ -5,6 +5,12 @@ export interface WsClientReconnectOptions {
     interval?: number;
     maxAttempts?: number;
 }
+interface RoomSubscription {
+    key: string;
+    data: unknown[];
+    handleEvent: (data: unknown) => void;
+    handleResync?: () => void;
+}
 type WsRequestPayload = unknown | unknown[];
 export declare class WsClient {
     #private;
@@ -16,9 +22,8 @@ export declare class WsClient {
     constructor(url: string, ErrorCls?: ErrorConstructor | undefined);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
     /**
-     * The handshake only carries a same-origin cookie, so clients that hold the token in memory
-     * (native, cross-origin) authenticate with this frame instead. Signing out sends `null`, which
-     * drops the handshake cookie server-side and revokes the rooms it had authorized.
+     * For clients holding the token in memory (native, cross-origin): the handshake carries only a same-origin cookie.
+     * `null` drops that cookie server-side and revokes the rooms it authorized.
      */
     setJwt(jwt: string | null): void;
     connect(): void;
@@ -29,17 +34,7 @@ export declare class WsClient {
     removeAllListeners(key: string): this;
     hasListeners(key: string): boolean;
     emit(key: string, data: WsRequestPayload): this;
-    subscribe(option: {
-        key: string;
-        data: unknown[];
-        handleEvent: (data: unknown) => void;
-        handleResync?: () => void;
-    }): this | undefined;
-    unsubscribe(option: {
-        key: string;
-        data: unknown[];
-        handleEvent: (data: unknown) => void;
-        handleResync?: () => void;
-    }): void;
+    subscribe(option: RoomSubscription): this;
+    unsubscribe(option: RoomSubscription): void;
 }
 export {};

package/types/fetch/fetchType/appliedReturn.type.d.ts

@@ -1,6 +1,5 @@
 import type { DataList, GetStateObject, PromiseOrObject } from "akanjs/base";
 import type { ExtractSort, FilterInstance } from "akanjs/document";
-/** Metadata that identifies a generated slice list/insight request. */
 export type SliceMeta = {
     refName: string;
     sliceName: string;
@@ -9,17 +8,9 @@ export type SliceMeta = {
 /** What the root slice takes: one of the model's declared filter queries, and the args that filter asks for. */
 export interface QuerySetting {
     queryKey: string;
-    /**
-     * Read when the query is applied rather than when the setting is written, so a thunk keeps an arg relative to
-     * now — `() => [dayjs().subtract(1, "hour")]` — current at the moment the user asks for it.
-     */
+    /** Read when the query is applied, so a thunk keeps an arg relative to now. */
     args?: unknown[] | (() => unknown[]);
-    /**
-     * The same list under the name the rest of the framework already uses for it — the `queryArgsOf<Model>` state
-     * key, `refresh<Model>({ queryArgs })`, and a field's own `.meta(...)` declaration. Accepted so a query a
-     * field declares is one of these as it stands, rather than something every caller has to rename by hand.
-     * `args` wins when both are given.
-     */
+    /** `args` under the framework's usual name (`queryArgsOf<Model>`, a field's `.meta(...)`); `args` wins over it. */
     queryArgs?: unknown[] | (() => unknown[]);
 }
 type ServerInitShape<RefName extends string, QueryArgs, CapRefName extends string, LightObj, InsightObj, Sort> = SliceMeta & {
@@ -42,7 +33,6 @@ type ServerInitShape<RefName extends string, QueryArgs, CapRefName extends strin
     [K in `${RefName}InitAt`]: Date;
 };
 export type ServerInit<RefName extends string, Light, Insight = any, QueryArgs = any, Filter extends FilterInstance = any> = ServerInitShape<RefName, QueryArgs, Capitalize<RefName>, GetStateObject<Light>, GetStateObject<Insight>, ExtractSort<Filter>>;
-/** Client/server-friendly return type for initialized list and insight data. */
 export type ClientInit<RefName extends string, Light, Insight = any, QueryArgs = any, Filter extends FilterInstance = any> = PromiseOrObject<ServerInit<RefName, Light, Insight, QueryArgs, Filter>>;
 export type ServerView<RefName extends string, Model> = {
     refName: RefName;
@@ -51,7 +41,6 @@ export type ServerView<RefName extends string, Model> = {
 } & {
     [K in `${RefName}ViewAt`]: Date;
 };
-/** Client/server-friendly return type for a single model view payload. */
 export type ClientView<RefName extends string, Model> = PromiseOrObject<ServerView<RefName, Model>>;
 export type ServerEdit<RefName extends string, Model> = {
     refName: RefName;
@@ -71,11 +60,7 @@ export type EditReturn<RefName extends string, Full> = {
 } & {
     [K in `${RefName}Edit`]: ServerEdit<RefName, Full>;
 };
-/**
- * What `fetch.view<Model>` / `fetch.edit<Model>` / `fetch.init<Model><Suffix>` return: awaitable for the shape
- * the helper has always given, and destructurable into one promise per field for a route that wants each
- * section to render as its own data lands instead of holding the page for the slowest.
- */
+/** Awaitable as the shape the helper always gave, and destructurable into one promise per field. */
 export type FetchHandleOf<Awaited, Fields> = PromiseLike<Awaited> & Fields;
 export type ViewHandle<RefName extends string, Full> = FetchHandleOf<ViewReturn<RefName, Full>, {
     [K in RefName]: Promise<Full>;
@@ -102,11 +87,8 @@ export type InitReturn<RefName extends string, Suffix extends string, Light, Ins
     id: string;
 }, Insight>;
 /**
- * The list resolves without waiting for the aggregate, so `x<Slice>List` lands before `x<Slice>Init` — which
- * carries `lastPageOf<Model>` and therefore needs the count.
- *
- * `x<Slice>List` and `x<Slice>Insight` hold hydrated model instances, which React Flight refuses as props to a
- * client component: consume them in a server component and hand `x<Slice>Init` to a `Zone`.
+ * `x<Slice>List` lands before `x<Slice>Init`, which needs the count. List and Insight hold hydrated instances React
+ * Flight refuses as client props: consume them in a server component and hand `x<Slice>Init` to a `Zone`.
  */
 type InitHandleShape<RefName extends string, CapSuffix extends string, Init, ListItem extends {
     id: string;

package/types/fetch/fetchType/buildFetch.type.d.ts

@@ -1,4 +1,5 @@
-import type { DatabaseSignal, EndpointCls, SerializedSignal, ServiceSignal, SliceCls } from "akanjs/signal";
+import type { ConstantModel } from "akanjs/constant";
+import type { DatabaseSignal, EndpointCls, SerializedSignal, SerializedSlice, ServiceSignal, SliceCls } from "akanjs/signal";
 import type { FetchProxy } from "../client.d.ts";
 import type { GetSliceMetaObjFromDatabaseSignals } from "../types.d.ts";
 import type { SliceMeta } from "./appliedReturn.type";
@@ -36,4 +37,17 @@ type MergeDirectFetchTypes<Signals extends readonly FetchSignalInput[], Acc = Re
 } ? MergeDirectFetchTypes<Rest, Acc> : MergeDirectFetchTypes<Rest, Acc & FetchTypeOfSignal<First>> : Acc;
 export type MergeAllFetchTypes<Signals extends readonly FetchSignalInput[]> = MergeProxyFetchTypes<Signals> extends infer ProxyFetch ? MergeDirectFetchTypes<Signals> extends infer DirectFetch ? Omit<ProxyFetch, keyof DirectFetch> & DirectFetch : never : never;
 export type FetchClientType<Signals extends readonly FetchSignalInput[]> = FetchProxy<MergeAllFetchTypes<Signals>, GetSliceMetaObjFromDatabaseSignals<Signals>>;
+export type ClientSlice = {
+    refName: string;
+    sliceName: string;
+    serializedSlice: SerializedSlice;
+};
+export type ClientSignal<RefName extends string = string, SlceCls extends SliceCls = SliceCls, Cnst extends ConstantModel = ConstantModel> = {
+    refName: RefName;
+    _slice: SlceCls;
+    cnst: Cnst;
+    fetch: FetchProxy<any>;
+    slices: ClientSlice[];
+    serializedSignal: SerializedSignal;
+};
 export {};

package/types/fetch/fetchType/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./appliedReturn.type";
 export * from "./buildFetch.type";
-export * from "./clientSignal.type";
 export * from "./endpointFetch.type";
 export * from "./sliceFetch.type";

package/types/fetch/requestStorage.d.ts

@@ -40,15 +40,12 @@ declare global {
 }
 export declare const requestStorage: RequestStorage | null;
 export declare function createRequestStore(request: Request, policy?: Partial<Omit<AkanRequestPolicy, "tags">>): AkanRequestStore;
-/** Stores theme preference on the active request when server rendering. */
 export declare function setRequestTheme(theme: AkanTheme | undefined): void;
 export declare function getRequestTheme(): AkanTheme | undefined;
 export declare function setRequestFrameState(frameState: unknown): void;
 export declare function getRequestFrameState<FrameState = unknown>(): FrameState | undefined;
 export declare function pushRequestFallback(storeOrRequest: Request | AkanRequestStore): () => void;
-/** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
 export declare function getRequestStore(): AkanRequestStore | undefined;
-/** Returns the active server request from AsyncLocalStorage or the fallback stack. */
 export declare function getRequest(options?: {
     trackDynamic?: boolean;
 }): Request | undefined;
@@ -61,25 +58,15 @@ export declare function updateRequestPolicy(patch: Partial<Omit<AkanRequestPolic
 /** @internal Route cache tag collection is reserved for framework-owned cache policy experiments. */
 export declare function cacheTag(...tags: string[]): AkanRequestPolicy | undefined;
 export declare function getRequestDynamicUsage(): AkanDynamicUsage | undefined;
-/**
- * Deduplicates a promise-producing query within the active request, and says whether this caller is the one
- * that started it.
- *
- * `owned` is what lets the caller skip copying the response. The copy exists because one response object is
- * handed to every caller in the request and a parsed model can hold references into it, so a second caller must
- * not be given the same graph — but a query asked for once (which is nearly all of them: the key carries the
- * URL and the auth headers) has no second caller to protect, and copying for it is a whole JSON round-trip
- * spent on nothing.
- */
+/** Deduplicates within the active request; `owned` means this caller started it and may skip the defensive copy. */
 export declare function claimRequestQuery<T>(key: string, factory: () => Promise<T>): {
     value: Promise<T>;
     owned: boolean;
 };
 /** Appends to the active request's query log; outside a request there is nothing to read it, so nothing is kept. */
 export declare function recordRequestQuery(record: RequestQueryRecord): void;
-/** Deduplicates a promise-producing query within the active request. */
 export declare function memoizeRequestQuery<T>(key: string, factory: () => Promise<T>): Promise<T>;
-/** Returns current request headers as a Map, or an empty Map outside a request. */
+/** An empty Map outside a request. */
 export declare function headers(options?: {
     trackDynamic?: boolean;
 }): Map<string, string>;
@@ -90,7 +77,7 @@ export interface CookieEntry {
     value: string;
 }
 export declare function parseCookieHeader(cookieHeader: string): Map<string, CookieEntry>;
-/** Returns parsed cookies from the current request, or an empty Map outside a request. */
+/** An empty Map outside a request. */
 export declare function cookies(options?: {
     trackDynamic?: boolean;
 }): Map<string, CookieEntry>;

package/types/fetch/types.d.ts

@@ -1,7 +1,6 @@
 import { type Environment, type SLICE_META } from "akanjs/base";
 import type { DatabaseSignal } from "akanjs/signal";
 import type { SliceMeta } from "./fetchType/appliedReturn.type";
-/** Account data made available to services for the current app/environment. */
 export type Account<AddData = unknown> = {
     appName: string;
     environment: Environment;