@ciwergrp/nuxid 1.1.4 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Nuxid – Nuxt Essentials
 
-Nuxid bundles a set of productivity helpers for Nuxt projects: lodash auto-imports, Element Plus-friendly validation rules, a form composable, helper utilities, optional icon defaults, Element Plus setup, and Pinia integration. Enable the pieces you need and keep the rest off.
+Nuxid bundles a set of productivity helpers for Nuxt projects: lodash auto-imports, Element Plus-friendly validation rules, form and cursor fetch composables, helper utilities, optional icon defaults, Element Plus setup, and Pinia integration. Enable the pieces you need and keep the rest off.
 
 ## Quick start
 
@@ -32,6 +32,7 @@ export default defineNuxtConfig({
 - **Validator helpers** (enabled by default): Element Plus friendly `createValidationRules` plus `ValidationRule` and `ValidationOptions` types. Auto-imported when enabled.
 - **Form composable** (enabled by default): `useHttp` wraps `$fetch`, handles `processing`, `errors`, `response`, and builds `FormData` automatically (or always when `alwaysFormData: true`). Auto-imported when enabled.
 - **Helper utilities** (enabled by default): array/object/number/string helpers with configurable factory (`number().abbreviate()`) or prefixed (`NumberAbbreviate()`) styles, locale lookups, and currency defaults.
+- **Cursor fetch composable** (enabled by default): `useCursorFetch` wraps `$fetch`, supports cursor pagination, polling, reactive params, custom fetchers, and configurable cursor/meta keys. Auto-imported when enabled.
 - **Pinia integration** (enabled by default): injects Pinia, auto-imports core helpers (`defineStore`, `storeToRefs`, etc.), and auto-imports stores from `stores` by default.
 - **Icon defaults** (disabled by default): installs `@nuxt/icon` with default component name `KIcon`, size `1.25em`, base class `align-middle inline-block text-current`, mode `svg`. Configure via `nuxid.icon.config`.
 - **Element Plus module** (disabled by default): installs `@element-plus/nuxt` with your provided config.
@@ -75,6 +76,21 @@ const price = number().currency(4200)
 const slug = string().slug('Hello World')
 ```
 
+**Cursor fetch example**
+
+```ts
+const { data, loadMore, refresh } = useCursorFetch('/api/messages', {
+  fetchOptions: { query: { perPage: 20 } },
+  pollInterval: 5000,
+  itemKey: 'code',
+  cursorParam: 'after',
+  meta: {
+    cursorKey: 'next_cursor',
+    hasMoreKey: 'has_next_page',
+  },
+})
+```
+
 **Pinia example**
 
 ```ts
@@ -135,6 +151,9 @@ export default defineNuxtConfig({
       enabled: true,
       storesDirs: ['stores'],
     },
+    fetcher: {
+      enabled: true,
+    },
   },
 })
 ```

package/console/resource.mjs

@@ -283,7 +283,7 @@ function reindexApiModules(baseDir, caseStyle) {
     const folderName = path.basename(dir);
     const exportName = toCase(folderName, caseStyle);
     const safeAlias = isValidIdentifier(exportName) ? exportName : toSafeIdentifier(folderName);
-    const modulePath = `./modules/${folderName}/index`;
+    const modulePath = `./modules/${folderName}`;
 
     if (safeAlias) {
       imports.push(`import * as ${safeAlias} from '${modulePath}';`);

package/dist/module.d.mts

@@ -3,6 +3,7 @@ export * from '../dist/runtime/form.js';
 export { default as useHttp } from '../dist/runtime/form.js';
 export * from '../dist/runtime/validator.js';
 export * from '../dist/runtime/helper/index.js';
+export * from '../dist/runtime/fetcher/index.js';
 
 interface LodashOptions {
     /**
@@ -196,6 +197,15 @@ interface VueUseOptions {
 }
 type VueUseFeatureInput = boolean | Partial<VueUseOptions> | undefined;
 
+interface FetcherOptions {
+    /**
+     * Enable cursor fetch composable auto-import
+     * @default true
+     */
+    enabled: boolean;
+}
+type FetcherFeatureInput = boolean | Partial<FetcherOptions> | undefined;
+
 interface ModuleOptions {
     lodash?: LodashFeatureInput;
     validator?: ValidatorFeatureInput;
@@ -205,6 +215,7 @@ interface ModuleOptions {
     helper?: HelperFeatureInput;
     pinia?: PiniaFeatureInput;
     vueuse?: VueUseFeatureInput;
+    fetcher?: FetcherFeatureInput;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

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

package/dist/module.mjs

@@ -5,6 +5,7 @@ export * from '../dist/runtime/form.js';
 export { default as useHttp } from '../dist/runtime/form.js';
 export * from '../dist/runtime/validator.js';
 export * from '../dist/runtime/helper/index.js';
+export * from '../dist/runtime/fetcher/index.js';
 
 const lodashExcludes = [
   "wrapperValue",
@@ -447,6 +448,29 @@ function registerVueUseFeature(options, nuxt) {
   });
 }
 
+const fetcherDefaults = {
+  enabled: false
+};
+function resolveFetcherOptions(input) {
+  if (input === false) {
+    return { ...fetcherDefaults, enabled: false };
+  }
+  const overrides = typeof input === "boolean" || input === void 0 ? {} : input;
+  return {
+    ...fetcherDefaults,
+    ...overrides,
+    enabled: overrides?.enabled ?? true
+  };
+}
+function registerFetcherFeature(options, { from }) {
+  if (!options.enabled) {
+    return;
+  }
+  addImports({ name: "useCursorFetch", as: "useCursorFetch", from });
+  addImports({ name: "APIResponseCursor", as: "APIResponseCursor", from, type: true });
+  addImports({ name: "CursorFetchOptions", as: "CursorFetchOptions", from, type: true });
+}
+
 const module$1 = defineNuxtModule({
   meta: {
     name: "@ciwergrp/nuxid",
@@ -470,6 +494,7 @@ const module$1 = defineNuxtModule({
     const helperOptions = resolveHelperOptions(options.helper);
     const piniaOptions = resolvePiniaOptions(options.pinia);
     const vueuseOptions = resolveVueUseOptions(options.vueuse);
+    const fetcherOptions = resolveFetcherOptions(options.fetcher);
     if (iconOptions.enabled) {
       await installModule("@nuxt/icon", iconOptions.config);
     }
@@ -494,6 +519,11 @@ const module$1 = defineNuxtModule({
         from: resolver.resolve("./runtime/helper")
       });
     }
+    if (fetcherOptions.enabled) {
+      registerFetcherFeature(fetcherOptions, {
+        from: resolver.resolve("./runtime/fetcher")
+      });
+    }
     if (piniaOptions.enabled) {
       const piniaRuntimeDir = fileURLToPath(new URL("./runtime/pinia", import.meta.url));
       registerPiniaFeature(piniaOptions, nuxt, {

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

@@ -0,0 +1,31 @@
+import type { NitroFetchOptions, NitroFetchRequest } from 'nitropack';
+export interface APIResponseCursor<T> {
+    data: T[];
+    meta: {
+        afterCursor?: string | null;
+        hasMore?: boolean;
+        [key: string]: any;
+    };
+}
+export interface CursorMetaConfig {
+    cursorKey?: string;
+    hasMoreKey?: string;
+}
+export interface CursorFetchOptions<TRequest extends NitroFetchRequest = NitroFetchRequest> {
+    lazy?: boolean;
+    pollInterval?: number;
+    fetcher?: typeof $fetch;
+    fetchOptions?: NitroFetchOptions<TRequest>;
+    meta?: CursorMetaConfig;
+    itemKey?: string;
+    cursorParam?: string;
+}
+export declare function useCursorFetch<T extends Record<string, string>, TResponse extends APIResponseCursor<T> = APIResponseCursor<T>, TRequest extends NitroFetchRequest = NitroFetchRequest>(url: TRequest, options?: CursorFetchOptions<TRequest>): {
+    data: import("vue").Ref<TResponse | undefined, TResponse | undefined>;
+    loading: Readonly<import("vue").Ref<boolean, boolean>>;
+    error: Readonly<import("vue").Ref<Error | null, Error | null>>;
+    hasNextPage: Readonly<import("vue").Ref<boolean, boolean>>;
+    isLoadMoreTriggered: Readonly<import("vue").Ref<boolean, boolean>>;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+};

package/dist/runtime/fetcher/cursor.js

@@ -0,0 +1,178 @@
+import { isRef, onUnmounted, readonly, ref, shallowRef, watch } from "vue";
+export function useCursorFetch(url, options) {
+  function findReactiveSources(obj) {
+    const sources = [];
+    if (!obj || typeof obj !== "object") {
+      return sources;
+    }
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        const value = obj[key];
+        if (isRef(value)) {
+          sources.push(value);
+        } else if (typeof value === "object") {
+          sources.push(...findReactiveSources(value));
+        }
+      }
+    }
+    return sources;
+  }
+  function unwrapReactiveObject(obj) {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+    const unwrapped = Array.isArray(obj) ? [] : {};
+    for (const key in obj) {
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        const value = obj[key];
+        if (isRef(value)) {
+          unwrapped[key] = value.value;
+        } else if (typeof value === "object") {
+          unwrapped[key] = unwrapReactiveObject(value);
+        } else {
+          unwrapped[key] = value;
+        }
+      }
+    }
+    return unwrapped;
+  }
+  const {
+    lazy = false,
+    pollInterval,
+    fetcher,
+    fetchOptions,
+    meta,
+    itemKey = "id",
+    cursorParam = "cursor"
+  } = options ?? {};
+  const initialUrl = url;
+  const data = ref();
+  const loading = ref(false);
+  const error = ref(null);
+  const nextCursor = ref(null);
+  const hasNextPage = ref(true);
+  const isLoadMoreTriggered = ref(false);
+  const currentParams = shallowRef(
+    unwrapReactiveObject(fetchOptions)
+  );
+  let pollTimer = null;
+  const fetcherFn = fetcher ?? globalThis.$fetch;
+  if (!fetcherFn) {
+    throw new Error("Nuxt $fetch is not available in the current context");
+  }
+  const normalizeKey = (value, fallback) => {
+    if (typeof value !== "string") {
+      return fallback;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : fallback;
+  };
+  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 fetchData = async (fetchUrl, params) => {
+    if (loading.value) {
+      return;
+    }
+    if (!hasNextPage.value && data.value) {
+      return;
+    }
+    loading.value = true;
+    error.value = null;
+    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 = e;
+    } finally {
+      loading.value = false;
+    }
+  };
+  const pollData = async () => {
+    try {
+      const response = await fetcherFn(initialUrl, currentParams.value);
+      if (data.value) {
+        const existingIds = new Set(
+          data.value.data.map((item) => item[resolvedItemKey])
+        );
+        const newItems = response.data.filter(
+          (item) => !existingIds.has(item[resolvedItemKey])
+        );
+        if (newItems.length > 0) {
+          data.value.data.unshift(...newItems);
+        }
+      } else {
+        data.value = response;
+        nextCursor.value = normalizeCursorValue(response.meta?.[cursorKey]);
+        hasNextPage.value = response.meta?.[hasMoreKey] ?? false;
+      }
+    } catch (e) {
+      console.error("Polling error:", e);
+    }
+  };
+  const loadMore = async () => {
+    if (!hasNextPage.value) {
+      return;
+    }
+    isLoadMoreTriggered.value = true;
+    const params = nextCursor.value ? {
+      ...currentParams.value,
+      query: { ...currentParams.value?.query, [resolvedCursorParam]: nextCursor.value }
+    } : currentParams.value;
+    await fetchData(initialUrl, params);
+  };
+  const refresh = async () => {
+    data.value = void 0;
+    nextCursor.value = null;
+    hasNextPage.value = true;
+    isLoadMoreTriggered.value = false;
+    await fetchData(initialUrl, 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 (!lazy) {
+    void fetchData(initialUrl, currentParams.value);
+  }
+  return {
+    data,
+    loading: readonly(loading),
+    error: readonly(error),
+    hasNextPage: readonly(hasNextPage),
+    isLoadMoreTriggered: readonly(isLoadMoreTriggered),
+    loadMore,
+    refresh
+  };
+}

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

@@ -0,0 +1 @@
+export * from './cursor.js';

package/dist/runtime/fetcher/index.js

@@ -0,0 +1 @@
+export * from "./cursor.js";

package/dist/types.d.mts

@@ -9,3 +9,5 @@ export * from '../dist/runtime/form.js'
 export * from '../dist/runtime/validator.js'
 
 export * from '../dist/runtime/helper/index.js'
+
+export * from '../dist/runtime/fetcher/index.js'

package/package.json

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