akanjs 2.4.2-rc.1 → 2.4.2-rc.3

package/common/fileUpload.ts

@@ -10,7 +10,7 @@ interface FileUploadSerializedSignal {
 /** Framework-owned file-upload contract shared by client-safe packages. */
 export const fileUploadContract = {
   fields: { files: "files", metas: "metas", type: "type", parentId: "parentId" },
-  buildMetas: (fileList: FileList) =>
+  buildMetas: (fileList: FileList | File[]) =>
     Array.from(fileList).map((f) => ({ lastModifiedAt: new Date(f.lastModified).toISOString(), size: f.size })),
 } as const;
 

package/common/index.ts

@@ -52,7 +52,7 @@ export {
 } from "./routeConvention";
 export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
-export { getBasePathFromPathname, parseBasePaths } from "./subRoute";
+export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
 export type * from "./types";
 export {
   type WebsocketAuthAckData,

package/common/subRoute.ts

@@ -12,6 +12,67 @@ export const parseBasePaths = (value: string | string[] | Set<string> | undefine
   return [...new Set(items.map((basePath) => basePath.trim()).filter(Boolean))];
 };
 
+const normalizeSubRouteHost = (host: string): string => host.trim().toLowerCase().replace(/:\d+$/, "");
+
+/** A hostname never contains these; a fragment carrying one is a malformed entry, not a host we failed to match. */
+const isSubRouteHost = (host: string): boolean => host.length > 0 && !/[\s/=]/.test(host);
+
+/**
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
+ * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
+ * every pod that received it.
+ */
+export const parseSubRouteHosts = (value: string | undefined | null): Record<string, string[]> => {
+  const hostsByBasePath: Record<string, string[]> = {};
+  for (const group of (value ?? "").split(";")) {
+    const separatorIdx = group.indexOf("=");
+    if (separatorIdx < 0) continue;
+    const basePath = group
+      .slice(0, separatorIdx)
+      .trim()
+      .replace(/^\/+|\/+$/g, "");
+    if (!basePath) continue;
+    const hosts = group
+      .slice(separatorIdx + 1)
+      .split(",")
+      .map(normalizeSubRouteHost)
+      .filter(isSubRouteHost);
+    if (!hosts.length) continue;
+    hostsByBasePath[basePath] = [...new Set([...(hostsByBasePath[basePath] ?? []), ...hosts])];
+  }
+  return hostsByBasePath;
+};
+
+/**
+ * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
+ * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
+ * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ */
+export const resolveSubRouteHosts = ({
+  subRoutes,
+  basePaths,
+  env,
+}: {
+  subRoutes: Record<string, string[]>;
+  basePaths: Iterable<string>;
+  env?: string | null;
+}): { subRoutes: Record<string, string[]>; ignoredBasePaths: string[] } => {
+  const parsed = Object.entries(parseSubRouteHosts(env));
+  if (!parsed.length) return { subRoutes, ignoredBasePaths: [] };
+
+  const configuredBasePaths = new Set(parseBasePaths([...basePaths]));
+  const merged: Record<string, string[]> = { ...subRoutes };
+  const ignoredBasePaths: string[] = [];
+  for (const [basePath, hosts] of parsed) {
+    if (!configuredBasePaths.has(basePath)) {
+      ignoredBasePaths.push(basePath);
+      continue;
+    }
+    merged[basePath] = [...new Set([...(merged[basePath] ?? []).map(normalizeSubRouteHost), ...hosts])];
+  }
+  return { subRoutes: merged, ignoredBasePaths };
+};
+
 export const getBasePathFromPathname = (
   pathname: string,
   {

package/constant/cascadePaths.ts

@@ -0,0 +1,32 @@
+import type { ConstantField, FieldObject } from "./fieldInfo";
+import type { ConstantModelRef } from "./via";
+
+/** What happens to the documents a relation field points at when the owner is removed. */
+export const cascadeActions = ["remove"] as const;
+export type CascadeAction = (typeof cascadeActions)[number];
+
+export class CascadePaths {
+  /** Field key → the model its ids point at. Resolved to a refName later: the target may not be registered yet. */
+  readonly remove = new Map<string, ConstantModelRef>();
+
+  collect(fieldMap: FieldObject) {
+    for (const [key, field] of Object.entries(fieldMap)) {
+      if (!field.cascade) continue;
+      this.#assertCascadable(key, field.cascade, field);
+      this.remove.set(key, field.modelRef);
+    }
+    return this;
+  }
+
+  #assertCascadable(key: string, action: CascadeAction, field: ConstantField) {
+    
+    if (!cascadeActions.includes(action)) {
+      throw new Error(`Cascade field "${key}" declares cascade: "${action}", which is not one of ${cascadeActions}`);
+    }
+    
+    if (!field.isClass || field.isScalar) {
+      throw new Error(`Cascade field "${key}" is not a model reference and has no document to remove`);
+    }
+    if (field.arrDepth > 1) throw new Error(`Cascade field "${key}" is a nested array and cannot cascade`);
+  }
+}

package/constant/fieldInfo.ts

@@ -16,6 +16,7 @@ import {
   type SingleValue,
   type UnCls,
 } from "akanjs/base";
+import type { CascadeAction } from "./cascadePaths";
 import { ConstantRegistry } from "./constantRegistry";
 import type { TextFieldRole } from "./textFieldPaths";
 import type { BaseObject } from "./types";
@@ -104,6 +105,7 @@ export interface ConstantFieldProps<
   of?: MapValue; 
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
+  cascade?: CascadeAction;
   meta?: Metadata;
 }
 export const fieldPresets = ["email", "password", "url"] as const;
@@ -194,6 +196,7 @@ interface ConstantFieldBuildProps<
   of?: MapValue; 
   validate?: (value: FieldValue, model: any) => boolean;
   text?: TextFieldRole;
+  cascade?: CascadeAction;
   modelRef: ConstantModelRef;
   arrDepth: number;
   optArrDepth: number;
@@ -317,6 +320,7 @@ export class ConstantField<
   readonly of?: MapValue; 
   readonly validate?: (value: FieldValue, model: any) => boolean;
   readonly text?: TextFieldRole;
+  readonly cascade?: CascadeAction;
   readonly modelRef: ConstantModelRef;
   readonly arrDepth: number;
   readonly optArrDepth: number;
@@ -348,6 +352,7 @@ export class ConstantField<
     this.of = props.of;
     this.validate = props.validate;
     this.text = props.text;
+    this.cascade = props.cascade;
     this.modelRef = props.modelRef;
     this.arrDepth = props.arrDepth;
     this.optArrDepth = props.optArrDepth;
@@ -426,6 +431,7 @@ export class ConstantField<
       of: option.of,
       validate: option.validate,
       text: option.text,
+      cascade: option.cascade,
       modelRef,
       arrDepth: arrDepth,
       optArrDepth: optArrDepth,
@@ -465,6 +471,7 @@ export class ConstantField<
       of: this.of,
       validate: this.validate,
       text: this.text,
+      cascade: this.cascade,
       modelRef: this.modelRef,
       arrDepth: this.arrDepth,
       optArrDepth: this.optArrDepth,

package/constant/index.ts

@@ -1,3 +1,4 @@
+export * from "./cascadePaths";
 export * from "./constantRegistry";
 export * from "./crystalize";
 export * from "./deserialize";

package/constant/purify.ts

@@ -10,7 +10,6 @@ import {
   ID,
   PrimitiveRegistry,
   type PrimitiveScalar,
-  type Upload,
 } from "akanjs/base";
 import { Logger } from "akanjs/common";
 
@@ -37,15 +36,15 @@ type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof
 } & {
   [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
 };
-export type PurifiedModel<T> = T extends Upload[]
-  ? FileList
-  : T extends (infer S)[]
-    ? PurifiedModel<S>[]
-    : T extends string | number | boolean | Dayjs | File
-      ? T
-      : T extends Map<infer K, infer V>
-        ? Map<K, PurifiedModel<V>>
-        : PurifiedWithObjectToId<T>;
+export type PurifiedModel<T> = T extends (infer S)[]
+  ? PurifiedModel<S>[]
+  : T extends string | number | boolean | Dayjs | File
+    ? T
+    : T extends Map<infer K, infer V>
+      ? Map<K, PurifiedModel<V>>
+      : PurifiedWithObjectToId<T>;
+
+export type UploadableClientArg<T> = [T] extends [File[]] ? File[] | FileList : T;
 
 export type PurifyFunc<Input, _DefaultInput = DefaultOf<Input>, _PurifiedInput = PurifiedModel<Input>> = (
   self: _DefaultInput,

package/constant/via.ts

@@ -13,6 +13,7 @@ import { applyMixins } from "akanjs/common";
 import { immerable } from "immer";
 
 import { crystalize, getDefault } from ".";
+import { CascadePaths } from "./cascadePaths";
 import { ConstantRegistry } from "./constantRegistry";
 import {
   ConstantField,
@@ -193,6 +194,7 @@ const getBaseConstantClass = (field: FieldObject, modelType: ConstantType = "sca
     static readonly [FIELD_META]: FieldObject = field;
     static modelType: ConstantType = modelType;
     static text: TextFieldPaths = new TextFieldPaths();
+    static cascade: CascadePaths = new CascadePaths();
     static children: Set<ConstantModelRef> = new Set();
     static relations: Set<ConstantModelRef> = new Set();
     static enums: Set<EnumInstance> = new Set();
@@ -269,6 +271,7 @@ export interface ConstantStatics<
   relations: Set<ConstantModelRef>;
   enums: Set<EnumInstance>;
   text: TextFieldPaths;
+  cascade: CascadePaths;
   _OptionalKey: OptionalKey;
   _RelationKey: RelationKey;
   _PrimitiveKey: PrimitiveKey;
@@ -296,6 +299,7 @@ export interface DatabaseConstantStatics<Schema = any, FieldObj extends FieldObj
   relations: Set<ConstantModelRef>;
   enums: Set<EnumInstance>;
   text: TextFieldPaths;
+  cascade: CascadePaths;
   _DatabaseSchema: {
     [K in keyof Schema]: K extends keyof FieldObj
       ? FieldObj[K]["fieldType"] extends "hidden"
@@ -318,6 +322,7 @@ export type ConstantModelRef<
     relations: Set<ConstantModelRef>;
     enums: Set<EnumInstance>;
     text: TextFieldPaths;
+    cascade: CascadePaths;
   }
 >;
 
@@ -440,6 +445,7 @@ const applyConstantStatics = <Model>(model: ConstantCls<Model>, fieldMap: FieldO
     for (const relation of field.modelRef.relations) model.relations.add(relation);
   });
   model.text.collect(fieldMap);
+  model.cascade.collect(fieldMap);
   return model as unknown as ConstantCls<Model>;
 };
 

package/fetch/client/fetchClient.ts

@@ -491,7 +491,7 @@ export class FetchClient {
     this.#setHandlerFactory(
       names.addModelFiles,
       () =>
-        (async (fileList: FileList, parentId?: string, option?: FetchPolicy) => {
+        (async (fileList: FileList | File[], parentId?: string, option?: FetchPolicy) => {
           const cap = resolveFileUploadCapability(this.serializedSignal);
           const endpoint = cap ? this.serializedSignal[cap.refName]?.endpoint[cap.endpointKey] : undefined;
           if (!cap || !endpoint)

package/fetch/client/httpClient.ts

@@ -125,6 +125,12 @@ export class HttpClient {
     });
     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();
@@ -133,11 +139,9 @@ export class HttpClient {
         if (arg.nullable && (argValue === null || argValue === undefined)) return;
         if (!arg.nullable && (argValue === null || argValue === undefined))
           throw new Error(`Argument ${arg.name} is required`);
-        if (Array.isArray(argValue)) {
-          argValue.forEach((value) => {
-            formData.append(arg.name, value as Blob | string);
-          });
-        } else formData.append(arg.name, argValue as Blob | string);
+        HttpClient.#toUploadValues(argValue).forEach((value) => {
+          formData.append(arg.name, value);
+        });
       });
       bodyArgs.forEach((arg) => {
         const argValue = argMap.get(arg.name);

package/fetch/fetchType/sliceFetch.type.ts

@@ -152,7 +152,7 @@ type AppliedBaseSliceFetchType<
   [K in `get${_CapitalizedRefName}Edit`]: (id: string, option?: FetchPolicy) => Promise<ServerEdit<RefName, Full>>;
 } & {
   [K in `add${_CapitalizedRefName}Files`]: (
-    fileList: FileList,
+    fileList: FileList | File[],
     parentId?: string,
     option?: FetchPolicy,
   ) => Promise<ProtoFile[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.4.2-rc.1",
+  "version": "2.4.2-rc.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -457,7 +457,13 @@ export class DiLifecycle {
             if (serviceCls.type === "database") {
               const databaseModule = this.#database.get(serviceCls.refName);
               if (!databaseModule) throw new Error(`Database "${serviceCls.refName}" is not registered`);
-              ServiceResolver.resolveDatabaseService(databaseModule.constant, databaseModule.database, serviceCls);
+              ServiceResolver.resolveDatabaseService(
+                databaseModule.constant,
+                databaseModule.database,
+                serviceCls,
+
+                (refName) => this.getService(refName),
+              );
             }
             const service = new serviceCls();
             await InjectInfo.resolveInjection(service, serviceCls, this.registry, this.#env);

package/server/proxy/hostBasePathWebProxy.ts

@@ -1,12 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { getEnv } from "akanjs/base";
+import { Logger, resolveSubRouteHosts } from "akanjs/common";
 import type { BaseBuildArtifact } from "../types";
 import { AkanResponse } from "./akanResponse";
 import type { WebProxy } from "./types";
 
 export class HostBasePathWebProxy implements WebProxy {
   static readonly refName = "HostBasePathWebProxy";
+  #logger = new Logger("HostBasePathWebProxy");
   #domainMap: Map<string, string> | null = null;
 
   use(request: Bun.BunRequest) {
@@ -49,7 +51,16 @@ export class HostBasePathWebProxy implements WebProxy {
 
   #getDomainMap(): Map<string, string> {
     if (this.#domainMap) return this.#domainMap;
-    const subRoutes = loadWebRouteMetadata();
+    const metadata = loadWebRouteMetadata();
+    const { subRoutes, ignoredBasePaths } = resolveSubRouteHosts({
+      subRoutes: metadata.subRoutes,
+      basePaths: metadata.basePaths,
+      env: process.env.AKAN_SUB_ROUTE_HOSTS,
+    });
+    if (ignoredBasePaths.length)
+      this.#logger.warn(
+        `AKAN_SUB_ROUTE_HOSTS names basePaths this build does not serve, ignoring: ${ignoredBasePaths.join(", ")}`,
+      );
     const map = new Map<string, string>();
     for (const [basePath, domains] of Object.entries(subRoutes)) {
       for (const domain of domains) map.set(normalizeHost(domain), basePath);
@@ -59,14 +70,14 @@ export class HostBasePathWebProxy implements WebProxy {
   }
 }
 
-function loadWebRouteMetadata() {
+function loadWebRouteMetadata(): Pick<BaseBuildArtifact, "subRoutes" | "basePaths"> {
   const artifactPath = path.join(resolveArtifactDir(), "base-artifact.json");
-  if (!fs.existsSync(artifactPath)) return { routes: [] };
+  if (!fs.existsSync(artifactPath)) return { subRoutes: {}, basePaths: [] };
   try {
     const parsed = JSON.parse(fs.readFileSync(artifactPath, "utf8")) as Partial<BaseBuildArtifact>;
-    return parsed.subRoutes ?? {};
+    return { subRoutes: parsed.subRoutes ?? {}, basePaths: parsed.basePaths ?? [] };
   } catch {
-    return { routes: [] };
+    return { subRoutes: {}, basePaths: [] };
   }
 }
 

package/server/resolver/service.resolver.ts

@@ -1,6 +1,6 @@
 import type { PromiseOrObject } from "akanjs/base";
 import { capitalize } from "akanjs/common";
-import type { ConstantModel, QueryOf } from "akanjs/constant";
+import { type ConstantModel, ConstantRegistry, type QueryOf } from "akanjs/constant";
 import {
   type CRUDEventType,
   type DatabaseModel,
@@ -17,7 +17,11 @@ import {
 import type { DatabaseService, ServiceCls } from "akanjs/service";
 
 export class ServiceResolver {
-  static #getDefaultDbServiceMethods(className: string) {
+  static #getDefaultDbServiceMethods(
+    className: string,
+    cascades: [string, string][],
+    getService: (refName: string) => DatabaseService,
+  ) {
     const dbServiceMethods = {
       async __get(this: DatabaseService, id: string) {
         return await this.__databaseModel.__get(id);
@@ -95,9 +99,18 @@ export class ServiceResolver {
         return this.__update(id, data);
       },
       async __remove(this: DatabaseService, id: string): Promise<Doc> {
+
+        const targets = cascades.map(([key, refName]) => [key, getService(refName)] as const);
         await this.__libsPreRemove(id);
         const doc = await this.__databaseModel.__remove(id);
-        return await this.__libsPostRemove(doc);
+        const removed = await this.__libsPostRemove(doc);
+        for (const [key, target] of targets) {
+          const value = (removed as Record<string, unknown>)[key];
+          const ids = (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === "string");
+
+          for (const targetId of ids) await target.__remove(targetId);
+        }
+        return removed;
       },
       async [`remove${className}`](this: DatabaseService, id: string): Promise<Doc> {
         return this.__remove(id);
@@ -105,9 +118,18 @@ export class ServiceResolver {
     };
     return dbServiceMethods;
   }
-  static resolveDatabaseService(constant: ConstantModel, database: DatabaseModel, srvRef: ServiceCls): ServiceCls {
+  static resolveDatabaseService(
+    constant: ConstantModel,
+    database: DatabaseModel,
+    srvRef: ServiceCls,
+    getService: (refName: string) => DatabaseService,
+  ): ServiceCls {
     const className = capitalize(database.refName);
-    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(className));
+
+    const cascades = [...constant.full.cascade.remove].map(
+      ([key, modelRef]) => [key, ConstantRegistry.getRefName(modelRef)] as [string, string],
+    );
+    Object.assign(srvRef.prototype, ServiceResolver.#getDefaultDbServiceMethods(className, cascades, getService));
     const getQueryDataFromKey = (queryKey: string, args: any): { query: any; queryOption: any } => {
       const lastArg = args.at(-1);
       const hasQueryOption =

package/server/webRouter.ts

@@ -7,6 +7,7 @@ import {
   getBasePathFromPathname,
   Logger,
   parseAkanI18nEnv,
+  resolveSubRouteHosts,
 } from "akanjs/common";
 import { type AkanRequestStore, createRequestStore, parseCookieHeader } from "akanjs/fetch";
 import type { AkanMetricsReport } from "akanjs/service";
@@ -267,6 +268,7 @@ export class WebRouter {
   #logger = new Logger("WebRouter");
   #artifactDir = WebRouter.#resolveArtifactDir();
   #artifact: BaseBuildArtifact;
+  #subRoutes: Record<string, string[]>;
   #rsc: RscWorker;
   #hub: HmrWsHub | null = null;
   #prodMode = process.env.NODE_ENV === "production";
@@ -293,6 +295,16 @@ export class WebRouter {
   constructor({ artifact, cssBytesByUrl, rsc, seedIndex, upgradeHmrWs }: WebRouterOptions) {
     this.#logger.verbose(`[SSR] loaded ${Object.keys(cssBytesByUrl).length} CSS assets`);
     this.#artifact = artifact;
+    const { subRoutes, ignoredBasePaths } = resolveSubRouteHosts({
+      subRoutes: artifact.subRoutes,
+      basePaths: artifact.basePaths,
+      env: process.env.AKAN_SUB_ROUTE_HOSTS,
+    });
+    this.#subRoutes = subRoutes;
+    if (ignoredBasePaths.length)
+      this.#logger.warn(
+        `AKAN_SUB_ROUTE_HOSTS names basePaths this build does not serve, ignoring: ${ignoredBasePaths.join(", ")}`,
+      );
     this.#rsc = rsc;
     this.renderState = {
       buildId: 0,
@@ -424,8 +436,7 @@ export class WebRouter {
           const clientOrigin = WebRouter.#clientFacingOrigin(req);
           const target = reqUrl.searchParams.get("url");
           const rawTargetUrl = target ? new URL(target, clientOrigin) : reqUrl;
-          const requestBasePath =
-            req.headers.get("x-base-path") ?? WebRouter.#basePathForRequestHost(req, this.#artifact.subRoutes);
+          const requestBasePath = this.#requestBasePath(req);
           const normalizedTarget = normalizeRscTargetUrlForHostBasePath(rawTargetUrl, {
             basePath: requestBasePath,
             basePaths: this.#artifact.basePaths,
@@ -517,11 +528,7 @@ export class WebRouter {
           });
         }
 
-        const sitemapBasePath = getSitemapBasePath(
-          url.pathname,
-          this.#artifact.basePaths,
-          req.headers.get("x-base-path") ?? WebRouter.#basePathForRequestHost(req, this.#artifact.subRoutes),
-        );
+        const sitemapBasePath = getSitemapBasePath(url.pathname, this.#artifact.basePaths, this.#requestBasePath(req));
         if (sitemapBasePath !== undefined) {
           return new Response(
             createDefaultSitemapXml({
@@ -713,6 +720,17 @@ export class WebRouter {
     return getClientFacingOrigin(req);
   }
 
+  /**
+   * `x-base-path` is set by `HostBasePathWebProxy`, but it reaches here from the wire too, so it is checked against
+   * the basePaths this build serves — the same check `getBasePathFromPathname` already applies to it. An unknown
+   * value falls through to host matching instead of routing the request into a basePath that resolves to nothing.
+   */
+  #requestBasePath(req: Request): string | null {
+    const headerBasePath = req.headers.get("x-base-path");
+    if (headerBasePath && this.#artifact.basePaths.includes(headerBasePath)) return headerBasePath;
+    return WebRouter.#basePathForRequestHost(req, this.#subRoutes);
+  }
+
   static #basePathForRequestHost(req: Request, subRoutes: Record<string, string[]>): string | null {
     const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "")
       .toLowerCase()
@@ -857,8 +875,7 @@ export class WebRouter {
       pathname,
       i18n: this.#artifact.i18n,
       basePaths: this.#artifact.basePaths,
-      headerBasePath:
-        req.headers.get("x-base-path") ?? WebRouter.#basePathForRequestHost(req, this.#artifact.subRoutes),
+      headerBasePath: this.#requestBasePath(req),
     });
   }
 
@@ -866,8 +883,7 @@ export class WebRouter {
     const basePath = getBasePathFromPathname(pathname, {
       basePaths: Object.keys(this.renderState.cssAssets),
       i18n: this.#artifact.i18n,
-      headerBasePath:
-        req.headers.get("x-base-path") ?? WebRouter.#basePathForRequestHost(req, this.#artifact.subRoutes),
+      headerBasePath: this.#requestBasePath(req),
     });
     return this.renderState.cssAssets[basePath ?? ""]?.cssUrl ?? null;
   }

package/signal/endpointInfo.ts

@@ -15,6 +15,7 @@ import type {
   ParamFieldType,
   PlainTypeToFieldType,
   PurifiedModel,
+  UploadableClientArg,
 } from "akanjs/constant";
 import type { ServiceModel } from "akanjs/service";
 import type { InternalArgCls } from "./internalArg";
@@ -135,7 +136,7 @@ export class EndpointInfo<
     Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
     Optional extends boolean = false,
     _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType,
-    _ClientArg = PurifiedModel<_ArgType>,
+    _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>) {
     if (this.execFn) throw new Error("Query function is already set");

package/signal/slice.ts

@@ -112,7 +112,7 @@ export function slice<
             _Filter,
             SrvMap<SrvModule>,
             ["query"],
-            [_Query],
+            [query?: _Query | null],
             [],
             [_Query]
           >;

package/signal/sliceInfo.ts

@@ -9,6 +9,7 @@ import type {
   PlainTypeToFieldType,
   PurifiedModel,
   QueryOf,
+  UploadableClientArg,
 } from "akanjs/constant";
 import type { FilterCls, FilterInstance } from "akanjs/document";
 import type { ServiceModel } from "akanjs/service";
@@ -94,7 +95,7 @@ export class SliceInfo<
     Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>,
     Optional extends boolean = false,
     _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType,
-    _ClientArg = PurifiedModel<_ArgType>,
+    _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>) {
     if (this.execFn) throw new Error("Query function is already set");

package/store/action.ts

@@ -224,7 +224,7 @@ type FormSetter<
       ? K extends string
         ? SetterKey<"upload", K, RefName, _CapitalizedRefName>
         : never
-      : never]: (fileList: FileList, idx?: number) => Promise<void>;
+      : never]: (fileList: FileList | File[], idx?: number) => Promise<void>;
   } & {
     [K in `writeOn${_CapitalizedRefName}`]: (path: string | (string | number)[], value: any) => void;
   };
@@ -376,7 +376,11 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
         : {}),
       ...(field.isClass && !!fileUploadRefName && ConstantRegistry.getRefName(field.modelRef) === fileUploadRefName
         ? {
-            [namesOfField.uploadFieldOnModel]: async function (this: SetGet, fileList: FileList, index?: number) {
+            [namesOfField.uploadFieldOnModel]: async function (
+              this: SetGet,
+              fileList: FileList | File[],
+              index?: number,
+            ) {
               const form = (this.get() as { [key: string]: any })[names.modelForm] as { [key: string]: any };
               if (!fileList.length) return;
               const files = await (fetch[names.addModelFiles] as (...args: any) => Promise<ProtoFile[]>)(
@@ -476,6 +480,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     initModel: `init${className}`,
     modelInitList: `${fieldName}InitList`,
     modelInitAt: `${fieldName}InitAt`,
+    modelStaleAt: `${fieldName}StaleAt`,
     refreshModel: `refresh${className}`,
     selectModel: `select${className}`,
     setPageOfModel: `setPageOf${className}`,
@@ -489,6 +494,14 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     queryArgsOfModel: `queryArgsOf${className}`,
     sortOfModel: `sortOf${className}`,
   };
+  const staleAtOfOtherSlices = (createdSliceName: string) => {
+    const staleAt = new Date();
+    return Object.fromEntries(
+      slices
+        .filter(({ sliceName }) => sliceName !== createdSliceName)
+        .map(({ sliceName }) => [sliceName.replace(names.model, names.modelStaleAt), staleAt]),
+    );
+  };
   const baseAction = {
     [names.createModelInForm]: async function (
       this: SetGet,
@@ -527,6 +540,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         [namesOfSlice.modelInsight]: newModelInsight,
         [names.modelViewAt]: new Date(),
         [names.modelModal]: modal ?? null,
+        ...staleAtOfOtherSlices(sliceName),
         ...(typeof path === "string" && path ? { [path]: model } : {}),
       });
       await onSuccess?.(model);
@@ -609,6 +623,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         [namesOfSlice.modelInsight]: newModelInsight,
         [names.modelViewAt]: new Date(),
         [names.modelModal]: modal ?? null,
+        ...staleAtOfOtherSlices(sliceName),
         ...(typeof path === "string" && path ? { [path]: model } : {}),
       });
       await onSuccess?.(model);
@@ -845,6 +860,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       initModel: SliceName.replace(names.Model, names.initModel),
       modelInitList: SliceName.replace(names.Model, names.modelInitList),
       modelInitAt: SliceName.replace(names.Model, names.modelInitAt),
+      modelStaleAt: SliceName.replace(names.Model, names.modelStaleAt),
       refreshModel: SliceName.replace(names.Model, names.refreshModel),
       selectModel: SliceName.replace(names.Model, names.selectModel),
       setPageOfModel: SliceName.replace(names.Model, names.setPageOfModel),

package/store/state.ts

@@ -23,6 +23,7 @@ export type SliceStateKey =
   | "modelListLoading"
   | "modelInitList"
   | "modelInitAt"
+  | "modelStaleAt"
   | "modelSelection"
   | "lastPageOfModel"
   | "pageOfModel"
@@ -78,6 +79,8 @@ export type SliceState<
   [K in `${RefName}InitList${_CapitalizedSuffix}`]: DataList<Light>;
 } & {
   [K in `${RefName}InitAt${_CapitalizedSuffix}`]: Date;
+} & {
+  [K in `${RefName}StaleAt${_CapitalizedSuffix}`]: Date;
 } & {
   [K in `${RefName}Selection${_CapitalizedSuffix}`]: DataList<Light>;
 } & {
@@ -112,7 +115,9 @@ type DefaultSliceStateFields<
     | `${_RefName}InitList${StoreSliceSuffixCap<SlceCls, Suffix>}`
     | `${_RefName}Selection${StoreSliceSuffixCap<SlceCls, Suffix>}`]: DataList<_Light>;
 } & {
-  [Suffix in _Suffixes as `${_RefName}InitAt${StoreSliceSuffixCap<SlceCls, Suffix>}`]: Date;
+  [Suffix in _Suffixes as
+    | `${_RefName}InitAt${StoreSliceSuffixCap<SlceCls, Suffix>}`
+    | `${_RefName}StaleAt${StoreSliceSuffixCap<SlceCls, Suffix>}`]: Date;
 } & {
   [Suffix in _Suffixes as `${_RefName}ListLoading${StoreSliceSuffixCap<SlceCls, Suffix>}`]: boolean;
 } & {
@@ -182,6 +187,7 @@ export const createSliceState = (refName: string, slice: { [key: string]: Serial
     modelListLoading: `${fieldName}ListLoading`,
     modelInitList: `${fieldName}InitList`,
     modelInitAt: `${fieldName}InitAt`,
+    modelStaleAt: `${fieldName}StaleAt`,
     modelSelection: `${fieldName}Selection`,
     modelInsight: `${fieldName}Insight`,
     lastPageOfModel: `lastPageOf${className}`,
@@ -200,6 +206,7 @@ export const createSliceState = (refName: string, slice: { [key: string]: Serial
       modelListLoading: sliceName.replace(names.model, names.modelListLoading),
       modelInitList: sliceName.replace(names.model, names.modelInitList),
       modelInitAt: sliceName.replace(names.model, names.modelInitAt),
+      modelStaleAt: sliceName.replace(names.model, names.modelStaleAt),
       modelSelection: sliceName.replace(names.model, names.modelSelection),
       modelInsight: sliceName.replace(names.model, names.modelInsight),
       lastPageOfModel: SliceName.replace(names.Model, names.lastPageOfModel),
@@ -214,6 +221,7 @@ export const createSliceState = (refName: string, slice: { [key: string]: Serial
       [namesOfSlice.modelListLoading]: true,
       [namesOfSlice.modelInitList]: new DataList(),
       [namesOfSlice.modelInitAt]: new Date(0),
+      [namesOfSlice.modelStaleAt]: new Date(0),
       [namesOfSlice.modelSelection]: new DataList(),
       [namesOfSlice.modelInsight]: new cnst.insight(),
       [namesOfSlice.lastPageOfModel]: 1,

package/store/storeInstance.ts

@@ -263,6 +263,7 @@ export class StoreInstance {
       modelListLoading: `${fieldName}ListLoading`,
       modelInitList: `${fieldName}InitList`,
       modelInitAt: `${fieldName}InitAt`,
+      modelStaleAt: `${fieldName}StaleAt`,
       pageOfModel: `pageOf${className}`,
       limitOfModel: `limitOf${className}`,
       queryArgsOfModel: `queryArgsOf${className}`,
@@ -286,6 +287,7 @@ export class StoreInstance {
       modelList: sliceName.replace(names.model, names.modelList),
       modelListLoading: sliceName.replace(names.model, names.modelListLoading),
       modelInitAt: SliceName.replace(names.Model, names.modelInitAt),
+      modelStaleAt: SliceName.replace(names.Model, names.modelStaleAt),
       lastPageOfModel: SliceName.replace(names.Model, names.lastPageOfModel),
       pageOfModel: SliceName.replace(names.Model, names.pageOfModel),
       limitOfModel: SliceName.replace(names.Model, names.limitOfModel),

package/test/sampleOf.ts

@@ -10,7 +10,7 @@ import {
   Upload,
 } from "akanjs/base";
 import { randomPick } from "akanjs/common";
-import type { BaseObject, ConstantCls, ConstantField, DocumentModel, FieldPreset } from "akanjs/constant";
+import type { BaseObject, ConstantCls, ConstantField, DocumentModel, FieldObject, FieldPreset } from "akanjs/constant";
 
 import { sample } from "./sample";
 
@@ -57,8 +57,8 @@ const makeSample = (field: ConstantField): any => {
 export type SampleOf<Model> = DocumentModel<{
   [K in keyof Model as Model[K] extends BaseObject ? never : K]: NonNullable<Model[K]>;
 }>;
-export const sampleOf = <Model>(
-  modelRef: ConstantCls<Model>,
+export const sampleOf = <Model, FieldObj extends FieldObject>(
+  modelRef: ConstantCls<Model, FieldObj>,
 ): DocumentModel<{ [K in keyof Model as Model[K] extends BaseObject ? never : K]: NonNullable<Model[K]> }> => {
   
   return Object.fromEntries(

package/types/common/fileUpload.d.ts

@@ -13,7 +13,7 @@ export declare const fileUploadContract: {
         readonly type: "type";
         readonly parentId: "parentId";
     };
-    readonly buildMetas: (fileList: FileList) => {
+    readonly buildMetas: (fileList: FileList | File[]) => {
         lastModifiedAt: string;
         size: number;
     }[];

package/types/common/index.d.ts

@@ -25,6 +25,6 @@ export { randomPicks } from "./randomPicks.d.ts";
 export { assertUniqueRoutePatterns, compareRouteSpecificity, isRouteSourceFile, isSpecialRouteLeaf, matchRoutePattern, normalizeRoutePattern, type ParsedRouteModuleKey, parseRouteModuleKey, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
 export { sleep } from "./sleep.d.ts";
 export { splitVersion } from "./splitVersion.d.ts";
-export { getBasePathFromPathname, parseBasePaths } from "./subRoute.d.ts";
+export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";
 export type * from "./types.d.ts";
 export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";

package/types/common/subRoute.d.ts

@@ -1,5 +1,24 @@
 import type { AkanI18nConfig } from "./localeConfig.d.ts";
 export declare const parseBasePaths: (value: string | string[] | Set<string> | undefined | null) => string[];
+/**
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
+ * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
+ * every pod that received it.
+ */
+export declare const parseSubRouteHosts: (value: string | undefined | null) => Record<string, string[]>;
+/**
+ * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
+ * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
+ * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ */
+export declare const resolveSubRouteHosts: ({ subRoutes, basePaths, env, }: {
+    subRoutes: Record<string, string[]>;
+    basePaths: Iterable<string>;
+    env?: string | null;
+}) => {
+    subRoutes: Record<string, string[]>;
+    ignoredBasePaths: string[];
+};
 export declare const getBasePathFromPathname: (pathname: string, { basePaths, i18n, headerBasePath, }: {
     basePaths: Iterable<string>;
     i18n?: Pick<AkanI18nConfig, "locales" | "defaultLocale">;

package/types/constant/cascadePaths.d.ts

@@ -0,0 +1,11 @@
+import type { FieldObject } from "./fieldInfo.d.ts";
+import type { ConstantModelRef } from "./via.d.ts";
+/** What happens to the documents a relation field points at when the owner is removed. */
+export declare const cascadeActions: readonly ["remove"];
+export type CascadeAction = (typeof cascadeActions)[number];
+export declare class CascadePaths {
+    #private;
+    /** Field key → the model its ids point at. Resolved to a refName later: the target may not be registered yet. */
+    readonly remove: Map<string, ConstantModelRef>;
+    collect(fieldMap: FieldObject): this;
+}

package/types/constant/fieldInfo.d.ts

@@ -1,4 +1,5 @@
 import { type Any, CLIENT_VALUE, type Cls, type Dayjs, type EnumInstance, type Float, Int, type PrimitiveScalar, SERVER_VALUE, type SingleValue, type UnCls } from "akanjs/base";
+import type { CascadeAction } from "./cascadePaths.d.ts";
 import type { TextFieldRole } from "./textFieldPaths.d.ts";
 import type { BaseObject } from "./types.d.ts";
 import type { ConstantModelRef } from "./via.d.ts";
@@ -45,6 +46,7 @@ export interface ConstantFieldProps<FieldType extends ConstantFieldKind = Consta
     of?: MapValue;
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
+    cascade?: CascadeAction;
     meta?: Metadata;
 }
 export declare const fieldPresets: readonly ["email", "password", "url"];
@@ -91,6 +93,7 @@ interface ConstantFieldBuildProps<FieldType extends ConstantFieldKind = any, Fie
     of?: MapValue;
     validate?: (value: FieldValue, model: any) => boolean;
     text?: TextFieldRole;
+    cascade?: CascadeAction;
     modelRef: ConstantModelRef;
     arrDepth: number;
     optArrDepth: number;
@@ -134,6 +137,7 @@ export declare class ConstantField<FieldType extends ConstantFieldKind = Constan
     readonly of?: MapValue;
     readonly validate?: (value: FieldValue, model: any) => boolean;
     readonly text?: TextFieldRole;
+    readonly cascade?: CascadeAction;
     readonly modelRef: ConstantModelRef;
     readonly arrDepth: number;
     readonly optArrDepth: number;

package/types/constant/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./cascadePaths.d.ts";
 export * from "./constantRegistry.d.ts";
 export * from "./crystalize.d.ts";
 export * from "./deserialize.d.ts";

package/types/constant/purify.d.ts

@@ -1,4 +1,4 @@
-import { type Dayjs, type GetStateObject, type Upload } from "akanjs/base";
+import { type Dayjs, type GetStateObject } from "akanjs/base";
 import { type BaseObject, type ConstantModelRef, type DefaultOf, type DefaultOfSchema } from ".";
 type Purified<O> = O extends BaseObject ? string : O extends BaseObject[] ? string[] : O extends Dayjs ? Dayjs : O extends object ? PurifiedModel<O> : O;
 type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof GetStateObject<T>> = {
@@ -6,7 +6,8 @@ type PurifiedWithObjectToId<T, StateKeys extends keyof GetStateObject<T> = keyof
 } & {
     [K in StateKeys as null extends T[K] ? K : never]?: Purified<T[K]> | undefined;
 };
-export type PurifiedModel<T> = T extends Upload[] ? FileList : T extends (infer S)[] ? PurifiedModel<S>[] : T extends string | number | boolean | Dayjs | File ? T : T extends Map<infer K, infer V> ? Map<K, PurifiedModel<V>> : PurifiedWithObjectToId<T>;
+export type PurifiedModel<T> = T extends (infer S)[] ? PurifiedModel<S>[] : T extends string | number | boolean | Dayjs | File ? T : T extends Map<infer K, infer V> ? Map<K, PurifiedModel<V>> : PurifiedWithObjectToId<T>;
+export type UploadableClientArg<T> = [T] extends [File[]] ? File[] | FileList : T;
 export type PurifyFunc<Input, _DefaultInput = DefaultOf<Input>, _PurifiedInput = PurifiedModel<Input>> = (self: _DefaultInput, isChild?: boolean) => _PurifiedInput | null;
 export type PurifyFuncV2<Input, RelationKey extends string = never, _DefaultInput = DefaultOfSchema<Input, RelationKey>, _PurifiedInput = PurifiedModel<Input>> = (self: _DefaultInput, isChild?: boolean) => _PurifiedInput | null;
 export declare const makePurify: <I>(modelRef: ConstantModelRef<I>) => PurifyFunc<I>;

package/types/constant/via.d.ts

@@ -1,4 +1,5 @@
 import { CLIENT_VALUE, type Cls, DEFAULT_VALUE, type EnumInstance, FIELD_META, type ObjectAssign, type ObjectAssignKeyOfObjects, PURIFIED_VALUE, SERVER_VALUE } from "akanjs/base";
+import { CascadePaths } from "./cascadePaths.d.ts";
 import { type ExtractFieldInfoObject, type FieldBuilder, type FieldInfoObject, type FieldInfoObjectToFieldObject, type FieldObject, type FieldResolver } from "./fieldInfo.d.ts";
 import { type PurifiedModel, type PurifyFunc } from "./purify.d.ts";
 import { TextFieldPaths } from "./textFieldPaths.d.ts";
@@ -34,6 +35,7 @@ export interface ConstantStatics<Schema = any, OwnSchema = Schema, OwnFieldObj e
     relations: Set<ConstantModelRef>;
     enums: Set<EnumInstance>;
     text: TextFieldPaths;
+    cascade: CascadePaths;
     _OptionalKey: OptionalKey;
     _RelationKey: RelationKey;
     _PrimitiveKey: PrimitiveKey;
@@ -60,6 +62,7 @@ export interface DatabaseConstantStatics<Schema = any, FieldObj extends FieldObj
     relations: Set<ConstantModelRef>;
     enums: Set<EnumInstance>;
     text: TextFieldPaths;
+    cascade: CascadePaths;
     _DatabaseSchema: {
         [K in keyof Schema]: K extends keyof FieldObj ? FieldObj[K]["fieldType"] extends "hidden" ? NonNullable<Schema[K]> : Schema[K] : Schema[K];
     };
@@ -71,6 +74,7 @@ export type ConstantModelRef<Schema = any, FieldObj extends FieldObject = FieldO
     relations: Set<ConstantModelRef>;
     enums: Set<EnumInstance>;
     text: TextFieldPaths;
+    cascade: CascadePaths;
 }>;
 export type DocumentConstantModelRef<Schema = any, FieldObj extends FieldObject = FieldObject, ModelType extends ConstantType = ConstantType, DatabaseSchema = DatabaseSchemaOf<Schema, never>> = Cls<Schema, {
     [FIELD_META]: FieldObj;

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

@@ -60,7 +60,7 @@ type AppliedBaseSliceFetchType<RefName extends string, Input, Full, _Capitalized
 } & {
     [K in `get${_CapitalizedRefName}Edit`]: (id: string, option?: FetchPolicy) => Promise<ServerEdit<RefName, Full>>;
 } & {
-    [K in `add${_CapitalizedRefName}Files`]: (fileList: FileList, parentId?: string, option?: FetchPolicy) => Promise<ProtoFile[]>;
+    [K in `add${_CapitalizedRefName}Files`]: (fileList: FileList | File[], parentId?: string, option?: FetchPolicy) => Promise<ProtoFile[]>;
 } & {
     [K in `merge${_CapitalizedRefName}`]: (modelOrId: Full | string, data: Partial<_PurifiedInput>, option?: FetchPolicy) => Promise<Full>;
 };

package/types/server/resolver/service.resolver.d.ts

@@ -1,7 +1,7 @@
-import type { ConstantModel } from "akanjs/constant";
+import { type ConstantModel } from "akanjs/constant";
 import { type DatabaseModel } from "akanjs/document";
-import type { ServiceCls } from "akanjs/service";
+import type { DatabaseService, ServiceCls } from "akanjs/service";
 export declare class ServiceResolver {
     #private;
-    static resolveDatabaseService(constant: ConstantModel, database: DatabaseModel, srvRef: ServiceCls): ServiceCls;
+    static resolveDatabaseService(constant: ConstantModel, database: DatabaseModel, srvRef: ServiceCls, getService: (refName: string) => DatabaseService): ServiceCls;
 }

package/types/signal/endpointInfo.d.ts

@@ -1,5 +1,5 @@
 import { type Dayjs, type EnumInstance, type PromiseOrObject } from "akanjs/base";
-import type { ConstantFieldType, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel } from "akanjs/constant";
+import type { ConstantFieldType, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel, UploadableClientArg } from "akanjs/constant";
 import type { ServiceModel } from "akanjs/service";
 import type { InternalArgCls } from "./internalArg.d.ts";
 import type { ArgType, SignalOption, SrvMap } from "./types.d.ts";
@@ -45,7 +45,7 @@ export declare class EndpointInfo<ReqType extends EndpointType = EndpointType, S
     static getReturnInfo<Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, Nullable extends boolean = false>(modelRef: Returns, signalOption?: SignalOption<Returns, Nullable>): ReturnInfo<Returns, Nullable>;
     constructor(type: ReqType, returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>);
     param<ArgName extends string, Arg extends ParamFieldType, _ClientArg = FieldToValue<Arg>, _ServerArg = DocumentModel<_ClientArg>>(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg], Returns, ClientReturns, ServerReturns, Nullable>;
-    body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)], Returns, ClientReturns, ServerReturns, Nullable>;
+    body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)], Returns, ClientReturns, ServerReturns, Nullable>;
     room<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg], Returns, ClientReturns, ServerReturns, Nullable>;
     msg<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: string, arg: Arg, option?: EndpointArgProps<Optional>): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)], Returns, ClientReturns, ServerReturns, Nullable>;
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined], Returns, ClientReturns, ServerReturns, Nullable>;

package/types/signal/slice.d.ts

@@ -51,7 +51,7 @@ export declare function slice<SrvModule extends ServiceModel, BuildSlice extends
     [""]: SliceInfo<SrvRefName<SrvModule>, _Input, _Full, _Light, _Insight, _Filter, SrvMap<SrvModule>, [
         "query"
     ], [
-        _Query
+        query?: _Query | null
     ], [
     ], [
         _Query

package/types/signal/sliceInfo.d.ts

@@ -1,5 +1,5 @@
 import type { Cls, PromiseOrObject } from "akanjs/base";
-import type { BaseInsight, BaseObject, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel, QueryOf } from "akanjs/constant";
+import type { BaseInsight, BaseObject, ConstantFieldTypeInput, DocumentModel, FieldToValue, ParamFieldType, PlainTypeToFieldType, PurifiedModel, QueryOf, UploadableClientArg } from "akanjs/constant";
 import type { FilterCls, FilterInstance } from "akanjs/document";
 import type { ServiceModel } from "akanjs/service";
 import { type ArgInfo, type EndpointArgProps, type InternalArgInfo, type InternalArgProps } from "./endpointInfo.d.ts";
@@ -23,7 +23,7 @@ export declare class SliceInfo<RefName extends string = string, Input = any, Ful
     execFn: ((...args: [...ServerArgs, ...InternalArgs]) => QueryOf<DocumentModel<Full>>) | null;
     constructor(refName: RefName, input: Cls<Input>, full: Cls<Full>, light: Cls<Light>, insight: Cls<Insight>, filter: FilterCls<Filter>, signalOption?: SignalOption);
     param<ArgName extends string, Arg extends ParamFieldType, _ClientArg = FieldToValue<Arg>, _ServerArg = DocumentModel<_ClientArg>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg]>;
-    body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)]>;
+    body<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, Optional extends boolean = false, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], Optional extends true ? [...Args, arg?: _ClientArg | null] : [...Args, arg: _ClientArg], InternalArgs, [...ServerArgs, arg: _ServerArg | (Optional extends true ? undefined : never)]>;
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: ArgName, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined]>;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): SliceInfo<RefName, Input, Full, Light, Insight, Filter, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs>;
     exec(query: (this: {

package/types/store/action.d.ts

@@ -111,7 +111,7 @@ type ArrayFieldAddOrSubSetters<RefName extends string, _CapRef extends string, _
     }) => void;
 };
 type FormSetter<Full, RefName extends string, _CapitalizedRefName extends string = Capitalize<RefName>, _DefaultState = DefaultOf<Full>> = FieldFormSetter<_DefaultState, RefName, _CapitalizedRefName> & ArrayFieldAddSetters<RefName, _CapitalizedRefName, _DefaultState> & ArrayFieldSubSetters<RefName, _CapitalizedRefName, _DefaultState> & ArrayFieldAddOrSubSetters<RefName, _CapitalizedRefName, _DefaultState> & {
-    [K in keyof _DefaultState as _DefaultState[K] extends (ProtoFile | null) | ProtoFile[] ? K extends string ? SetterKey<"upload", K, RefName, _CapitalizedRefName> : never : never]: (fileList: FileList, idx?: number) => Promise<void>;
+    [K in keyof _DefaultState as _DefaultState[K] extends (ProtoFile | null) | ProtoFile[] ? K extends string ? SetterKey<"upload", K, RefName, _CapitalizedRefName> : never : never]: (fileList: FileList | File[], idx?: number) => Promise<void>;
 } & {
     [K in `writeOn${_CapitalizedRefName}`]: (path: string | (string | number)[], value: any) => void;
 };

package/types/store/state.d.ts

@@ -3,7 +3,7 @@ import { type DefaultOf } from "akanjs/constant";
 import type { ExtractSort, FilterInstance } from "akanjs/document";
 import type { SerializedSlice, SlceCnstCapitalizedRefName, SlceCnstDefault, SlceCnstFull, SlceCnstInsight, SlceCnstLight, SlceCnstRefName, SlceDbFilter, SlceDbSort, SliceCls } from "akanjs/signal";
 import type { StoreSliceArgs, StoreSliceMap, StoreSliceSuffixCap, Submit } from "./types.d.ts";
-export type SliceStateKey = "defaultModel" | "modelInsight" | "modelList" | "modelListLoading" | "modelInitList" | "modelInitAt" | "modelSelection" | "lastPageOfModel" | "pageOfModel" | "limitOfModel" | "queryArgsOfModel" | "sortOfModel";
+export type SliceStateKey = "defaultModel" | "modelInsight" | "modelList" | "modelListLoading" | "modelInitList" | "modelInitAt" | "modelStaleAt" | "modelSelection" | "lastPageOfModel" | "pageOfModel" | "limitOfModel" | "queryArgsOfModel" | "sortOfModel";
 type _SliceMap<S extends SliceCls> = StoreSliceMap<S>;
 type _StateRefName<S extends SliceCls> = SlceCnstRefName<S>;
 type _StateCap<S extends SliceCls> = SlceCnstCapitalizedRefName<S>;
@@ -42,6 +42,8 @@ export type SliceState<RefName extends string, Suffix extends string, Full, Ligh
     [K in `${RefName}InitList${_CapitalizedSuffix}`]: DataList<Light>;
 } & {
     [K in `${RefName}InitAt${_CapitalizedSuffix}`]: Date;
+} & {
+    [K in `${RefName}StaleAt${_CapitalizedSuffix}`]: Date;
 } & {
     [K in `${RefName}Selection${_CapitalizedSuffix}`]: DataList<Light>;
 } & {
@@ -64,7 +66,7 @@ type DefaultSliceStateFields<SlceCls extends SliceCls, _RefName extends string,
 } & {
     [Suffix in _Suffixes as `${_RefName}List${StoreSliceSuffixCap<SlceCls, Suffix>}` | `${_RefName}InitList${StoreSliceSuffixCap<SlceCls, Suffix>}` | `${_RefName}Selection${StoreSliceSuffixCap<SlceCls, Suffix>}`]: DataList<_Light>;
 } & {
-    [Suffix in _Suffixes as `${_RefName}InitAt${StoreSliceSuffixCap<SlceCls, Suffix>}`]: Date;
+    [Suffix in _Suffixes as `${_RefName}InitAt${StoreSliceSuffixCap<SlceCls, Suffix>}` | `${_RefName}StaleAt${StoreSliceSuffixCap<SlceCls, Suffix>}`]: Date;
 } & {
     [Suffix in _Suffixes as `${_RefName}ListLoading${StoreSliceSuffixCap<SlceCls, Suffix>}`]: boolean;
 } & {

package/types/test/sampleOf.d.ts

@@ -1,5 +1,5 @@
-import type { BaseObject, ConstantCls, DocumentModel } from "akanjs/constant";
+import type { BaseObject, ConstantCls, DocumentModel, FieldObject } from "akanjs/constant";
 export type SampleOf<Model> = DocumentModel<{
     [K in keyof Model as Model[K] extends BaseObject ? never : K]: NonNullable<Model[K]>;
 }>;
-export declare const sampleOf: <Model>(modelRef: ConstantCls<Model>) => DocumentModel<{ [K in keyof Model as Model[K] extends BaseObject ? never : K]: NonNullable<Model[K]>; }>;
+export declare const sampleOf: <Model, FieldObj extends FieldObject>(modelRef: ConstantCls<Model, FieldObj>) => DocumentModel<{ [K in keyof Model as Model[K] extends BaseObject ? never : K]: NonNullable<Model[K]>; }>;

package/types/ui/Load/Units.d.ts

@@ -18,6 +18,8 @@ interface DefaultProps<L extends {
     renderList?: (list: DataList<L>) => ReactNode;
     reverse?: boolean;
     pagination?: boolean;
+    /** Max age in ms of the cached slice data before the client refetches on mount; `0` always refetches. */
+    staleTime?: number;
 }
 interface UnitsProps<RefName extends string, Light extends {
     id: string;
@@ -26,5 +28,5 @@ interface UnitsProps<RefName extends string, Light extends {
 }
 export default function Units<RefName extends string, Light extends {
     id: string;
-}>({ containerRef, className, init, noDiv, from, to, loading, renderItem, renderList, renderEmpty, filter, sort, reverse, style, pagination, }: UnitsProps<RefName, Light>): import("react/jsx-runtime").JSX.Element;
+}>({ containerRef, className, init, noDiv, from, to, loading, renderItem, renderList, renderEmpty, filter, sort, reverse, style, pagination, staleTime, }: UnitsProps<RefName, Light>): import("react/jsx-runtime").JSX.Element;
 export {};

package/ui/Load/Units.tsx

@@ -28,6 +28,8 @@ interface DefaultProps<L extends { id: string }> {
   renderList?: (list: DataList<L>) => ReactNode;
   reverse?: boolean;
   pagination?: boolean;
+  /** Max age in ms of the cached slice data before the client refetches on mount; `0` always refetches. */
+  staleTime?: number;
 }
 
 interface UnitsProps<RefName extends string, Light extends { id: string }> extends DefaultProps<Light> {
@@ -60,6 +62,7 @@ function Render<RefName extends string, Light extends { id: string }>({
   sort = (a, b) => 1,
   reverse,
   pagination,
+  staleTime,
 }: RenderProps<RefName, Light>) {
   const loaded = useRef(false);
   const storeUse = st.use as { [key: string]: () => unknown };
@@ -75,6 +78,7 @@ function Render<RefName extends string, Light extends { id: string }>({
     modelInsight: `${modelName}Insight`,
     modelInitList: `${modelName}InitList`,
     modelInitAt: `${modelName}InitAt`,
+    modelStaleAt: `${modelName}StaleAt`,
     modelObjList: `${modelName}ObjList`,
     modelObjInsight: `${modelName}ObjInsight`,
     pageOfModel: `pageOf${ModelName}`,
@@ -84,12 +88,14 @@ function Render<RefName extends string, Light extends { id: string }>({
     sortOfModel: `sortOf${ModelName}`,
     setPageOfModel: `setPageOf${ModelName}`,
     addPageOfModel: `addPageOf${ModelName}`,
+    refreshModel: `refresh${ModelName}`,
   };
   const namesOfSlice = {
     modelList: sliceName.replace(names.model, names.modelList),
     modelListLoading: sliceName.replace(names.model, names.modelListLoading),
     modelInitList: sliceName.replace(names.model, names.modelInitList),
     modelInitAt: sliceName.replace(names.model, names.modelInitAt),
+    modelStaleAt: sliceName.replace(names.model, names.modelStaleAt),
     modelInsight: sliceName.replace(names.model, names.modelInsight),
     pageOfModel: sliceName.replace(names.model, names.pageOfModel),
     lastPageOfModel: sliceName.replace(names.model, names.lastPageOfModel),
@@ -98,6 +104,7 @@ function Render<RefName extends string, Light extends { id: string }>({
     sortOfModel: sliceName.replace(names.model, names.sortOfModel),
     setPageOfModel: sliceName.replace(names.model, names.setPageOfModel),
     addPageOfModel: sliceName.replace(names.model, names.addPageOfModel),
+    refreshModel: sliceName.replace(names.model, names.refreshModel),
   };
   const modelList = storeUse[namesOfSlice.modelList]() as DataList<Light>;
   const modelListLoading = storeUse[namesOfSlice.modelListLoading]() as string | boolean;
@@ -106,6 +113,7 @@ function Render<RefName extends string, Light extends { id: string }>({
   const initModelObjInsight = (init as any)[names.modelObjInsight] as BaseInsight;
   const initLimitOfModel = (init as any)[names.limitOfModel] as number;
   const initPageOfModel = (init as any)[names.pageOfModel] as number;
+  const modelStaleAt = storeUse[namesOfSlice.modelStaleAt]() as Date;
 
   const useCache =
     !modelListLoading &&
@@ -143,6 +151,13 @@ function Render<RefName extends string, Light extends { id: string }>({
     loaded.current = true;
   }, []);
 
+  useEffect(() => {
+    const staleThreshold = Math.max(modelStaleAt.getTime(), staleTime === undefined ? 0 : Date.now() - staleTime);
+    if (storeGet<Date>()[namesOfSlice.modelInitAt].getTime() >= staleThreshold) return;
+    if (storeGet<boolean>()[namesOfSlice.modelListLoading]) return;
+    void storeDo[namesOfSlice.refreshModel]({ invalidate: true });
+  }, [modelStaleAt]);
+
   const modelInsight = storeUse[namesOfSlice.modelInsight]() as BaseInsight;
   const limitOfModel = storeUse[namesOfSlice.limitOfModel]() as number;
   const pageOfModel = storeUse[namesOfSlice.pageOfModel]() as number;
@@ -237,6 +252,7 @@ export default function Units<RefName extends string, Light extends { id: string
   reverse,
   style,
   pagination = true,
+  staleTime,
 }: UnitsProps<RefName, Light>) {
   const props: UnitsProps<RefName, Light> = {
     containerRef,
@@ -254,6 +270,7 @@ export default function Units<RefName extends string, Light extends { id: string
     sort,
     reverse,
     pagination,
+    staleTime,
   };
 
   const { fulfilled, value: promiseInit } = useFetch(init);

package/ui/Signal/Arg.tsx

@@ -351,7 +351,7 @@ const ArgUpload = ({ value, onChange }: ArgUploadProps) => {
       multiple
       className="file-input file-input-bordered w-full max-w-xs"
       onChange={(e: ChangeEvent<HTMLInputElement>) => {
-        onChange(new Array(e.target.files?.length).fill(0).map((_, idx) => e.target.files?.[idx]) as any as FileList);
+        onChange(e.target.files);
       }}
     />
   );