akanjs 2.4.2-rc.2 → 2.4.2-rc.4

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/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/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.2",
+  "version": "2.4.2-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -43,6 +43,19 @@ type GatewayUpstream = {
   ws?: Extract<AkanUpstream, { type: "tcp" }>;
 };
 
+/**
+ * Received-only close codes cannot be sent in a close frame. The gateway deliberately normalizes
+ * every unsendable code, including semantically distinct 1005 and 1006 events, to 1001 in both
+ * relay directions. In particular, Bun's global client `WebSocket.close()` throws an
+ * InvalidAccessError for these codes at the client-to-upstream relay; normalization at the
+ * upstream-to-client `Bun.ServerWebSocket.close()` relay is defensive and keeps behavior symmetric.
+ */
+const relayableCloseCode = (code: number): number => {
+  if (code >= 3000 && code <= 4999) return code;
+  if (code >= 1000 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006) return code;
+  return 1001;
+};
+
 /** Options for the Akan gateway that launches child server replicas and listens for traffic. */
 export interface AkanAppOptions {
   replica?: number | string;
@@ -583,7 +596,7 @@ export class AkanApp {
       const result = ws.send(event.data as string | ArrayBuffer);
       if (result === 0) upstream.close();
     });
-    upstream.addEventListener("close", (event) => ws.close(event.code, event.reason));
+    upstream.addEventListener("close", (event) => ws.close(relayableCloseCode(event.code), event.reason));
     upstream.addEventListener("error", () => ws.close(1011, "upstream websocket error"));
     Object.assign(ws.data, { pending });
   }
@@ -604,7 +617,7 @@ export class AkanApp {
   }
 
   #handleWsClose(ws: Bun.ServerWebSocket<GatewayWsData>, code: number, reason: string) {
-    ws.data.upstream.close(code, reason);
+    ws.data.upstream.close(relayableCloseCode(code), reason);
     const child = this.#children.get(ws.data.childIdx);
     if (child) child.metrics.activeWebSockets = Math.max(0, (child.metrics.activeWebSockets ?? 1) - 1);
   }

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/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/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/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);
       }}
     />
   );