akanjs 2.1.0-rc.0 → 2.1.0-rc.10

package/capacitor.base.config.ts

@@ -0,0 +1,88 @@
+import os from "node:os";
+import type { CapacitorConfig } from "@capacitor/cli";
+import type { AkanMobileTargetConfig, AppScanResult } from "akanjs";
+
+const getLocalIP = () => {
+  const interfaces = os.networkInterfaces();
+  for (const interfaceName in interfaces) {
+    const iface = interfaces[interfaceName];
+    if (!iface) continue;
+    for (const alias of iface) {
+      if (alias.family === "IPv4" && !alias.internal) return alias.address;
+    }
+  }
+  return "127.0.0.1"; 
+};
+
+const normalizeBasePath = (basePath: string | undefined) => basePath?.replace(/^\/+|\/+$/g, "");
+
+const routeBasePaths = (appInfo: AppScanResult) =>
+  new Set(
+    appInfo.routes
+      .map((route) => route.replace(/^\.\//, "").split("/")[0])
+      .filter((segment): segment is string => !!segment && !segment.startsWith("_") && !segment.startsWith("(")),
+  );
+
+const resolveTarget = (appInfo: AppScanResult, targetName = process.env.AKAN_MOBILE_TARGET) => {
+  const targets = appInfo.akanConfig.mobile.targets;
+  if (!targets || Object.keys(targets).length === 0) throw new Error("Akan mobile target metadata is missing.");
+  if (targetName) {
+    const target = targets[targetName];
+    if (!target) {
+      const basePath = normalizeBasePath(targetName);
+      const [template] = Object.values(targets);
+      if (basePath && template && routeBasePaths(appInfo).has(basePath))
+        return { ...template, name: basePath, basePath };
+      throw new Error(`Akan mobile target '${targetName}' was not found.`);
+    }
+    return target;
+  }
+  const entries = Object.entries(targets);
+  if (entries.length !== 1) throw new Error("AKAN_MOBILE_TARGET is required when multiple mobile targets exist.");
+  return entries[0]?.[1] as AkanMobileTargetConfig;
+};
+
+const localCsrUrl = (ip: string, target: AkanMobileTargetConfig) => {
+  const basePath = normalizeBasePath(target.basePath);
+  const port = process.env.AKAN_PUBLIC_CLIENT_PORT ?? process.env.PORT ?? "8282";
+  return `http://${ip}:${port}/${basePath ? `${basePath}` : ""}?csr=true`;
+};
+
+export const withBase = (
+  configImp: (config: CapacitorConfig, target: AkanMobileTargetConfig) => CapacitorConfig = (config) => config,
+  appData?: AppScanResult,
+  targetName?: string,
+) => {
+  const ip = getLocalIP();
+  const appInfo = appData;
+  if (!appInfo) throw new Error("withBase requires apps/<app>/akan.app.json metadata.");
+  const target = resolveTarget(appInfo, targetName);
+  const baseConfig: CapacitorConfig = {
+    ...target,
+    appId: target.appId,
+    appName: target.appName,
+    webDir: "dist",
+    server:
+      process.env.APP_OPERATION_MODE !== "release"
+        ? {
+            androidScheme: "http",
+            url: localCsrUrl(ip, target),
+            cleartext: true,
+            allowNavigation: [ip, "localhost"],
+          }
+        : {
+            allowNavigation: ["*"],
+          },
+    plugins: {
+      CapacitorCookies: { enabled: true },
+      ...target.plugins,
+    },
+    android: {
+      ...target.android,
+    },
+    ios: {
+      ...target.ios,
+    },
+  };
+  return configImp(baseConfig, target);
+};

package/client/capacitor.ts

@@ -1,16 +1,145 @@
+export type CapacitorDeviceInfo = {
+  platform: string;
+  isVirtual: boolean;
+  osVersion: string;
+  [key: string]: unknown;
+};
+
+export type CapacitorKeyboardInfo = {
+  keyboardHeight: number;
+};
+
+export type CapacitorPermissionState = "prompt" | "prompt-with-rationale" | "granted" | "denied" | string;
+
+export type CapacitorAppModule = {
+  App: {
+    addListener: (eventName: string, listenerFunc: (...args: unknown[]) => void) => Promise<unknown> | unknown;
+    removeAllListeners: () => Promise<void> | void;
+    getInfo: () => Promise<{ id: string; version: string; build: string; [key: string]: unknown }>;
+  };
+};
+
+export type CapacitorBrowserModule = {
+  Browser: {
+    open: (options: { url: string; presentationStyle?: string }) => Promise<void> | void;
+  };
+};
+
+export type CapacitorCameraModule = {
+  Camera: {
+    checkPermissions: () => Promise<{ camera: CapacitorPermissionState; photos: CapacitorPermissionState }>;
+    requestPermissions: () => Promise<{ camera: CapacitorPermissionState; photos: CapacitorPermissionState }>;
+    getPhoto: (options: Record<string, unknown>) => Promise<{ dataUrl?: string; [key: string]: unknown }>;
+    pickImages: (options: Record<string, unknown>) => Promise<{ photos: unknown[]; [key: string]: unknown }>;
+  };
+  CameraResultType: { DataUrl: string };
+  CameraSource: { Prompt: string; Camera: string; Photos: string };
+};
+
+export type CapacitorContactsModule = {
+  Contacts: {
+    checkPermissions: () => Promise<{ contacts: CapacitorPermissionState }>;
+    requestPermissions: () => Promise<{ contacts: CapacitorPermissionState }>;
+    getContacts: (options: Record<string, unknown>) => Promise<{ contacts: unknown[] }>;
+  };
+};
+
+export type CapacitorCoreModule = {
+  CapacitorCookies: {
+    setCookie: (options: { key: string; value: string; path?: string }) => Promise<void> | void;
+  };
+};
+
+export type CapacitorDeviceModule = {
+  Device: {
+    getInfo: () => Promise<CapacitorDeviceInfo>;
+    getLanguageCode: () => Promise<{ value: string }>;
+  };
+};
+
+export type CapacitorFcmModule = {
+  FCM: {
+    setAutoInit: (options: { enabled: boolean }) => Promise<void> | void;
+    getToken: () => Promise<{ token: string }>;
+  };
+};
+
+export type CapacitorGeolocationModule = {
+  Geolocation: {
+    requestPermissions: () => Promise<{ location: string; coarseLocation: string; [key: string]: string }>;
+    getCurrentPosition: () => Promise<unknown>;
+  };
+};
+
+export type CapacitorHapticsModule = {
+  ImpactStyle: { Light: string; Medium: string; Heavy: string };
+  Haptics: {
+    vibrate: (options: { duration: number }) => Promise<void> | void;
+    impact: (options: { style: string }) => Promise<void> | void;
+    selectionStart: () => Promise<void> | void;
+    selectionChanged: () => Promise<void> | void;
+    selectionEnd: () => Promise<void> | void;
+  };
+};
+
+export type CapacitorKeyboardModule = {
+  Keyboard: {
+    show: () => Promise<void> | void;
+    hide: () => Promise<void> | void;
+    addListener: (eventName: string, listenerFunc: (info: CapacitorKeyboardInfo) => void) => Promise<unknown> | unknown;
+    removeAllListeners: () => Promise<void> | void;
+  };
+};
+
+export type CapacitorPreferencesModule = {
+  Preferences: {
+    get: (options: { key: string }) => Promise<{ value: string | null }>;
+    set: (options: { key: string; value: string }) => Promise<void> | void;
+    remove: (options: { key: string }) => Promise<void> | void;
+  };
+};
+
+export type CapacitorPushNotificationsModule = {
+  PushNotifications: {
+    requestPermissions: () => Promise<{ receive: "granted" | "denied" | string }>;
+    checkPermissions: () => Promise<{ receive: "granted" | "denied" | string }>;
+    register: () => Promise<void> | void;
+  };
+};
+
+export type CapacitorSafeAreaModule = {
+  SafeArea: {
+    getSafeAreaInsets: () => Promise<{ insets: { top: number; bottom: number } }>;
+  };
+};
+
+export type CapacitorUpdaterModule = {
+  CapacitorUpdater: {
+    notifyAppReady: () => Promise<void> | void;
+    getPluginVersion: () => Promise<{ version: string }>;
+    getDeviceId: () => Promise<{ deviceId: string }>;
+    current: () => Promise<{ bundle: { version: string }; native: string }>;
+    getBuiltinVersion: () => Promise<{ version: string }>;
+    download: (options: { url: string; version: string }) => Promise<unknown>;
+    set: (bundle: unknown) => Promise<void> | void;
+  };
+};
+
 type CapacitorModuleMap = {
-  app: typeof import("@capacitor/app");
-  browser: typeof import("@capacitor/browser");
-  camera: typeof import("@capacitor/camera");
-  contacts: typeof import("@capacitor-community/contacts");
-  device: typeof import("@capacitor/device");
-  fcm: typeof import("@capacitor-community/fcm");
-  geolocation: typeof import("@capacitor/geolocation");
-  haptics: typeof import("@capacitor/haptics");
-  keyboard: typeof import("@capacitor/keyboard");
-  pushNotifications: typeof import("@capacitor/push-notifications");
-  safeArea: typeof import("capacitor-plugin-safe-area");
-  updater: typeof import("@capgo/capacitor-updater");
+  app: CapacitorAppModule;
+  browser: CapacitorBrowserModule;
+  camera: CapacitorCameraModule;
+  contacts: CapacitorContactsModule;
+  core: CapacitorCoreModule;
+  device: CapacitorDeviceModule;
+  fcm: CapacitorFcmModule;
+  geolocation: CapacitorGeolocationModule;
+  haptics: CapacitorHapticsModule;
+  keyboard: CapacitorKeyboardModule;
+  preferences: CapacitorPreferencesModule;
+  pushNotifications: CapacitorPushNotificationsModule;
+  safeArea: CapacitorSafeAreaModule;
+  updater: CapacitorUpdaterModule;
 };
 
 type CapacitorImportCache = Partial<{
@@ -40,29 +169,58 @@ const loadCapacitorModule = <K extends keyof CapacitorModuleMap>(
   return loaded;
 };
 
-export const loadCapacitorApp = () => loadCapacitorModule("app", () => import("@capacitor/app"));
+const importNativeModule = <T>(specifier: string) => import(specifier) as Promise<T>;
+
+const capacitorPackage = (name: string) => `@capacitor/${name}`;
 
-export const loadCapacitorBrowser = () => loadCapacitorModule("browser", () => import("@capacitor/browser"));
+const capacitorCommunityPackage = (name: string) => `@capacitor-community/${name}`;
 
-export const loadCapacitorCamera = () => loadCapacitorModule("camera", () => import("@capacitor/camera"));
+export const loadCapacitorApp = () =>
+  loadCapacitorModule("app", () => importNativeModule<CapacitorAppModule>(capacitorPackage("app")));
+
+export const loadCapacitorBrowser = () =>
+  loadCapacitorModule("browser", () => importNativeModule<CapacitorBrowserModule>(capacitorPackage("browser")));
+
+export const loadCapacitorCamera = () =>
+  loadCapacitorModule("camera", () => importNativeModule<CapacitorCameraModule>(capacitorPackage("camera")));
 
 export const loadCapacitorContacts = () =>
-  loadCapacitorModule("contacts", () => import("@capacitor-community/contacts"));
+  loadCapacitorModule("contacts", () =>
+    importNativeModule<CapacitorContactsModule>(capacitorCommunityPackage("contacts")),
+  );
 
-export const loadCapacitorDevice = () => loadCapacitorModule("device", () => import("@capacitor/device"));
+export const loadCapacitorCore = () =>
+  loadCapacitorModule("core", () => importNativeModule<CapacitorCoreModule>(capacitorPackage("core")));
 
-export const loadCapacitorFcm = () => loadCapacitorModule("fcm", () => import("@capacitor-community/fcm"));
+export const loadCapacitorDevice = () =>
+  loadCapacitorModule("device", () => importNativeModule<CapacitorDeviceModule>(capacitorPackage("device")));
+
+export const loadCapacitorFcm = () =>
+  loadCapacitorModule("fcm", () => importNativeModule<CapacitorFcmModule>(capacitorCommunityPackage("fcm")));
 
 export const loadCapacitorGeolocation = () =>
-  loadCapacitorModule("geolocation", () => import("@capacitor/geolocation"));
+  loadCapacitorModule("geolocation", () =>
+    importNativeModule<CapacitorGeolocationModule>(capacitorPackage("geolocation")),
+  );
+
+export const loadCapacitorHaptics = () =>
+  loadCapacitorModule("haptics", () => importNativeModule<CapacitorHapticsModule>(capacitorPackage("haptics")));
 
-export const loadCapacitorHaptics = () => loadCapacitorModule("haptics", () => import("@capacitor/haptics"));
+export const loadCapacitorKeyboard = () =>
+  loadCapacitorModule("keyboard", () => importNativeModule<CapacitorKeyboardModule>(capacitorPackage("keyboard")));
 
-export const loadCapacitorKeyboard = () => loadCapacitorModule("keyboard", () => import("@capacitor/keyboard"));
+export const loadCapacitorPreferences = () =>
+  loadCapacitorModule("preferences", () =>
+    importNativeModule<CapacitorPreferencesModule>(capacitorPackage("preferences")),
+  );
 
 export const loadCapacitorPushNotifications = () =>
-  loadCapacitorModule("pushNotifications", () => import("@capacitor/push-notifications"));
+  loadCapacitorModule("pushNotifications", () =>
+    importNativeModule<CapacitorPushNotificationsModule>(capacitorPackage("push-notifications")),
+  );
 
-export const loadCapacitorSafeArea = () => loadCapacitorModule("safeArea", () => import("capacitor-plugin-safe-area"));
+export const loadCapacitorSafeArea = () =>
+  loadCapacitorModule("safeArea", () => importNativeModule<CapacitorSafeAreaModule>("capacitor-plugin-safe-area"));
 
-export const loadCapacitorUpdater = () => loadCapacitorModule("updater", () => import("@capgo/capacitor-updater"));
+export const loadCapacitorUpdater = () =>
+  loadCapacitorModule("updater", () => importNativeModule<CapacitorUpdaterModule>("@capgo/capacitor-updater"));

package/client/cookie.ts

@@ -2,6 +2,7 @@ import { getEnv } from "akanjs/base";
 import { decodeJwtPayload, Logger } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
 import { requestStorage } from "akanjs/fetch";
+import { loadCapacitorCore } from "./capacitor";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
 
@@ -42,11 +43,18 @@ export const setCookie = (
   value: string,
   options: CookieOptions = { path: "/", sameSite: "none", secure: true },
 ) => {
-  if (getEnv().side === "server") return;
-  else
-    void import("@capacitor/core").then(({ CapacitorCookies }) =>
-      CapacitorCookies.setCookie({ key, value, path: options.path }),
-    );
+  const env = getEnv();
+  if (env.side === "server") return;
+  const encoded = `${key}=${value}`;
+  const path = options.path ? `; path=${options.path}` : "";
+  const sameSite = options.sameSite ? `; SameSite=${options.sameSite}` : "";
+  const secure = options.secure ? "; Secure" : "";
+  
+  document.cookie = `${encoded}${path}${sameSite}${secure}`;
+  if (env.renderMode !== "csr") return;
+  void loadCapacitorCore()
+    .then(({ CapacitorCookies }) => CapacitorCookies.setCookie({ key, value, path: options.path }))
+    .catch(() => undefined);
 };
 
 export const getCookie = (key: string): string | undefined => {
@@ -61,6 +69,7 @@ export const getCookie = (key: string): string | undefined => {
 export const removeCookie = (key: string, options: { path: string } = { path: "/" }) => {
   if (getEnv().side === "server") return cookies().delete(key);
   else {
+    
     document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
   }
 };

package/client/device.ts

@@ -1,19 +1,87 @@
 "use client";
-import type { DeviceInfo } from "@capacitor/device";
-import type { KeyboardInfo } from "@capacitor/keyboard";
 import type { RefObject } from "react";
-import { isMobile } from "react-device-detect";
-import { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } from "./capacitor";
+import type {
+  CapacitorDeviceInfo,
+  CapacitorHapticsModule,
+  CapacitorKeyboardInfo,
+  CapacitorKeyboardModule,
+} from "./capacitor";
+
+type DeviceInfo = CapacitorDeviceInfo;
+type Keyboard = CapacitorKeyboardModule["Keyboard"];
+type Haptics = CapacitorHapticsModule["Haptics"];
+type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
+type ProcessEnvLike = { env?: Record<string, string | undefined> };
+
+const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessEnvLike };
 
 interface DeviceInitOption {
   lang: string;
   info: DeviceInfo;
   topSafeArea: number;
   bottomSafeArea: number;
-  keyboard: Awaited<ReturnType<typeof loadCapacitorKeyboard>>["Keyboard"];
-  haptics: Awaited<ReturnType<typeof loadCapacitorHaptics>>["Haptics"];
-  impactStyle: Awaited<ReturnType<typeof loadCapacitorHaptics>>["ImpactStyle"];
+  keyboard: Keyboard;
+  haptics: Haptics;
+  impactStyle: ImpactStyle;
 }
+
+const noopKeyboard: Keyboard = {
+  show: async () => undefined,
+  hide: async () => undefined,
+  addListener: async () => undefined,
+  removeAllListeners: async () => undefined,
+};
+
+const noopHaptics: Haptics = {
+  vibrate: async () => undefined,
+  impact: async () => undefined,
+  selectionStart: async () => undefined,
+  selectionChanged: async () => undefined,
+  selectionEnd: async () => undefined,
+};
+
+const noopImpactStyle: ImpactStyle = {
+  Light: "light",
+  Medium: "medium",
+  Heavy: "heavy",
+};
+
+const getRenderMode = () => globalWithProcess.process?.env?.AKAN_PUBLIC_RENDER_ENV ?? "csr";
+
+const getBrowserLanguage = () => globalThis.navigator?.language?.split("-")[0] ?? "en";
+
+const isNativeTarget = () => {
+  if (typeof window === "undefined") return false;
+  return Boolean((window as typeof window & { __AKAN_MOBILE_TARGET__?: unknown }).__AKAN_MOBILE_TARGET__);
+};
+
+export const isMobileDevice = () => {
+  if (typeof navigator === "undefined") return false;
+  if (typeof window !== "undefined" && window.matchMedia?.("(hover: none) and (pointer: coarse)")?.matches) return true;
+  return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+};
+
+const createWebDevice = ({
+  lang,
+  supportLanguages,
+}: {
+  lang?: string;
+  supportLanguages: string[] | readonly string[];
+}) => {
+  const pathname = typeof window === "undefined" ? "" : window.location.pathname;
+  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
+  const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
+  return new Device({
+    lang: lang ?? predefinedLang ?? getBrowserLanguage(),
+    info: { platform: "web", isVirtual: false, osVersion: "" },
+    topSafeArea: 0,
+    bottomSafeArea: 0,
+    keyboard: noopKeyboard,
+    haptics: noopHaptics,
+    impactStyle: noopImpactStyle,
+  });
+};
+
 /** Capacitor-aware device helper for platform info, safe areas, keyboard, haptics, and scroll state. */
 export class Device {
   static instance: Device | null = null;
@@ -25,6 +93,14 @@ export class Device {
     supportLanguages?: string[] | readonly string[];
   }) {
     if (Device.instance) return Device.instance;
+    if (getRenderMode() !== "csr" || !isNativeTarget()) {
+      const device = createWebDevice({ lang, supportLanguages });
+      Device.instance = device;
+      return device;
+    }
+    const { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } = await import(
+      "./capacitor"
+    );
     const [{ Device: CapacitorDevice }, { Keyboard }, { Haptics, ImpactStyle }, { SafeArea }] = await Promise.all([
       loadCapacitorDevice(),
       loadCapacitorKeyboard(),
@@ -61,7 +137,7 @@ export class Device {
   lang: string;
   topSafeArea: number;
   bottomSafeArea: number;
-  isMobile = isMobile;
+  isMobile = isMobileDevice();
   #keyboard: DeviceInitOption["keyboard"];
   #haptics: DeviceInitOption["haptics"];
   #impactStyle: DeviceInitOption["impactStyle"];
@@ -89,10 +165,10 @@ export class Device {
   }
   listenKeyboardChanged(onKeyboardChanged: (height: number) => void) {
     if (this.info.platform === "web") return;
-    void this.#keyboard.addListener("keyboardWillShow", (keyboard: KeyboardInfo) => {
+    void this.#keyboard.addListener("keyboardWillShow", (keyboard: CapacitorKeyboardInfo) => {
       onKeyboardChanged(keyboard.keyboardHeight);
     });
-    void this.#keyboard.addListener("keyboardDidShow", (keyboard: KeyboardInfo) => {
+    void this.#keyboard.addListener("keyboardDidShow", (keyboard: CapacitorKeyboardInfo) => {
       onKeyboardChanged(keyboard.keyboardHeight);
     });
     void this.#keyboard.addListener("keyboardWillHide", () => {

package/client/index.ts

@@ -1,4 +1,3 @@
-export * from "./capacitor";
 export * from "./clientRuntime";
 export * from "./cookie";
 export * from "./createFont";

package/client/storage.ts

@@ -1,33 +1,57 @@
 import { getEnv } from "akanjs/base";
+import { loadCapacitorPreferences } from "./capacitor";
+
+const getLocalStorageItem = (key: string) => localStorage.getItem(key);
+
+const setLocalStorageItem = (key: string, value: string) => {
+  localStorage.setItem(key, value);
+};
+
+const removeLocalStorageItem = (key: string) => {
+  localStorage.removeItem(key);
+};
 
 export const storage = {
   getItem: async (key: string) => {
-    if (getEnv().side === "server") return;
-    if (getEnv().renderMode === "ssr") return localStorage.getItem(key);
-    else {
-      const { Preferences } = await import("@capacitor/preferences");
+    const env = getEnv();
+    if (env.side === "server") return;
+    if (env.renderMode === "ssr") return getLocalStorageItem(key);
+    try {
+      const { Preferences } = await loadCapacitorPreferences();
       return (await Preferences.get({ key })).value;
+    } catch {
+      return getLocalStorageItem(key);
     }
   },
   setItem: async (key: string, value: string) => {
-    if (getEnv().side === "server") return;
-    if (getEnv().renderMode === "ssr") {
-      localStorage.setItem(key, value);
+    const env = getEnv();
+    if (env.side === "server") return;
+    if (env.renderMode === "ssr") {
+      setLocalStorageItem(key, value);
       return;
-    } else {
-      const { Preferences } = await import("@capacitor/preferences");
+    }
+    try {
+      const { Preferences } = await loadCapacitorPreferences();
       await Preferences.set({ key, value });
       return;
+    } catch {
+      setLocalStorageItem(key, value);
+      return;
     }
   },
   removeItem: async (key: string) => {
-    if (getEnv().side === "server") return;
-    if (getEnv().renderMode === "ssr") {
-      localStorage.removeItem(key);
+    const env = getEnv();
+    if (env.side === "server") return;
+    if (env.renderMode === "ssr") {
+      removeLocalStorageItem(key);
       return;
-    } else {
-      const { Preferences } = await import("@capacitor/preferences");
+    }
+    try {
+      const { Preferences } = await loadCapacitorPreferences();
       return Preferences.remove({ key });
+    } catch {
+      removeLocalStorageItem(key);
+      return;
     }
   },
 };

package/document/filterMeta.ts

@@ -93,6 +93,11 @@ export const getFilterSortByKey = (modelRef: FilterCls, key: string) => {
   return filterMeta.sort[key];
 };
 
+export const fillMissingFilterArgs = (filterInfo: FilterInfo, args: unknown[]) => {
+  if (args.length >= filterInfo.args.length) return args;
+  return [...args, ...Array(filterInfo.args.length - args.length).fill(undefined)];
+};
+
 export type BaseFilterSortKey = "latest" | "oldest";
 export type BaseFilterQueryKey = "any";
 export type BaseFilterKey = BaseFilterSortKey | BaseFilterQueryKey;

package/fetch/client/fetchClient.ts

@@ -19,6 +19,16 @@ import { WsClient } from "./wsClient";
 type FetchHandler = (...args: unknown[]) => PromiseOrObject<unknown>;
 type UnknownRecord = Record<string, unknown>;
 
+const isNullableArg = (arg: SerializedArg) => arg.nullable ?? arg.type === "search";
+
+const normalizeQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => {
+  let length = Math.min(queryArgs.length, args.length);
+  while (length > 0 && isNullableArg(args[length - 1]) && queryArgs[length - 1] == null) length--;
+  return queryArgs.slice(0, length);
+};
+
+const expandQueryArgs = (queryArgs: unknown[], args: SerializedArg[]) => args.map((_, idx) => queryArgs[idx]);
+
 export type FetchProxy<
   FetchType = unknown,
   SliceMetaObj extends Record<string, SliceMeta> = Record<never, never>,
@@ -411,14 +421,18 @@ export class FetchClient {
     const listFn = this.handler[names.list] as (...args: unknown[]) => Promise<unknown[]>;
     const insightFn = this.handler[names.insight] as (...args: unknown[]) => Promise<unknown>;
     const initFn = async (...argData: unknown[]) => {
-      const queryArgs = Array.from({ length: argLength }, (_, idx) => argData[idx]);
+      const queryArgs = normalizeQueryArgs(
+        Array.from({ length: Math.min(argData.length, argLength) }, (_, idx) => argData[idx]),
+        slice.args,
+      );
+      const fetchQueryArgs = expandQueryArgs(queryArgs, slice.args);
       const option = (argData[argLength] ?? {}) as { page?: number; limit?: number; sort?: string; insight?: boolean };
       const { page = 1, limit = 20, sort = "latest", insight: fetchInsight = true } = option;
       const skip = (page - 1) * limit;
 
       const [modelObjList, modelObjInsight] = (await Promise.all([
-        listFn(...queryArgs, skip, limit, sort, { ...option, crystalize: false }),
-        fetchInsight ? insightFn(...queryArgs, { ...option, crystalize: false }) : null,
+        listFn(...fetchQueryArgs, skip, limit, sort, { ...option, crystalize: false }),
+        fetchInsight ? insightFn(...fetchQueryArgs, { ...option, crystalize: false }) : null,
       ])) as unknown as [BaseObject[], BaseInsight];
       const modelList = new DataList(modelObjList.map((modelObj) => new cnst.light(modelObj)));
       const modelInsight = new cnst.insight(modelObjInsight);