@ciwergrp/nuxid 1.17.8 → 1.19.0

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@ciwergrp/nuxid",
   "configKey": "nuxid",
-  "version": "1.17.8",
+  "version": "1.19.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/fetcher/cursor.d.ts

@@ -1,18 +1,28 @@
 import type { NitroFetchOptions, NitroFetchRequest } from 'nitropack';
+import type { MultiWatchSources, Ref } from 'vue';
 export interface APIResponseCursor<T> {
     data: T[];
-    meta: {
-        [key: string]: any;
-    };
+    meta: Record<string, any>;
 }
 export interface CursorMetaConfig {
     cursorKey?: string;
     hasMoreKey?: string;
 }
-export interface CursorFetchOptions<TRequest extends NitroFetchRequest = NitroFetchRequest> extends NitroFetchOptions<TRequest> {
+export interface CursorExecuteOptions {
+    dedupe?: 'cancel' | 'defer';
+    timeout?: number;
+    signal?: AbortSignal;
+}
+export interface CursorFetchOptions<TRequest extends NitroFetchRequest = NitroFetchRequest, TResponse extends APIResponseCursor<any> = APIResponseCursor<any>> {
+    cache?: 'none' | 'payload' | 'static' | 'both';
+    server?: boolean;
     lazy?: boolean;
     immediate?: boolean;
-    pollInterval?: number;
+    default?: () => TResponse | Ref<TResponse | null> | null;
+    deep?: boolean;
+    dedupe?: 'cancel' | 'defer';
+    timeout?: number;
+    watch?: MultiWatchSources | false;
     fetcher?: typeof $fetch;
     fetchOptions?: NitroFetchOptions<TRequest>;
     meta?: CursorMetaConfig;
@@ -20,28 +30,41 @@ export interface CursorFetchOptions<TRequest extends NitroFetchRequest = NitroFe
     cursorParam?: string;
     query?: Record<string, any>;
     key?: string;
+    pollInterval?: number;
 }
 export interface FetchError<TData = any> {
     statusCode: number | undefined;
     statusMessage: string | undefined;
     _data: TData | undefined;
 }
-export declare function useCursorHttp<T extends Record<string, any> = any, TResponse extends APIResponseCursor<T> = APIResponseCursor<T>, TRequest extends NitroFetchRequest = NitroFetchRequest>(url: TRequest, options?: CursorFetchOptions<TRequest>): Promise<{
-    data: import("vue").Ref<TResponse | undefined, TResponse | undefined>;
-    loading: Readonly<import("vue").Ref<boolean, boolean>>;
-    error: Readonly<import("vue").Ref<{
+export declare const normalizeFetchError: (error: unknown) => FetchError;
+export declare const ensureCursorResponse: <T extends APIResponseCursor<any>>(response: T) => T;
+export declare const extractCursorState: (response: APIResponseCursor<any>, metaConfig?: CursorMetaConfig) => {
+    nextCursor: string | null;
+    hasNextPage: boolean;
+};
+export declare const mergeCursorResponse: <T extends APIResponseCursor<any>>(current: T | undefined, next: T, itemKey: string) => T;
+export declare const buildKey: (key: string | undefined, url: NitroFetchRequest, query: Record<string, any> | undefined) => string;
+export declare const buildFetchOptions: <TRequest extends NitroFetchRequest>(baseOptions: NitroFetchOptions<TRequest> | undefined, query: Record<string, any> | undefined, signal?: AbortSignal) => NitroFetchOptions<TRequest>;
+export declare const resolveDefaultResponse: <TResponse extends APIResponseCursor<any>>(factory?: CursorFetchOptions<any, TResponse>["default"]) => TResponse | null | undefined;
+export declare function useCursorHttp<T extends Record<string, any> = any, TResponse extends APIResponseCursor<T> = APIResponseCursor<T>, TRequest extends NitroFetchRequest = NitroFetchRequest>(url: TRequest, options?: CursorFetchOptions<TRequest, TResponse>): Promise<{
+    data: [TResponse | null | undefined] extends [Ref<any, any>] ? import("@vue/shared").IfAny<Ref<any, any> & TResponse, Ref<Ref<any, any> & TResponse, Ref<any, any> & TResponse>, Ref<any, any> & TResponse> : Ref<import("vue").UnwrapRef<TResponse> | null | undefined, TResponse | import("vue").UnwrapRef<TResponse> | null | undefined>;
+    loading: Readonly<Ref<boolean, boolean>>;
+    error: Readonly<Ref<{
         readonly statusCode: number | undefined;
         readonly statusMessage: string | undefined;
         readonly _data: any;
-    } | null, {
+    } | undefined, {
         readonly statusCode: number | undefined;
         readonly statusMessage: string | undefined;
         readonly _data: any;
-    } | null>>;
-    hasNextPage: Readonly<import("vue").Ref<boolean, boolean>>;
-    isLoadMoreTriggered: Readonly<import("vue").Ref<boolean, boolean>>;
-    loadMore: () => Promise<void>;
-    refresh: () => Promise<void>;
-    init: () => Promise<void>;
+    } | undefined>>;
+    hasNextPage: Readonly<Ref<boolean, boolean>>;
+    isLoadMoreTriggered: Readonly<Ref<boolean, boolean>>;
+    loadMore: (executeOptions?: CursorExecuteOptions) => Promise<void>;
+    refresh: (executeOptions?: CursorExecuteOptions) => Promise<void>;
+    execute: (executeOptions?: CursorExecuteOptions) => Promise<void>;
+    clear: () => void;
+    init: (executeOptions?: CursorExecuteOptions) => Promise<void>;
 }>;
 export default useCursorHttp;

package/dist/runtime/fetcher/cursor.js

@@ -1,281 +1,485 @@
-import { isRef, onBeforeMount, onUnmounted, readonly, ref, shallowRef, watch } from "vue";
-export async function useCursorHttp(url, options) {
-  function findReactiveSources(obj) {
-    const sources = [];
-    if (!obj || typeof obj !== "object") {
-      return sources;
+import { isRef, onMounted, onUnmounted, readonly, ref, shallowRef, watch } from "vue";
+const META_CURSOR_CANDIDATES = ["afterCursor", "next_cursor", "nextCursor", "cursor"];
+const META_HAS_MORE_CANDIDATES = ["hasMore", "has_next_page", "hasNextPage", "has_next"];
+const normalizeString = (value, fallback) => {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+};
+const normalizeCursorValue = (value) => {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  return String(value);
+};
+const resolveItemKeyValue = (item, itemKey) => {
+  const normalizedKey = normalizeString(itemKey, "");
+  if (!normalizedKey || !item || typeof item !== "object") {
+    return void 0;
+  }
+  const record = item;
+  if (Object.prototype.hasOwnProperty.call(record, normalizedKey)) {
+    return record[normalizedKey];
+  }
+  if (!normalizedKey.includes(".")) {
+    return record[normalizedKey];
+  }
+  return normalizedKey.split(".").reduce((current, segment) => {
+    if (current === null || current === void 0) {
+      return void 0;
     }
-    for (const key2 in obj) {
-      if (Object.prototype.hasOwnProperty.call(obj, key2)) {
-        const value = obj[key2];
-        if (isRef(value)) {
-          sources.push(value);
-        } else if (typeof value === "object") {
-          sources.push(...findReactiveSources(value));
-        }
-      }
+    return current[segment];
+  }, item);
+};
+const cloneResponse = (response) => ({
+  ...response,
+  data: [...response.data]
+});
+export const normalizeFetchError = (error) => {
+  if (error && typeof error === "object") {
+    const cast = error;
+    return {
+      statusCode: typeof cast.statusCode === "number" ? cast.statusCode : void 0,
+      statusMessage: typeof cast.statusMessage === "string" ? cast.statusMessage : cast.message ?? void 0,
+      _data: cast.data
+    };
+  }
+  if (typeof error === "string") {
+    return {
+      statusCode: void 0,
+      statusMessage: error,
+      _data: void 0
+    };
+  }
+  return {
+    statusCode: void 0,
+    statusMessage: "Unknown error",
+    _data: void 0
+  };
+};
+export const ensureCursorResponse = (response) => {
+  if (!response || typeof response !== "object" || !Array.isArray(response.data)) {
+    throw new Error("Cursor responses must include a data array");
+  }
+  return response;
+};
+const unwrapReactiveObject = (value) => {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const unwrapped = Array.isArray(value) ? [] : {};
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
+    }
+    const current = value[key];
+    if (isRef(current)) {
+      ;
+      unwrapped[key] = current.value;
+      continue;
     }
+    if (current && typeof current === "object") {
+      ;
+      unwrapped[key] = unwrapReactiveObject(current);
+      continue;
+    }
+    ;
+    unwrapped[key] = current;
+  }
+  return unwrapped;
+};
+const findReactiveSources = (value) => {
+  const sources = [];
+  if (!value || typeof value !== "object") {
     return sources;
   }
-  function unwrapReactiveObject(obj) {
-    if (!obj || typeof obj !== "object") {
-      return obj;
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      continue;
     }
-    const unwrapped = Array.isArray(obj) ? [] : {};
-    for (const key2 in obj) {
-      if (Object.prototype.hasOwnProperty.call(obj, key2)) {
-        const value = obj[key2];
-        if (isRef(value)) {
-          unwrapped[key2] = value.value;
-        } else if (typeof value === "object") {
-          unwrapped[key2] = unwrapReactiveObject(value);
-        } else {
-          unwrapped[key2] = value;
-        }
-      }
+    const current = value[key];
+    if (isRef(current)) {
+      sources.push(current);
+      continue;
     }
-    return unwrapped;
-  }
-  function normalizeFetchError(e) {
-    if (e && typeof e === "object") {
-      const cast = e;
-      return {
-        statusCode: typeof cast.statusCode === "number" ? cast.statusCode : void 0,
-        statusMessage: typeof cast.statusMessage === "string" ? cast.statusMessage : cast.message ?? void 0,
-        _data: cast.data
-      };
+    if (current && typeof current === "object") {
+      sources.push(...findReactiveSources(current));
     }
-    if (typeof e === "string") {
-      return { statusCode: void 0, statusMessage: e, _data: void 0 };
+  }
+  return sources;
+};
+const uniqueSources = (sources) => Array.from(new Set(sources));
+const resolveCursorMetaValue = (meta, explicitKey, candidates) => {
+  if (!meta || typeof meta !== "object") {
+    return void 0;
+  }
+  const normalizedKey = normalizeString(explicitKey, "");
+  if (normalizedKey) {
+    return meta[normalizedKey];
+  }
+  for (const candidate of candidates) {
+    if (candidate in meta) {
+      return meta[candidate];
     }
-    return { statusCode: void 0, statusMessage: "Unknown error", _data: void 0 };
   }
+  return void 0;
+};
+export const extractCursorState = (response, metaConfig) => {
+  const cursorValue = resolveCursorMetaValue(response.meta, metaConfig?.cursorKey, META_CURSOR_CANDIDATES);
+  const hasMoreValue = resolveCursorMetaValue(response.meta, metaConfig?.hasMoreKey, META_HAS_MORE_CANDIDATES);
+  return {
+    nextCursor: normalizeCursorValue(cursorValue),
+    hasNextPage: Boolean(hasMoreValue)
+  };
+};
+export const mergeCursorResponse = (current, next, itemKey) => {
+  if (!current) {
+    return cloneResponse(next);
+  }
+  const knownKeys = new Set(
+    current.data.map((item) => resolveItemKeyValue(item, itemKey))
+  );
+  const newItems = next.data.filter((item) => !knownKeys.has(resolveItemKeyValue(item, itemKey)));
+  return {
+    ...next,
+    data: [...current.data, ...newItems]
+  };
+};
+export const buildKey = (key, url, query) => {
+  const normalizedKey = normalizeString(key, "");
+  if (normalizedKey) {
+    return normalizedKey;
+  }
+  try {
+    return `${String(url)}:${JSON.stringify(query ?? {})}`;
+  } catch {
+    return String(url);
+  }
+};
+export const buildFetchOptions = (baseOptions, query, signal) => {
+  const currentQuery = {
+    ...baseOptions?.query ?? {},
+    ...query ?? {}
+  };
+  return {
+    ...baseOptions,
+    query: currentQuery,
+    signal
+  };
+};
+export const resolveDefaultResponse = (factory) => {
+  const value = factory?.();
+  return isRef(value) ? value.value : value ?? void 0;
+};
+const createTimeoutAbortController = (timeout) => {
+  if (!timeout || timeout <= 0) {
+    return void 0;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  return {
+    controller,
+    clear: () => clearTimeout(timer)
+  };
+};
+const resolveCachedDataGetter = (cache) => {
+  if (cache === "none" || cache === void 0) {
+    return () => void 0;
+  }
+  if (cache === "payload") {
+    return (key, nuxtApp) => nuxtApp.isHydrating ? nuxtApp.payload.data[key] : void 0;
+  }
+  if (cache === "static") {
+    return (key, nuxtApp) => nuxtApp.static.data[key];
+  }
+  return (key, nuxtApp) => nuxtApp.isHydrating ? nuxtApp.payload.data[key] : nuxtApp.static.data[key];
+};
+export async function useCursorHttp(url, options) {
   const {
+    cache = "none",
+    server = true,
     lazy = false,
     immediate = true,
-    pollInterval,
+    default: defaultFactory,
+    deep = false,
+    dedupe = "cancel",
+    timeout,
+    watch: watchSources = void 0,
     fetcher,
     fetchOptions,
     query,
     meta,
     itemKey = "id",
     cursorParam = "cursor",
-    key
+    key,
+    pollInterval
   } = options ?? {};
-  const initialUrl = url;
-  const data = ref();
-  const loading = ref(false);
-  const error = ref(null);
+  const fetcherFn = fetcher ?? globalThis.$fetch;
+  if (!fetcherFn) {
+    throw new Error("Nuxt $fetch is not available in the current context");
+  }
+  const { useAsyncData } = await import("#app");
+  const { clearNuxtData } = await import("#app");
+  const resolvedKey = buildKey(key, url, query ?? fetchOptions?.query);
+  const instanceId = cache === "none" ? globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}` : "";
+  const stateKey = cache === "none" ? `${resolvedKey}:${instanceId}` : resolvedKey;
+  const resolvedBaseOptions = shallowRef(
+    unwrapReactiveObject(fetchOptions)
+  );
+  const reactiveSources = uniqueSources([
+    ...watchSources === false ? [] : Array.isArray(watchSources) ? watchSources : watchSources ? [watchSources] : [],
+    ...findReactiveSources(fetchOptions),
+    ...findReactiveSources(query)
+  ]);
+  const data = ref(resolveDefaultResponse(defaultFactory));
   const nextCursor = ref(null);
   const hasNextPage = ref(true);
+  const hasResolvedInitial = ref(false);
   const isLoadMoreTriggered = ref(false);
-  const currentParams = shallowRef(
-    unwrapReactiveObject(fetchOptions) ?? {}
+  const loadMorePending = ref(false);
+  const loadMoreError = ref(void 0);
+  const pollTimer = ref(null);
+  const loadMoreRequest = ref(null);
+  const loadMoreAbortController = ref(null);
+  const asyncData = await useAsyncData(
+    stateKey,
+    async (_nuxtApp, { signal }) => {
+      const requestOptions = buildFetchOptions(
+        resolvedBaseOptions.value,
+        unwrapReactiveObject(query),
+        signal
+      );
+      const response = await fetcherFn(url, requestOptions);
+      return ensureCursorResponse(response);
+    },
+    {
+      server,
+      lazy,
+      immediate,
+      default: defaultFactory,
+      deep,
+      dedupe,
+      timeout,
+      getCachedData: resolveCachedDataGetter(cache)
+    }
   );
-  const normalizeStateKey = (value, fallback) => {
-    if (typeof value !== "string") {
-      return fallback;
+  const syncResponseState = (response) => {
+    if (!response) {
+      nextCursor.value = null;
+      hasNextPage.value = false;
+      hasResolvedInitial.value = false;
+      data.value = response ?? resolveDefaultResponse(defaultFactory);
+      return;
     }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : fallback;
+    const clonedResponse = cloneResponse(response);
+    const cursorState = extractCursorState(clonedResponse, meta);
+    data.value = clonedResponse;
+    nextCursor.value = cursorState.nextCursor;
+    hasNextPage.value = cursorState.hasNextPage;
+    hasResolvedInitial.value = true;
   };
-  const stateKey = normalizeStateKey(key, (() => {
-    try {
-      const queryValue = query ?? currentParams.value?.query ?? {};
-      return `${String(url)}:${JSON.stringify(queryValue)}`;
-    } catch {
-      return String(url);
-    }
-  })());
-  const { useNuxtApp, useState } = await import("#app");
-  const nuxtApp = useNuxtApp();
-  const initialResponseState = useState(stateKey, () => null);
-  let pollTimer = null;
-  let fetchPromise = null;
-  const fetcherFn = fetcher ?? globalThis.$fetch;
-  if (!fetcherFn) {
-    throw new Error("Nuxt $fetch is not available in the current context");
+  watch(
+    () => asyncData.data.value,
+    (response) => {
+      syncResponseState(response);
+      loadMoreError.value = void 0;
+      isLoadMoreTriggered.value = false;
+    },
+    { immediate: true }
+  );
+  if (reactiveSources.length > 0) {
+    watch(
+      reactiveSources,
+      () => {
+        resolvedBaseOptions.value = unwrapReactiveObject(fetchOptions);
+        void refresh();
+      },
+      { flush: "sync" }
+    );
   }
-  const normalizeKey = (value, fallback) => {
-    if (typeof value !== "string") {
-      return fallback;
-    }
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : fallback;
+  if (cache === "none") {
+    onUnmounted(() => {
+      clearNuxtData(stateKey);
+    });
+  }
+  const resetCursorState = () => {
+    nextCursor.value = null;
+    hasNextPage.value = true;
+    hasResolvedInitial.value = false;
+    isLoadMoreTriggered.value = false;
+    loadMorePending.value = false;
+    loadMoreError.value = void 0;
+    data.value = resolveDefaultResponse(defaultFactory);
   };
-  const cursorKey = normalizeKey(meta?.cursorKey, "afterCursor");
-  const hasMoreKey = normalizeKey(meta?.hasMoreKey, "hasMore");
-  const resolvedItemKey = normalizeKey(itemKey, "id");
-  const resolvedCursorParam = normalizeKey(cursorParam, "cursor");
-  const normalizeCursorValue = (value) => {
-    if (value === null || value === void 0) {
-      return null;
-    }
-    if (typeof value === "string") {
-      const trimmed = value.trim();
-      return trimmed.length > 0 ? trimmed : null;
-    }
-    return String(value);
+  const cancelLoadMore = () => {
+    loadMoreAbortController.value?.abort();
+    loadMoreAbortController.value = null;
+    loadMoreRequest.value = null;
+    loadMorePending.value = false;
   };
-  const cloneResponse = (response) => ({
-    ...response,
-    data: [...response.data]
-  });
-  const applyResponse = (response, cacheInitial = false) => {
-    data.value = cloneResponse(response);
-    nextCursor.value = normalizeCursorValue(response.meta?.[cursorKey]);
-    hasNextPage.value = response.meta?.[hasMoreKey] ?? false;
-    if (cacheInitial) {
-      initialResponseState.value = cloneResponse(response);
-    }
+  const refresh = async (executeOptions) => {
+    cancelLoadMore();
+    resetCursorState();
+    await asyncData.refresh(executeOptions);
   };
-  const fetchData = async (fetchUrl, params) => {
-    if (loading.value) {
-      return fetchPromise ?? Promise.resolve();
-    }
-    if (!hasNextPage.value && data.value) {
-      return Promise.resolve();
-    }
-    loading.value = true;
-    error.value = null;
-    const promise = (async () => {
-      try {
-        const response = await fetcherFn(fetchUrl, params);
-        data.value = {
-          ...response,
-          data: [...data.value?.data ?? [], ...response.data]
-        };
-        nextCursor.value = normalizeCursorValue(response.meta?.[cursorKey]);
-        hasNextPage.value = response.meta?.[hasMoreKey] ?? false;
-      } catch (e) {
-        error.value = normalizeFetchError(e);
-      } finally {
-        loading.value = false;
-      }
-    })();
-    fetchPromise = promise;
-    try {
-      await promise;
-    } finally {
-      if (fetchPromise === promise) {
-        fetchPromise = null;
+  const execute = async (executeOptions) => {
+    await refresh(executeOptions);
+  };
+  const init = async (executeOptions) => {
+    await execute(executeOptions);
+  };
+  const clear = () => {
+    cancelLoadMore();
+    asyncData.clear();
+    clearNuxtData(stateKey);
+    resetCursorState();
+  };
+  const loadMore = async (executeOptions) => {
+    if (loadMorePending.value) {
+      if (dedupe === "defer") {
+        return loadMoreRequest.value ?? Promise.resolve();
       }
+      cancelLoadMore();
     }
-  };
-  const fetchInitialData = async (params, useCache = true) => {
-    if (loading.value) {
-      return fetchPromise ?? Promise.resolve();
+    if (!hasResolvedInitial.value) {
+      await init(executeOptions);
     }
-    const canUseHydrationCache = import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered;
-    if (useCache && canUseHydrationCache && initialResponseState.value) {
-      applyResponse(initialResponseState.value);
+    if (!hasResolvedInitial.value || !data.value || !hasNextPage.value) {
       return Promise.resolve();
     }
-    loading.value = true;
-    error.value = null;
-    const promise = (async () => {
+    isLoadMoreTriggered.value = true;
+    loadMorePending.value = true;
+    loadMoreError.value = void 0;
+    const pendingRequest = (async () => {
+      const timeoutHandle = createTimeoutAbortController(executeOptions?.timeout ?? timeout);
+      const requestAbortController = new AbortController();
+      loadMoreAbortController.value = requestAbortController;
+      if (executeOptions?.signal) {
+        if (executeOptions.signal.aborted) {
+          requestAbortController.abort();
+        } else {
+          executeOptions.signal.addEventListener("abort", () => requestAbortController.abort(), { once: true });
+        }
+      }
+      if (timeoutHandle) {
+        const timeoutSignal = timeoutHandle.controller.signal;
+        if (timeoutSignal.aborted) {
+          requestAbortController.abort();
+        } else {
+          timeoutSignal.addEventListener("abort", () => requestAbortController.abort(), { once: true });
+        }
+      }
       try {
-        const response = await fetcherFn(initialUrl, params ?? currentParams.value);
-        applyResponse(response, true);
-      } catch (e) {
-        error.value = normalizeFetchError(e);
+        const baseOptions = resolvedBaseOptions.value ?? {};
+        const nextQuery = {
+          ...unwrapReactiveObject(query) ?? {}
+        };
+        if (nextCursor.value !== null) {
+          nextQuery[normalizeString(cursorParam, "cursor")] = nextCursor.value;
+        }
+        const requestOptions = buildFetchOptions(baseOptions, nextQuery, requestAbortController.signal);
+        const response = ensureCursorResponse(await fetcherFn(url, requestOptions));
+        const mergedResponse = mergeCursorResponse(data.value ?? void 0, response, normalizeString(itemKey, "id"));
+        const cursorState = extractCursorState(mergedResponse, meta);
+        data.value = mergedResponse;
+        nextCursor.value = cursorState.nextCursor;
+        hasNextPage.value = cursorState.hasNextPage;
+      } catch (error2) {
+        loadMoreError.value = normalizeFetchError(error2);
       } finally {
-        loading.value = false;
+        timeoutHandle?.clear();
+        loadMorePending.value = false;
+        loadMoreAbortController.value = null;
+        loadMoreRequest.value = null;
       }
     })();
-    fetchPromise = promise;
-    try {
-      await promise;
-    } finally {
-      if (fetchPromise === promise) {
-        fetchPromise = null;
-      }
-    }
+    loadMoreRequest.value = pendingRequest;
+    await pendingRequest;
   };
   const pollData = async () => {
     try {
-      const response = await fetcherFn(initialUrl, currentParams.value);
+      const response = ensureCursorResponse(
+        await fetcherFn(
+          url,
+          buildFetchOptions(resolvedBaseOptions.value, unwrapReactiveObject(query))
+        )
+      );
       if (data.value) {
         const existingIds = new Set(
-          data.value.data.map((item) => item[resolvedItemKey])
-        );
-        const newItems = response.data.filter(
-          (item) => !existingIds.has(item[resolvedItemKey])
+          data.value.data.map((item) => resolveItemKeyValue(item, normalizeString(itemKey, "id")))
         );
+        const newItems = response.data.filter((item) => !existingIds.has(resolveItemKeyValue(item, normalizeString(itemKey, "id"))));
         if (newItems.length > 0) {
-          data.value.data.unshift(...newItems);
+          data.value = {
+            ...response,
+            data: [...newItems, ...data.value.data]
+          };
         }
-      } else {
-        applyResponse(response, true);
-      }
-    } catch (e) {
-      console.error("Polling error:", e);
-    }
-  };
-  const loadMore = async () => {
-    if (!hasNextPage.value) {
-      return;
-    }
-    isLoadMoreTriggered.value = true;
-    const baseParams = currentParams.value ?? {};
-    const params = nextCursor.value ? {
-      ...baseParams,
-      query: {
-        ...baseParams.query ?? {},
-        [resolvedCursorParam]: nextCursor.value
+        const cursorState = extractCursorState(data.value, meta);
+        nextCursor.value = cursorState.nextCursor;
+        hasNextPage.value = cursorState.hasNextPage;
+        return;
       }
-    } : baseParams;
-    await fetchData(initialUrl, params);
-  };
-  const refresh = async () => {
-    data.value = void 0;
-    nextCursor.value = null;
-    hasNextPage.value = true;
-    isLoadMoreTriggered.value = false;
-    await fetchInitialData(currentParams.value, false);
-  };
-  const init = async () => {
-    if (data.value) {
-      return;
+      syncResponseState(response);
+    } catch {
     }
-    await fetchInitialData(currentParams.value);
   };
-  const reactiveSources = findReactiveSources(fetchOptions);
-  if (reactiveSources.length > 0) {
-    watch(
-      reactiveSources,
-      () => {
-        currentParams.value = unwrapReactiveObject(fetchOptions) ?? {};
-        refresh();
-      },
-      { flush: "sync" }
-    );
-  }
   if (pollInterval) {
-    pollTimer = setInterval(pollData, pollInterval);
-  }
-  onUnmounted(() => {
-    if (pollTimer) {
-      clearInterval(pollTimer);
-    }
-  });
-  if (immediate) {
-    if (import.meta.client && lazy) {
-      onBeforeMount(() => {
-        void fetchInitialData();
-      });
-    } else {
-      await fetchInitialData();
-    }
+    onMounted(() => {
+      pollTimer.value = setInterval(pollData, pollInterval);
+    });
+    onUnmounted(() => {
+      if (pollTimer.value) {
+        clearInterval(pollTimer.value);
+        pollTimer.value = null;
+      }
+    });
   }
+  const status = ref("idle");
+  watch(
+    [() => asyncData.status.value, loadMorePending, loadMoreError],
+    ([asyncStatus]) => {
+      if (loadMoreError.value) {
+        status.value = "error";
+        return;
+      }
+      status.value = loadMorePending.value ? "pending" : asyncStatus;
+    },
+    { immediate: true }
+  );
+  const error = ref(void 0);
+  watch(
+    [() => asyncData.error.value, loadMoreError],
+    ([initialError]) => {
+      error.value = loadMoreError.value ?? (initialError ? normalizeFetchError(initialError) : void 0);
+    },
+    { immediate: true }
+  );
+  const pending = ref(false);
+  watch(
+    [() => asyncData.pending.value, loadMorePending],
+    ([initialPending]) => {
+      pending.value = Boolean(initialPending || loadMorePending.value);
+    },
+    { immediate: true }
+  );
+  const loading = readonly(pending);
   return {
     data,
-    loading: readonly(loading),
+    loading,
     error: readonly(error),
     hasNextPage: readonly(hasNextPage),
     isLoadMoreTriggered: readonly(isLoadMoreTriggered),
     loadMore,
     refresh,
+    execute,
+    clear,
     init
   };
 }

package/docs/.docs/composables/use-cursor-http.md

@@ -1,6 +1,6 @@
 # useCursorHttp
 
-`useCursorHttp` wraps cursor-based APIs for infinite lists. It merges new pages, exposes `loadMore` and `refresh`, and can poll for new items.
+`useCursorHttp` wraps cursor-based APIs for infinite lists. It is Nuxt lifecycle-aware, so it can fetch on the server, hydrate on the client without duplicate requests, and keep `lazy`/`immediate` behavior familiar.
 
 ## Signature
 
@@ -10,15 +10,25 @@ const result = await useCursorHttp(url, options?)
 
 ## Options
 
-- `lazy` (boolean): skip the first fetch until `init()` is called.
+- `server` (boolean): fetch during SSR. Default: `true`.
+- `lazy` (boolean): do not block navigation while fetching. Default: `false`.
 - `immediate` (boolean): run the first fetch on creation. Default: `true`.
+- `cache` (string): caching strategy. Default: `none`.
+  - `none`: always fresh; uses a unique instance key and clears cached data on unmount.
+  - `payload`: reuse SSR/hydration payload only.
+  - `static`: reuse static payload only.
+  - `both`: reuse Nuxt payload/static data.
+- `default` (function): initial value before the request resolves.
+- `watch` (sources): auto-refresh when reactive sources change.
+- `dedupe` (string): control overlapping requests (`cancel` or `defer`).
+- `timeout` (number): abort slow requests.
 - `pollInterval` (number): poll interval in ms for new items.
 - `fetcher` (function): custom fetcher. Defaults to Nuxt `$fetch`.
 - `fetchOptions` (object): passed to `$fetch`, supports refs for reactive params.
 - `meta` (object): response meta keys.
-- `meta.cursorKey` (string): key for the next cursor. Default: `afterCursor`.
-- `meta.hasMoreKey` (string): key for more data. Default: `hasMore`.
-- `itemKey` (string): unique item id to dedupe polls. Default: `id`.
+- `meta.cursorKey` (string): key for the next cursor.
+- `meta.hasMoreKey` (string): key for more data.
+- `itemKey` (string): unique item id to dedupe polls. Supports dot paths like `customer.id`. Default: `id`.
 - `cursorParam` (string): query param for cursor. Default: `cursor`.
 
 ## Returns
@@ -30,6 +40,8 @@ const result = await useCursorHttp(url, options?)
 - `isLoadMoreTriggered` (readonly ref)
 - `loadMore()` (function)
 - `refresh()` (function)
+- `execute()` (function)
+- `clear()` (function)
 - `init()` (function)
 
 ## Examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciwergrp/nuxid",
-  "version": "1.17.8",
+  "version": "1.19.0",
   "description": "All-in-one essential modules for Nuxt",
   "repository": {
     "type": "git",