akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/fetch/fetchType/appliedReturn.type.ts

@@ -8,33 +8,62 @@ export type SliceMeta = {
   argLength: number;
 };
 
-export type ServerInit<
+/** 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.
+   */
+  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.
+   */
+  queryArgs?: unknown[] | (() => unknown[]);
+}
+
+type ServerInitShape<
   RefName extends string,
-  Light,
-  Insight = any,
-  QueryArgs = any,
-  Filter extends FilterInstance = any,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _LightObj = GetStateObject<Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
+  QueryArgs,
+  CapRefName extends string,
+  LightObj,
+  InsightObj,
+  Sort,
 > = SliceMeta & {
-  [K in `${RefName}ObjList`]: _LightObj[];
+  [K in `${RefName}ObjList`]: LightObj[];
 } & {
-  [K in `${RefName}ObjInsight`]: _InsightObj;
+  [K in `${RefName}ObjInsight`]: InsightObj;
 } & {
-  [K in `pageOf${_CapitalizedRefName}`]: number;
+  [K in `pageOf${CapRefName}`]: number;
 } & {
-  [K in `lastPageOf${_CapitalizedRefName}`]: number;
+  [K in `lastPageOf${CapRefName}`]: number;
 } & {
-  [K in `limitOf${_CapitalizedRefName}`]: number;
+  [K in `limitOf${CapRefName}`]: number;
 } & {
-  [K in `queryArgsOf${_CapitalizedRefName}`]: QueryArgs;
+  [K in `queryArgsOf${CapRefName}`]: QueryArgs;
 } & {
-  [K in `sortOf${_CapitalizedRefName}`]: _Sort;
+  [K in `sortOf${CapRefName}`]: Sort;
 } & {
   [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,
@@ -42,13 +71,7 @@ export type ClientInit<
   Insight = any,
   QueryArgs = any,
   Filter extends FilterInstance = any,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _LightObj = GetStateObject<Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
-> = PromiseOrObject<
-  ServerInit<RefName, Light, Insight, QueryArgs, Filter, _CapitalizedRefName, _LightObj, _InsightObj, _Sort>
->;
+> = PromiseOrObject<ServerInit<RefName, Light, Insight, QueryArgs, Filter>>;
 
 export type ServerView<RefName extends string, Model> = { refName: RefName } & {
   [K in `${RefName}Obj`]: GetStateObject<Model>;
@@ -77,6 +100,18 @@ export type EditReturn<RefName extends string, Full> = {
   [K in `${RefName}Edit`]: ServerEdit<RefName, Full>;
 };
 
+type InitReturnShape<
+  RefName extends string,
+  CapSuffix extends string,
+  Init,
+  ListItem extends { id: string },
+  Insight,
+> = {
+  [K in `${RefName}Init${CapSuffix}`]: Init;
+} & {
+  [K in `${RefName}List${CapSuffix}`]: DataList<ListItem>;
+} & { [K in `${RefName}Insight${CapSuffix}`]: Insight };
+
 export type InitReturn<
   RefName extends string,
   Suffix extends string,
@@ -84,25 +119,11 @@ export type InitReturn<
   Insight,
   Args,
   Filter extends FilterInstance,
-  _CapitalizedRefName extends string = Capitalize<RefName>,
-  _CapitalizedSuffix extends string = Capitalize<Suffix>,
-  _Light extends { id: string } = Light extends { id: string } ? Light : { id: string },
-  _LightObj = GetStateObject<_Light>,
-  _InsightObj = GetStateObject<Insight>,
-  _Sort = ExtractSort<Filter>,
-> = {
-  [K in `${RefName}Init${_CapitalizedSuffix}`]: ServerInit<
-    RefName,
-    Light,
-    Insight,
-    Args,
-    Filter,
-    _CapitalizedRefName,
-    _LightObj,
-    _InsightObj,
-    _Sort
-  >;
-} & {
-  [K in `${RefName}List${_CapitalizedSuffix}`]: DataList<_Light>;
-} & { [K in `${RefName}Insight${_CapitalizedSuffix}`]: Insight };
+> = InitReturnShape<
+  RefName,
+  Capitalize<Suffix>,
+  ServerInit<RefName, Light, Insight, Args, Filter>,
+  Light extends { id: string } ? Light : { id: string },
+  Insight
+>;
 

package/fetch/fetchType/endpointFetch.type.ts

@@ -7,6 +7,7 @@ import type {
   EndpInfoReqType,
   EndpointCls,
   EndpointInfo,
+  PromptMessage,
   SlceCnstFull,
   SlceCnstInsight,
   SlceCnstLight,
@@ -32,15 +33,21 @@ type EndpointClientReturns<E, SlceCls extends SliceCls | never> = [SlceCls] exte
       SlceCnstInsight<SlceCls>
     >;
 
-type EndpInfoReturns<E, SlceCls extends SliceCls | never> =
-  | EndpointClientReturns<E, SlceCls>
-  | (EndpInfoNullable<E> extends true ? null : never);
+type OrNull<T, Nullable> = Nullable extends true ? T | null : T;
+
+type EndpInfoReturns<E, SlceCls extends SliceCls | never> = OrNull<
+  EndpointClientReturns<E, SlceCls>,
+  EndpInfoNullable<E>
+>;
 
 type QueryOrMutationFetchFn<E, SlceCls extends SliceCls | never> = (
   ...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]
 ) => Promise<EndpInfoReturns<E, SlceCls>>;
 
-type MessageEmitFn<E> = (...args: EndpInfoArgs<E>) => void;
+/** Typed off `PromptResult` rather than the endpoint's return ref, which is the `Any` carrier a prompt rides on. */
+type PromptFetchFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => Promise<PromptMessage[]>;
+
+type MessageEmitFn<E> = (...args: [...EndpInfoArgs<E>, fetchPolicy?: FetchPolicy]) => void;
 
 type MessageListenFn<E, SlceCls extends SliceCls | never> = (
   handleEvent: (data: EndpInfoReturns<E, SlceCls>) => PromiseOrObject<void>,
@@ -58,12 +65,14 @@ type PubsubSubscribeFn<E, SlceCls extends SliceCls | never> = (
 type PrimaryFetchFn<E, SlceCls extends SliceCls | never> =
   EndpInfoReqType<E> extends "query" | "mutation"
     ? QueryOrMutationFetchFn<E, SlceCls>
-    : EndpInfoReqType<E> extends "message"
-      ? MessageEmitFn<E>
-      : never;
+    : EndpInfoReqType<E> extends "prompt"
+      ? PromptFetchFn<E>
+      : EndpInfoReqType<E> extends "message"
+        ? MessageEmitFn<E>
+        : never;
 
 type PrimaryFetchType<EInfoObj extends { [key: string]: EndpointInfo }, SlceCls extends SliceCls | never> = {
-  [K in keyof EInfoObj as EndpInfoReqType<EInfoObj[K]> extends "query" | "mutation" | "message"
+  [K in keyof EInfoObj as EndpInfoReqType<EInfoObj[K]> extends "query" | "mutation" | "prompt" | "message"
     ? K
     : never]: PrimaryFetchFn<EInfoObj[K], SlceCls>;
 };

package/fetch/fetchType/sliceFetch.type.ts

@@ -1,10 +1,9 @@
-import type { GetStateObject, SLICE_META } from "akanjs/base";
+import type { SLICE_META } from "akanjs/base";
 import type { FetchPolicy } from "akanjs/common";
 import type { ConstantModel, DefaultOf, ProtoFile, PurifiedModel } from "akanjs/constant";
 import type { DatabaseModel, ExtractSort, FilterInstance } from "akanjs/document";
 import type {
   SlceCnstCapitalizedRefName,
-  SlceCnstDefaultInput,
   SlceCnstFull,
   SlceCnstInput,
   SlceCnstInsight,
@@ -26,11 +25,9 @@ type _Full<S extends SliceCls> = SlceCnstFull<S>;
 type _Light<S extends SliceCls> = SlceCnstLight<S>;
 type _Insight<S extends SliceCls> = SlceCnstInsight<S>;
 type _PurifiedInput<S extends SliceCls> = SlceCnstPurifiedInput<S>;
-type _DefaultInput<S extends SliceCls> = SlceCnstDefaultInput<S>;
 type _Filter<S extends SliceCls> = SlceDbFilter<S>;
 type _Sort<S extends SliceCls> = SlceDbSort<S>;
-type _LightWithId<S extends SliceCls> = _Light<S> extends { id: string } ? _Light<S> : { id: string };
-type _SliceFetchInitOption<S extends SliceCls> = FetchInitOption<_Input<S>, _Filter<S>, _DefaultInput<S>, _Sort<S>>;
+type SliceInitOption<S extends SliceCls> = FetchInitOption<_Input<S>, _Filter<S>>;
 
 type SliceListFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `${_RefName<S>}List${Capitalize<Suffix>}` : never]: (
@@ -50,43 +47,33 @@ type SliceInsightFetch<S extends SliceCls> = {
   ) => Promise<_Insight<S>>;
 };
 
+type SliceInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = InitReturn<
+  _RefName<S>,
+  Suffix & string,
+  _Light<S>,
+  _Insight<S>,
+  SliceInfoArgs<_SliceMap<S>[Suffix]>,
+  _Filter<S>
+>;
+
+type SliceServerInit<S extends SliceCls, Suffix extends keyof _SliceMap<S>> = ServerInit<
+  _RefName<S>,
+  _Light<S>,
+  _Insight<S>,
+  SliceInfoArgs<_SliceMap<S>[Suffix]>,
+  _Filter<S>
+>;
+
 type SliceInitFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `init${_Cap<S>}${Capitalize<Suffix>}` : never]: (
-    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: _SliceFetchInitOption<S>]
-  ) => Promise<
-    InitReturn<
-      _RefName<S>,
-      Suffix & string,
-      _Light<S>,
-      _Insight<S>,
-      SliceInfoArgs<_SliceMap<S>[Suffix]>,
-      _Filter<S>,
-      _Cap<S>,
-      Suffix extends string ? Capitalize<Suffix> : never,
-      _LightWithId<S>,
-      GetStateObject<_LightWithId<S>>,
-      GetStateObject<_Insight<S>>,
-      _Sort<S>
-    >
-  >;
+    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: SliceInitOption<S>]
+  ) => Promise<SliceInit<S, Suffix>>;
 };
 
 type SliceGetInitFetch<S extends SliceCls> = {
   [Suffix in keyof _SliceMap<S> as Suffix extends string ? `get${_Cap<S>}Init${Capitalize<Suffix>}` : never]: (
-    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: _SliceFetchInitOption<S>]
-  ) => Promise<
-    ServerInit<
-      _RefName<S>,
-      _Light<S>,
-      _Insight<S>,
-      SliceInfoArgs<_SliceMap<S>[Suffix]>,
-      _Filter<S>,
-      _Cap<S>,
-      GetStateObject<_LightWithId<S>>,
-      GetStateObject<_Insight<S>>,
-      _Sort<S>
-    >
-  >;
+    ...args: [...SliceInfoArgs<_SliceMap<S>[Suffix]>, option?: SliceInitOption<S>]
+  ) => Promise<SliceServerInit<S, Suffix>>;
 };
 
 export type GetFetchTypeFromSlice<SlceCls extends SliceCls> = SlceCls["srv"]["cnst"] extends ConstantModel
@@ -164,23 +151,13 @@ type AppliedBaseSliceFetchType<
   ) => Promise<Full>;
 };
 
-export interface FetchInitForm<
-  Input,
-  Filter extends FilterInstance,
-  _DefaultInput = DefaultOf<Input>,
-  _Sort = ExtractSort<Filter>,
-> {
+export interface FetchInitForm<Input, Filter extends FilterInstance> {
   page?: number;
   limit?: number;
-  sort?: _Sort;
-  default?: Partial<_DefaultInput>;
+  sort?: ExtractSort<Filter>;
+  default?: Partial<DefaultOf<Input>>;
   invalidate?: boolean;
   insight?: boolean;
 }
 
-type FetchInitOption<
-  Input,
-  Filter extends FilterInstance,
-  _DefaultInput = DefaultOf<Input>,
-  _Sort = ExtractSort<Filter>,
-> = FetchPolicy & FetchInitForm<Input, Filter, _DefaultInput, _Sort>;
+type FetchInitOption<Input, Filter extends FilterInstance> = FetchPolicy & FetchInitForm<Input, Filter>;

package/fetch/index.ts

@@ -1,3 +1,4 @@
+export * from "./agentTurn";
 export * from "./client";
 export * from "./fetchType";
 export * from "./requestStorage";

package/index.ts

@@ -4,14 +4,37 @@ import type { AkanImageConfig } from "akanjs/server";
 export const archs = ["amd64", "arm64"] as const;
 export type Arch = (typeof archs)[number];
 
-export interface DockerConfig {
-  content: string;
+/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+export type DockerRun = string | { [key in Arch]?: string };
+
+/** The pieces Akan assembles a Dockerfile from. */
+export interface DockerImageConfig {
   image: string | { [key in Arch]?: string };
-  preRuns: (string | { [key in Arch]?: string })[];
-  postRuns: (string | { [key in Arch]?: string })[];
+  /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
+  preRuns: DockerRun[];
+  /** Runs after `bun install`, before the app files are copied. */
+  postRuns: DockerRun[];
   command: string[];
 }
 
+/**
+ * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
+ * nothing is merged into it, including the steps a lib contributes through its own `docker`.
+ */
+export type DockerConfig = string | DockerImageConfig;
+
+/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
+export type DockerOption = string | Partial<DockerImageConfig>;
+
+/**
+ * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
+ * command, only the steps its own runtime needs.
+ */
+export interface LibDockerConfig {
+  preRuns: DockerRun[];
+  postRuns: DockerRun[];
+}
+
 export interface AkanRouteDomains {
   main?: string[];
   develop?: string[];
@@ -24,9 +47,48 @@ export interface AkanRouteConfig {
   domains: AkanRouteDomains;
 }
 
+/**
+ * Which web surfaces an app serves, resolved. `ssr` is the RSC/SSR route renderer and everything it needs —
+ * the pages bundle, the client bundles, the RSC worker process. `csr` is the single-file SPA shell that the
+ * Capacitor mobile build ships and that `/__csr` serves.
+ */
+export interface AkanWebConfig {
+  ssr: boolean;
+  csr: boolean;
+}
+
+/**
+ * What an `akan.config.ts` may write. `false` is an API-only app — no web artifact is built and no web route
+ * is mounted; `true` (the default) is both surfaces. The object form keeps SSR and toggles only the CSR
+ * bundle, which is the whole range there is: the CSR bundle inlines the stylesheet the SSR build compiles, so
+ * CSR without SSR would ship an unstyled app and is not expressible here.
+ */
+export type AkanWebOption = boolean | { csr: boolean };
+
+/**
+ * How `akan build` trims the `public/` tree it copies into `dist`. Source trees are never touched: an app's
+ * and a lib's `public/` keep every file, and only the build's own copy is trimmed.
+ */
+export interface AkanAssetsConfig {
+  /**
+   * Drop font files from the build's `public/` that no built surface references. A font with `optimize` on is
+   * served from `/_akan/fonts` after subsetting, so its source is a build input the image never reads.
+   */
+  pruneFonts: boolean;
+  /**
+   * Font files to keep whatever the scan concludes, as globs relative to this app's or lib's own `public/`
+   * (`"fonts/Assistant-*.woff2"`). For the case a scan cannot see: a URL assembled at runtime. Declare it in
+   * the `akan.config.ts` that owns the font, so the reason travels with the lib rather than with the app.
+   */
+  keepFonts: string[];
+}
+
+/** A lib picks only which of its own fonts must survive; whether to prune at all belongs to the app. */
+export type LibAssetsConfig = Pick<AkanAssetsConfig, "keepFonts">;
+
 export type DatabaseMode = "single" | "multiple" | "cluster";
 export type MobileEnv = "local" | "debug" | "develop" | "main";
-export type MobilePermission = "camera" | "contacts" | "location" | "push";
+export type MobilePermission = "camera" | "contacts" | "location" | "push" | "speech";
 
 export interface AkanMobileTargetAssets {
   icon?: string;
@@ -162,6 +224,8 @@ export interface AkanPlugin {
 export interface AppConfigResult {
   docker: DockerConfig;
   defaultDatabaseMode: DatabaseMode;
+  /** Web surfaces built into the app and mounted at boot. Both default to `true`. */
+  web: AkanWebConfig;
   routes?: AkanRouteConfig[];
   /**
    * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
@@ -177,10 +241,16 @@ export interface AppConfigResult {
   publicEnv: string[];
   mobile: AkanMobileConfig;
   secrets: string[];
+  /** How the build trims the `public/` copy it ships. */
+  assets: AkanAssetsConfig;
 }
 
 export interface LibConfigResult {
   externalLibs: string[];
+  /** Image steps every app that mounts this lib inherits, unless that app declares a whole Dockerfile. */
+  docker: LibDockerConfig;
+  /** Which of this lib's own public fonts every app that mounts it must keep. */
+  assets: LibAssetsConfig;
 }
 
 export type DeepPartial<T> = {
@@ -197,7 +267,11 @@ export interface LibConfigContext {
   readonly type: "lib";
 }
 
-export type AppConfigInput = DeepPartial<AppConfigResult> & { plugins?: AkanPlugin[] };
+export type AppConfigInput = Omit<DeepPartial<AppConfigResult>, "docker" | "web"> & {
+  docker?: DockerOption;
+  web?: AkanWebOption;
+  plugins?: AkanPlugin[];
+};
 export type LibConfigInput = DeepPartial<LibConfigResult> & { plugins?: AkanPlugin[] };
 export type AppConfig = AppConfigInput | ((app: AppConfigContext) => AppConfigInput);
 export type LibConfig = LibConfigInput | ((lib: LibConfigContext) => LibConfigInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.7",
+  "version": "3.0.0-alpha.71",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -166,6 +166,11 @@
       "import": "./server/rscWorker.tsx",
       "default": "./server/rscWorker.tsx"
     },
+    "./server/akanApp": {
+      "types": "./types/server/akanApp.d.ts",
+      "import": "./server/akanApp.ts",
+      "default": "./server/akanApp.ts"
+    },
     "./server/memoryLimit": {
       "types": "./types/server/memoryLimit.d.ts",
       "import": "./server/memoryLimit.ts",
@@ -175,12 +180,21 @@
       "types": "./types/server/lifecycle/portInUse.d.ts",
       "import": "./server/lifecycle/portInUse.ts",
       "default": "./server/lifecycle/portInUse.ts"
+    },
+    "./server/logging/logQuery": {
+      "types": "./types/server/logging/logQuery.d.ts",
+      "import": "./server/logging/logQuery.ts",
+      "default": "./server/logging/logQuery.ts"
+    },
+    "./server/logging/logTailClient": {
+      "types": "./types/server/logging/logTailClient.d.ts",
+      "import": "./server/logging/logTailClient.ts",
+      "default": "./server/logging/logTailClient.ts"
     }
   },
   "dependencies": {
     "dayjs": "^1.11.20",
     "immer": "^11.1.8",
-    "sharp": "^0.34.5",
     "tailwind-merge": "^3.3.1",
     "tailwind-variants": "^3.3.0"
   },
@@ -202,6 +216,7 @@
     "@capacitor/preferences": "^8.0.1",
     "@capacitor/push-notifications": "^8.1.1",
     "@capgo/capacitor-updater": "^8.46.1",
+    "@happy-dom/global-registrator": "^20.11.2",
     "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
     "@react-spring/web": "^10.1.0",
@@ -210,14 +225,12 @@
     "capacitor-plugin-safe-area": "^5.0.0",
     "chance": "^1.1.13",
     "cordova-plugin-purchase": "^13.16.0",
-    "croner": "^10.0.1",
     "firebase": "^12.13.0",
+    "happy-dom": "^20.11.2",
     "ioredis": "^5.10.1",
-    "mermaid": "^11.15.0",
     "postgres": "^3.4.9",
     "protobufjs": "^8.4.0",
     "react": "19.2.7",
-    "react-datepicker": "^9.1.0",
     "react-dom": "19.2.7",
     "react-icons": "^5.6.0",
     "react-refresh": "^0.18.0",
@@ -225,7 +238,6 @@
     "react-simple-pull-to-refresh": "^1.3.4",
     "react-spring": "^10.0.4",
     "scheduler": "^0.27.0",
-    "sharp": "^0.34.5",
     "tailwind-scrollbar": "^4.0.2",
     "typescript": "^6.0.3"
   },
@@ -281,6 +293,9 @@
     "@capgo/capacitor-updater": {
       "optional": true
     },
+    "@happy-dom/global-registrator": {
+      "optional": true
+    },
     "@libsql/client": {
       "optional": true
     },
@@ -305,16 +320,13 @@
     "cordova-plugin-purchase": {
       "optional": true
     },
-    "croner": {
-      "optional": true
-    },
     "firebase": {
       "optional": true
     },
-    "ioredis": {
+    "happy-dom": {
       "optional": true
     },
-    "mermaid": {
+    "ioredis": {
       "optional": true
     },
     "postgres": {
@@ -326,9 +338,6 @@
     "react": {
       "optional": true
     },
-    "react-datepicker": {
-      "optional": true
-    },
     "react-dom": {
       "optional": true
     },
@@ -358,14 +367,14 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "2.4.4",
-    "@types/bun": "^1.3.14"
+    "@biomejs/biome": "2.5.8",
+    "@types/bun": "^1.4.0"
   },
   "bun": {
     "platform": "bun"
   },
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.4.0"
   },
   "main": "./index.ts"
-}
+}