xn-fe-tools 1.0.5 → 1.2.0

package/dist/hooks/useTableRequest/index.d.ts

@@ -0,0 +1,148 @@
+import { type Ref, type ComputedRef } from 'vue';
+import { type MaybeRef, type MaybeRefOrGetter } from '../../utils/utils';
+export type { MaybeRef, MaybeRefOrGetter };
+/** 请求函数类型 */
+export type RequestFunction<P, R> = (params: P) => Promise<R>;
+/** 分页配置 */
+export interface PaginationConfig {
+    /** 默认页码，默认 1 */
+    defaultPage?: number;
+    /** 默认每页数量，默认 10 */
+    defaultPageSize?: number;
+    /** 页码字段名，默认 'page' */
+    pageKey?: string;
+    /** 每页数量字段名，默认 'pageSize' */
+    pageSizeKey?: string;
+}
+/** 转换结果类型 */
+export interface TransformResultData<T> {
+    /** 列表数据 */
+    list: T[];
+    /** 总数 */
+    total: number;
+}
+/** Hook 配置选项 */
+export interface UseTableRequestOptions<P, R, T> {
+    /** 请求参数（响应式） */
+    params?: MaybeRefOrGetter<P>;
+    /** 是否立即执行，默认 true */
+    immediate?: boolean;
+    /** 防抖延迟（毫秒），默认 0（不防抖） */
+    debounceDelay?: number;
+    /** 分页配置 */
+    pagination?: PaginationConfig;
+    /** 数据列表字段名，默认空（直接使用 response），支持点号分隔的嵌套路径，如 "data" 或 "data.list" */
+    dataField?: string;
+    /** 总数字段名，默认空（自动推断），支持点号分隔的嵌套路径，如 "total" 或 "data.total" */
+    totalField?: string;
+    /** 当前页码字段名，默认空（不修正），支持点号分隔的嵌套路径，如 "page" 或 "data.currentPage" */
+    currentPageField?: string;
+    /** 请求前转换参数 */
+    transformParams?: (params: P, pagination: {
+        page: number;
+        pageSize: number;
+    }) => any;
+    /** 请求后转换结果，返回 { list, total } */
+    transformResult?: (response: R) => TransformResultData<T>;
+    /** 请求成功回调 */
+    onSuccess?: (data: T[], response: R) => void;
+    /** 请求失败回调 */
+    onError?: (error: Error) => void;
+}
+/** 分页信息 */
+export interface PaginationState {
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总数 */
+    total: number;
+}
+/** Hook 返回值 */
+export interface UseTableRequestReturn<T> {
+    /** 列表数据 */
+    data: Ref<T[]>;
+    /** 加载状态 */
+    loading: Ref<boolean>;
+    /** 错误信息 */
+    error: Ref<Error | null>;
+    /** 分页信息 */
+    pagination: ComputedRef<PaginationState>;
+    /** 手动触发请求 */
+    run: () => Promise<void>;
+    /** 翻页 */
+    onPageChange: (page: number) => Promise<void>;
+    /** 改变每页数量 */
+    onSizeChange: (size: number) => Promise<void>;
+}
+/** useTableRequest 全局配置选项 */
+export interface UseTableRequestGlobalConfig {
+    /** 是否立即执行，默认 true */
+    immediate?: boolean;
+    /** 防抖延迟（毫秒），默认 0（不防抖） */
+    debounceDelay?: number;
+    /** 分页配置 */
+    pagination?: PaginationConfig;
+    /** 数据列表字段名，默认空（直接使用 response），支持点号分隔的嵌套路径，如 "data" 或 "data.list" */
+    dataField?: string;
+    /** 总数字段名，默认空（自动推断），支持点号分隔的嵌套路径，如 "total" 或 "data.total" */
+    totalField?: string;
+    /** 当前页码字段名，默认空（不修正），支持点号分隔的嵌套路径，如 "page" 或 "data.currentPage" */
+    currentPageField?: string;
+}
+/**
+ * 设置 useTableRequest 全局默认配置
+ *
+ * @param config - 全局配置选项
+ *
+ * @example
+ * ```ts
+ * import { setTableRequestGlobalConfig } from 'xn-fe-tools'
+ *
+ * // 在应用入口处设置全局默认配置
+ * setTableRequestGlobalConfig({
+ *   immediate: true,
+ *   debounceDelay: 500,
+ *   pagination: {
+ *     defaultPageSize: 20,
+ *     pageKey: 'pageNum',
+ *     pageSizeKey: 'size',
+ *   },
+ * })
+ * ```
+ */
+export declare function setTableRequestGlobalConfig(config: UseTableRequestGlobalConfig): void;
+/**
+ * 获取当前 useTableRequest 全局配置
+ *
+ * @returns 当前全局配置的副本
+ */
+export declare function getTableRequestGlobalConfig(): UseTableRequestGlobalConfig;
+/**
+ * 用于表格请求的 Hook，支持分页、防抖、自动/手动请求
+ *
+ * @param requestFn - 请求函数，接收参数并返回 Promise
+ * @param options - 配置选项
+ * @returns 返回数据、状态和操作方法
+ *
+ * @example
+ * ```ts
+ * const { data, loading, pagination, run, onPageChange, onSizeChange } = useTableRequest(
+ *   (params) => fetchUserList(params),
+ *   {
+ *     params: computed(() => ({ keyword: search.value })),
+ *     immediate: true,
+ *     pagination: {
+ *       defaultPage: 1,
+ *       defaultPageSize: 10,
+ *       pageKey: 'page',
+ *       pageSizeKey: 'pageSize',
+ *     },
+ *     transformParams: (params, pagination) => ({ ...params, ...pagination }),
+ *     transformResult: (res) => ({ list: res.data.records, total: res.data.total }),
+ *   }
+ * )
+ * ```
+ */
+export declare function useTableRequest<P extends object, R, T = any>(requestFn: RequestFunction<any, R>, options?: UseTableRequestOptions<P, R, T>): UseTableRequestReturn<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/useTableRequest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/useTableRequest/index.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./toAwaitFetch/toAwaitFetch.cjs.js"),t=require("./version.cjs.js");exports.cancel=e.cancel,exports.createInstance=e.createInstance,exports.sendGet=e.sendGet,exports.sendGetBlob=e.sendGetBlob,exports.sendPost=e.sendPost,exports.sendPostBlob=e.sendPostBlob,exports.sendPostForm=e.sendPostForm,exports.setGlobalConfig=e.setGlobalConfig,exports.toAwaitFetch=e.default,exports.VERSION=t.VERSION,exports.getVersion=t.getVersion;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./toAwaitFetch/toAwaitFetch.cjs.js"),t=require("./useTableRequest/index.cjs.js"),s=require("./version.cjs.js");exports.cancel=e.cancel,exports.createInstance=e.createInstance,exports.sendGet=e.sendGet,exports.sendGetBlob=e.sendGetBlob,exports.sendPost=e.sendPost,exports.sendPostBlob=e.sendPostBlob,exports.sendPostForm=e.sendPostForm,exports.setGlobalConfig=e.setGlobalConfig,exports.toAwaitFetch=e.default,exports.getTableRequestGlobalConfig=t.getTableRequestGlobalConfig,exports.setTableRequestGlobalConfig=t.setTableRequestGlobalConfig,exports.useTableRequest=t.useTableRequest,exports.VERSION=s.VERSION,exports.getVersion=s.getVersion;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './hooks/toAwaitFetch/toAwaitFetch.api';
 export { default as toAwaitFetch, sendGet, sendPost, sendPostForm, sendPostBlob, sendGetBlob, setGlobalConfig, cancel, createInstance, } from './hooks/toAwaitFetch/toAwaitFetch';
+export * from './hooks/useTableRequest';
 export { VERSION, getVersion } from './version';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,uCAAuC,CAAA;AACrD,OAAO,EACL,OAAO,IAAI,YAAY,EACvB,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,MAAM,EACN,cAAc,GACf,MAAM,mCAAmC,CAAA;AAG1C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,cAAc,uCAAuC,CAAA;AACrD,OAAO,EACL,OAAO,IAAI,YAAY,EACvB,OAAO,EACP,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,eAAe,EACf,MAAM,EACN,cAAc,GACf,MAAM,mCAAmC,CAAA;AAE1C,cAAc,yBAAyB,CAAA;AAEvC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.es.js

@@ -1 +1 @@
-import{cancel as t,createInstance as o,sendGet as e,sendGetBlob as s,sendPost as a,sendPostBlob as i,sendPostForm as r,setGlobalConfig as m,default as c}from"./toAwaitFetch/toAwaitFetch.es.js";import{VERSION as f,getVersion as h}from"./version.es.js";export{f as VERSION,t as cancel,o as createInstance,h as getVersion,e as sendGet,s as sendGetBlob,a as sendPost,i as sendPostBlob,r as sendPostForm,m as setGlobalConfig,c as toAwaitFetch};
+import{cancel as t,createInstance as e,sendGet as o,sendGetBlob as s,sendPost as i,sendPostBlob as r,sendPostForm as a,setGlobalConfig as m,default as f}from"./toAwaitFetch/toAwaitFetch.es.js";import{getTableRequestGlobalConfig as p,setTableRequestGlobalConfig as c,useTableRequest as h}from"./useTableRequest/index.es.js";import{VERSION as j,getVersion as u}from"./version.es.js";export{j as VERSION,t as cancel,e as createInstance,p as getTableRequestGlobalConfig,u as getVersion,o as sendGet,s as sendGetBlob,i as sendPost,r as sendPostBlob,a as sendPostForm,m as setGlobalConfig,c as setTableRequestGlobalConfig,f as toAwaitFetch,h as useTableRequest};

package/dist/useTableRequest/index.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("vue"),a=require("../utils/utils.cjs.js"),t={};exports.getTableRequestGlobalConfig=function(){return{...t,pagination:{...t.pagination}}},exports.setTableRequestGlobalConfig=function(e){Object.assign(t,e),e.pagination&&(t.pagination={...t.pagination,...e.pagination})},exports.useTableRequest=function(l,n={}){const u={...t.pagination,...n.pagination},{params:o,immediate:r=t.immediate??!0,debounceDelay:i=t.debounceDelay??0,dataField:s=t.dataField??"",totalField:c=t.totalField??"",currentPageField:g=t.currentPageField??"",transformParams:v,transformResult:f,onSuccess:p,onError:d}=n,{defaultPage:y=1,defaultPageSize:b=10,pageKey:m="page",pageSizeKey:S="pageSize"}=u,P=e.ref([]),w=e.ref(!1),R=e.ref(null),q=e.ref(y),T=e.ref(b),h=e.ref(0);let F=0;const j=e.computed(()=>({page:q.value,pageSize:T.value,total:h.value}));async function z(){const e=++F;w.value=!0,R.value=null;try{const t=o?a.toValue(o):{},n={[m]:q.value,[S]:T.value};let u;u=v?v(t,{page:q.value,pageSize:T.value}):{...t,...n};const r=await l(u);if(e!==F)return;if(f){const e=f(r);e&&"object"==typeof e&&Array.isArray(e.list)?(P.value=e.list,h.value="number"==typeof e.total?e.total:e.list.length):(P.value=[],h.value=0,console.warn("[useTableRequest] transformResult 返回格式无法识别，请返回 { list: T[], total: number } 格式。"))}else{const e=r;Array.isArray(e)?(P.value=e,h.value=e.length):e&&"object"==typeof e?(s&&""!==s.trim()?P.value=a.getPropValue(e,s)||[]:P.value=e.list||e.data||e.records||e.items||[],c&&""!==c.trim()?h.value=a.getPropValue(e,c)??0:h.value=e.total??e.totalCount??e.count??P.value.length):(P.value=[],h.value=0)}if(g&&""!==g.trim()){const e=a.getPropValue(r,g);"number"==typeof e&&e!==q.value&&(console.warn(`[useTableRequest] 后端返回页码(${e})与客户端页码(${q.value})不一致，已自动修正`),q.value=e)}p?.(P.value,r)}catch(t){if(e!==F)return;R.value=t instanceof Error?t:new Error(String(t)),d?.(R.value)}finally{e===F&&(w.value=!1)}}const C=i>0?a.useDebounceFn(z,i):z;return o&&(a.warnIfNotReactiveSource(o,"useTableRequest"),e.watch(()=>a.toValue(o),()=>{q.value=y,C()},{deep:!0})),r&&z(),{data:P,loading:w,error:R,pagination:j,run:async function(){await z()},onPageChange:async function(e){q.value=e,await z()},onSizeChange:async function(e){T.value=e,q.value=y,await z()}}};

package/dist/useTableRequest/index.es.js

@@ -0,0 +1 @@
+import{ref as e,computed as a,watch as t}from"vue";import{warnIfNotReactiveSource as n,toValue as l,useDebounceFn as u,getPropValue as i}from"../utils/utils.es.js";const o={};function r(e){Object.assign(o,e),e.pagination&&(o.pagination={...o.pagination,...e.pagination})}function s(){return{...o,pagination:{...o.pagination}}}function c(r,s={}){const c={...o.pagination,...s.pagination},{params:v,immediate:g=o.immediate??!0,debounceDelay:p=o.debounceDelay??0,dataField:f=o.dataField??"",totalField:m=o.totalField??"",currentPageField:d=o.currentPageField??"",transformParams:y,transformResult:b,onSuccess:S,onError:w}=s,{defaultPage:h=1,defaultPageSize:z=10,pageKey:F="page",pageSizeKey:P="pageSize"}=c,R=e([]),j=e(!1),A=e(null),T=e(h),q=e(z),C=e(0);let E=0;const D=a(()=>({page:T.value,pageSize:q.value,total:C.value}));async function K(){const e=++E;j.value=!0,A.value=null;try{const a=v?l(v):{},t={[F]:T.value,[P]:q.value};let n;n=y?y(a,{page:T.value,pageSize:q.value}):{...a,...t};const u=await r(n);if(e!==E)return;if(b){const e=b(u);e&&"object"==typeof e&&Array.isArray(e.list)?(R.value=e.list,C.value="number"==typeof e.total?e.total:e.list.length):(R.value=[],C.value=0,console.warn("[useTableRequest] transformResult 返回格式无法识别，请返回 { list: T[], total: number } 格式。"))}else{const e=u;Array.isArray(e)?(R.value=e,C.value=e.length):e&&"object"==typeof e?(f&&""!==f.trim()?R.value=i(e,f)||[]:R.value=e.list||e.data||e.records||e.items||[],m&&""!==m.trim()?C.value=i(e,m)??0:C.value=e.total??e.totalCount??e.count??R.value.length):(R.value=[],C.value=0)}if(d&&""!==d.trim()){const e=i(u,d);"number"==typeof e&&e!==T.value&&(console.warn(`[useTableRequest] 后端返回页码(${e})与客户端页码(${T.value})不一致，已自动修正`),T.value=e)}S?.(R.value,u)}catch(a){if(e!==E)return;A.value=a instanceof Error?a:new Error(String(a)),w?.(A.value)}finally{e===E&&(j.value=!1)}}const $=p>0?u(K,p):K;return v&&(n(v,"useTableRequest"),t(()=>l(v),()=>{T.value=h,$()},{deep:!0})),g&&K(),{data:R,loading:j,error:A,pagination:D,run:async function(){await K()},onPageChange:async function(e){T.value=e,await K()},onSizeChange:async function(e){q.value=e,T.value=h,await K()}}}export{s as getTableRequestGlobalConfig,r as setTableRequestGlobalConfig,c as useTableRequest};

package/dist/utils/utils.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("vue");function t(t){return"function"==typeof t||e.isRef(t)}exports.getPropValue=function(e,t){if(!e||!t)return;const o=t.replace(/\[(\d+)\]/g,".$1").split(".").filter(Boolean);let n=e;for(const r of o){if(null==n)return;n=n[r]}return n},exports.isReactiveSource=t,exports.toValue=function(t){return"function"==typeof t?t():e.unref(t)},exports.useDebounceFn=function(e,t){let o=null;return(...n)=>{o&&clearTimeout(o),o=setTimeout(()=>{e(...n),o=null},t)}},exports.warnIfNotReactiveSource=function(e,o){"undefined"!=typeof __DEV__&&__DEV__&&void 0!==e&&!t(e)&&console.warn(`[${o}] 检测到 params 是普通对象，参数变化将不会触发请求更新。\n请使用 computed() 或 getter 函数包装：`)};

package/dist/utils/utils.d.ts

@@ -1,6 +1,11 @@
 /**
  * 工具函数集合
  */
+import { type Ref, type ComputedRef } from 'vue';
+/** 可能是 Ref 或普通值 */
+export type MaybeRef<T> = T | Ref<T>;
+/** 可能是 Ref、ComputedRef 或普通值 */
+export type MaybeRefOrGetter<T> = MaybeRef<T> | ComputedRef<T> | (() => T);
 /**
  * 从对象中根据路径字符串获取值
  * 支持点号分隔的路径，如 'data.list' 或 'data.items[0].name'
@@ -17,4 +22,53 @@
  * ```
  */
 export declare function getPropValue(obj: any, path: string): any;
+/**
+ * 解包 MaybeRefOrGetter 类型的值
+ *
+ * @param source - 可能是 Ref、ComputedRef、getter 函数或普通值
+ * @returns 解包后的值
+ *
+ * @example
+ * ```ts
+ * const refVal = ref(1)
+ * toValue(refVal) // 1
+ * toValue(() => 2) // 2
+ * toValue(3) // 3
+ * ```
+ */
+export declare function toValue<T>(source: MaybeRefOrGetter<T>): T;
+/**
+ * 检测值是否为响应式来源（Ref、ComputedRef 或 getter 函数）
+ *
+ * @param source - 要检测的值
+ * @returns 是否为响应式来源
+ */
+export declare function isReactiveSource<T>(source: MaybeRefOrGetter<T>): boolean;
+/**
+ * 在开发环境下警告用户传入了非响应式参数
+ *
+ * @param source - 要检测的参数
+ * @param hookName - Hook 名称，用于警告提示
+ *
+ * @example
+ * ```ts
+ * warnIfNotReactiveSource(params, 'useTableRequest')
+ * ```
+ */
+export declare function warnIfNotReactiveSource<T>(source: MaybeRefOrGetter<T> | undefined, hookName: string): void;
+/**
+ * 创建防抖函数
+ *
+ * @param fn - 需要防抖的函数
+ * @param delay - 延迟时间（毫秒）
+ * @returns 防抖后的函数
+ *
+ * @example
+ * ```ts
+ * const debouncedFn = useDebounceFn(() => console.log('called'), 300)
+ * debouncedFn() // 300ms 后执行
+ * debouncedFn() // 重新计时
+ * ```
+ */
+export declare function useDebounceFn<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAoBxD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAgB,KAAK,GAAG,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAA;AAE9D,mBAAmB;AACnB,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;AAEpC,+BAA+B;AAC/B,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;AAE1E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAoBxD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAKzD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAExE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,EACvC,QAAQ,EAAE,MAAM,GACf,IAAI,CAYN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC7D,EAAE,EAAE,CAAC,EACL,KAAK,EAAE,MAAM,GACZ,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAYlC"}

package/dist/utils/utils.es.js

@@ -0,0 +1 @@
+import{unref as n,isRef as t}from"vue";function e(n,t){if(!n||!t)return;const e=t.replace(/\[(\d+)\]/g,".$1").split(".").filter(Boolean);let o=n;for(const r of e){if(null==o)return;o=o[r]}return o}function o(t){return"function"==typeof t?t():n(t)}function r(n){return"function"==typeof n||t(n)}function u(n,t){"undefined"!=typeof __DEV__&&__DEV__&&void 0!==n&&!r(n)&&console.warn(`[${t}] 检测到 params 是普通对象，参数变化将不会触发请求更新。\n请使用 computed() 或 getter 函数包装：`)}function f(n,t){let e=null;return(...o)=>{e&&clearTimeout(e),e=setTimeout(()=>{n(...o),e=null},t)}}export{e as getPropValue,r as isReactiveSource,o as toValue,f as useDebounceFn,u as warnIfNotReactiveSource};

package/dist/version.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e="1.0.5";exports.VERSION=e,exports.getVersion=function(){return e};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e="1.2.0";exports.VERSION=e,exports.getVersion=function(){return e};

package/dist/version.es.js

@@ -1 +1 @@
-const n="1.0.5";function t(){return n}export{n as VERSION,t as getVersion};
+const n="1.2.0";function t(){return n}export{n as VERSION,t as getVersion};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xn-fe-tools",
-  "version": "1.0.5",
+  "version": "1.2.0",
   "description": "A powerful fetch wrapper with chaining & tuple API",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -26,7 +26,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build && tsc --emitDeclarationOnly",
-    "build:docs": "vitepress build docs",
+    "build:docs": "vitepress build docs && node scripts/post-build-docs.js",
     "dev:docs": "vitepress dev docs",
     "preview:docs": "vitepress preview docs",
     "test": "vitest",
@@ -42,10 +42,9 @@
     "release:patch": "node scripts/release.js patch",
     "release:minor": "node scripts/release.js minor",
     "release:major": "node scripts/release.js major",
-    "addHook": "bash scripts/add-hook.sh",
-    "removeHook": "bash scripts/remove-hook.sh",
-    "prepublishOnly": "node scripts/prepublish.js",
-    "prepack": "pnpm build"
+    "addHook": "node scripts/add-hook.js",
+    "removeHook": "node scripts/remove-hook.js",
+    "prepublishOnly": "node scripts/prepublish.js"
   },
   "keywords": [
     "vue",
@@ -66,7 +65,9 @@
       "optional": true
     }
   },
-  "git-checks": false,
+  "gitHooks": {
+    "pre-commit": "npm test:run && npm type-check && npm build"
+  },
   "devDependencies": {
     "@vitejs/plugin-vue": "^5.2.1",
     "@vue/test-utils": "^2.4.6",