@fbkworks/data 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/create.mjs CHANGED
@@ -27,7 +27,9 @@ function createPageRequest(config) {
27
27
  try {
28
28
  raw = await fetch(query);
29
29
  } catch (err) {
30
- const aborted = err instanceof DOMException && err.name === "AbortError";
30
+ const canceledBySignal = query.signal?.aborted === true;
31
+ const cancelLike = typeof err === "object" && err !== null && (err.name === "AbortError" || err.name === "CanceledError" || err.code === "ERR_CANCELED");
32
+ const aborted = canceledBySignal || cancelLike;
31
33
  if (!aborted) {
32
34
  report({
33
35
  source: "request",
@@ -62,7 +64,7 @@ function createPageRequest(config) {
62
64
  });
63
65
  throw wrapped;
64
66
  }
65
- if (ok === false) {
67
+ if (!ok) {
66
68
  const text = message ?? "请求失败(未提供 errorMessage)";
67
69
  report({
68
70
  source: "request",
@@ -1 +1 @@
1
- {"version":3,"file":"create.mjs","sources":["../src/create.ts"],"sourcesContent":["import { warnOnce } from '@fbkworks/shared'\nimport { FbkDataError } from './error'\nimport { extractRows, extractTotal } from './path'\nimport type {\n CreatePageRequestConfig,\n Page,\n PageFetcher,\n PageQuery,\n PageRequestErrorEvent,\n} from './types'\n\n/**\n * 把「任意形状的后端响应」映射成组件库期望的 `Page<T>`。\n *\n * 这是 @fbkworks/data 的核心:业务方只写「字段在哪」,\n * 不写分页、不写错误处理、不写类型转换。\n *\n * ```ts\n * // ruoyi\n * export const fetchOrders = createPageRequest({\n * fetch: ({ page, pageSize, params, signal }) =>\n * http.get('/api/order/list', { params: { pageNum: page, pageSize, ...params }, signal }),\n * rows: 'rows',\n * total: 'total',\n * isSuccess: (res) => res.code === 200,\n * errorMessage: (res) => res.msg,\n * scope: 'server-filtered',\n * })\n * ```\n */\nexport function createPageRequest<TRaw, T = unknown>(\n config: CreatePageRequestConfig<TRaw, T>,\n): PageFetcher<T> {\n const { fetch, rows, total, mapRow, isSuccess, errorMessage, scope, onError, feature } = config\n\n /* 数据级权限提醒。\n 这不是运行时校验 —— 前端无法真正校验权限。它的价值在于\n 把「前端隐藏不构成权限」这件事,出现在写代码的那一刻。 */\n if (scope === 'client-filtered') {\n warnOnce(\n 'data-scope-client-filtered',\n '[fbk/data] scope 为 client-filtered:数据级权限必须由服务端过滤。\\n' +\n ' 前端隐藏不构成权限 —— 列表接口已返回全部数据,\\n' +\n ' 任何用户都能在浏览器 Network 面板看到完整内容。\\n' +\n ' 如果服务端确实做了过滤,请改为 scope: \"server-filtered\"。',\n )\n }\n\n /** 统一的错误上报。不上报 AbortError —— 取消不是错误 */\n const report = (event: PageRequestErrorEvent) => {\n if (!onError) return\n try {\n onError(event)\n } catch {\n /* 上报器自身抛错不能影响业务请求 */\n }\n }\n\n /** 参数快照:只留可复现所需的最小信息,避免大对象进日志 */\n const snapshot = (query: PageQuery): Record<string, unknown> => ({\n page: query.page,\n pageSize: query.pageSize,\n sort: query.sort,\n params: query.params,\n })\n\n return async (query) => {\n let raw: TRaw\n try {\n raw = await fetch(query)\n } catch (err) {\n /* 取消是正常流程(快速翻页时旧请求被 abort),\n 不能当成错误上报 —— 否则监控里全是噪音。 */\n const aborted = err instanceof DOMException && err.name === 'AbortError'\n if (!aborted) {\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n cause: err,\n context: snapshot(query),\n })\n }\n throw err\n }\n\n /* 业务码判定。\n 有业务码的后端(ruoyi 的 code===200)如果不传 isSuccess,\n 失败响应会被当成空列表 —— 用户看到「暂无数据」,\n 而真实原因是 token 过期或参数错误。 */\n /* isSuccess / errorMessage 是调用方给的函数,它们自己也可能抛错 ——\n 最常见的是空 body(raw 是 null/undefined)时读 `raw.code`。\n 这两行以前在 try 之外:异常直接冒成裸 TypeError,onError 一次都收不到,\n 等于「请求失败了但监控里什么都没有」。 */\n if (isSuccess) {\n let ok: boolean\n let message: string | undefined\n try {\n ok = isSuccess(raw)\n if (!ok) message = errorMessage?.(raw)\n } catch (err) {\n const reason = err instanceof Error ? err.message : String(err)\n const wrapped = new FbkDataError(\n 'business',\n `[fbk/data] isSuccess/errorMessage 判定抛错(${reason})。响应可能是空 body 或结构不符。`,\n raw,\n )\n report({\n source: 'request',\n feature,\n message: wrapped.message,\n cause: err,\n raw,\n context: snapshot(query),\n })\n throw wrapped\n }\n\n if (ok === false) {\n const text = message ?? '请求失败(未提供 errorMessage)'\n report({\n source: 'request',\n feature,\n message: text,\n raw,\n context: snapshot(query),\n })\n throw new FbkDataError('business', text, raw)\n }\n }\n\n try {\n const rawRows = extractRows(raw, rows)\n const totalValue = total !== undefined ? extractTotal(raw, total) : rawRows.length\n\n const list = mapRow\n ? rawRows.map((item, index) => mapRow(item, index))\n : (rawRows as unknown as T[])\n\n return { list, total: totalValue } satisfies Page<T>\n } catch (err) {\n /* 路径解析失败是**开发期错误**(字段名写错),\n 但线上同样会走到这里,所以也要上报。 */\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n raw,\n cause: err,\n context: snapshot(query),\n })\n throw err\n }\n }\n}\n"],"names":[],"mappings":";;;AA8BO,SAAS,kBACd,QACgB;AAChB,QAAM,EAAE,OAAO,MAAM,OAAO,QAAQ,WAAW,cAAc,OAAO,SAAS,QAAA,IAAY;AAKzF,MAAI,UAAU,mBAAmB;AAC/B;AAAA,MACE;AAAA,MACA;AAAA,IAAA;AAAA,EAKJ;AAGA,QAAM,SAAS,CAAC,UAAiC;AAC/C,QAAI,CAAC,QAAS;AACd,QAAI;AACF,cAAQ,KAAK;AAAA,IACf,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,WAAW,CAAC,WAA+C;AAAA,IAC/D,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,MAAM,MAAM;AAAA,IACZ,QAAQ,MAAM;AAAA,EAAA;AAGhB,SAAO,OAAO,UAAU;AACtB,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,KAAK;AAAA,IACzB,SAAS,KAAK;AAGZ,YAAM,UAAU,eAAe,gBAAgB,IAAI,SAAS;AAC5D,UAAI,CAAC,SAAS;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,UACxD,OAAO;AAAA,UACP,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AAAA,MACH;AACA,YAAM;AAAA,IACR;AAUA,QAAI,WAAW;AACb,UAAI;AACJ,UAAI;AACJ,UAAI;AACF,aAAK,UAAU,GAAG;AAClB,YAAI,CAAC,GAAI,WAAU,eAAe,GAAG;AAAA,MACvC,SAAS,KAAK;AACZ,cAAM,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC9D,cAAM,UAAU,IAAI;AAAA,UAClB;AAAA,UACA,0CAA0C,MAAM;AAAA,UAChD;AAAA,QAAA;AAEF,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS,QAAQ;AAAA,UACjB,OAAO;AAAA,UACP;AAAA,UACA,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AACD,cAAM;AAAA,MACR;AAEA,UAAI,OAAO,OAAO;AAChB,cAAM,OAAO,WAAW;AACxB,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS;AAAA,UACT;AAAA,UACA,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AACD,cAAM,IAAI,aAAa,YAAY,MAAM,GAAG;AAAA,MAC9C;AAAA,IACF;AAEA,QAAI;AACF,YAAM,UAAU,YAAY,KAAK,IAAI;AACrC,YAAM,aAAa,UAAU,SAAY,aAAa,KAAK,KAAK,IAAI,QAAQ;AAE5E,YAAM,OAAO,SACT,QAAQ,IAAI,CAAC,MAAM,UAAU,OAAO,MAAM,KAAK,CAAC,IAC/C;AAEL,aAAO,EAAE,MAAM,OAAO,WAAA;AAAA,IACxB,SAAS,KAAK;AAGZ,aAAO;AAAA,QACL,QAAQ;AAAA,QACR;AAAA,QACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,QACxD;AAAA,QACA,OAAO;AAAA,QACP,SAAS,SAAS,KAAK;AAAA,MAAA,CACxB;AACD,YAAM;AAAA,IACR;AAAA,EACF;AACF;"}
1
+ {"version":3,"file":"create.mjs","sources":["../src/create.ts"],"sourcesContent":["import { warnOnce } from '@fbkworks/shared'\nimport { FbkDataError } from './error'\nimport { extractRows, extractTotal } from './path'\nimport type {\n CreatePageRequestConfig,\n Page,\n PageFetcher,\n PageQuery,\n PageRequestErrorEvent,\n} from './types'\n\n/**\n * 把「任意形状的后端响应」映射成组件库期望的 `Page<T>`。\n *\n * 这是 @fbkworks/data 的核心:业务方只写「字段在哪」,\n * 不写分页、不写错误处理、不写类型转换。\n *\n * ```ts\n * // ruoyi\n * export const fetchOrders = createPageRequest({\n * fetch: ({ page, pageSize, params, signal }) =>\n * http.get('/api/order/list', { params: { pageNum: page, pageSize, ...params }, signal }),\n * rows: 'rows',\n * total: 'total',\n * isSuccess: (res) => res.code === 200,\n * errorMessage: (res) => res.msg,\n * scope: 'server-filtered',\n * })\n * ```\n */\nexport function createPageRequest<TRaw, T = unknown>(\n config: CreatePageRequestConfig<TRaw, T>,\n): PageFetcher<T> {\n const { fetch, rows, total, mapRow, isSuccess, errorMessage, scope, onError, feature } = config\n\n /* 数据级权限提醒。\n 这不是运行时校验 —— 前端无法真正校验权限。它的价值在于\n 把「前端隐藏不构成权限」这件事,出现在写代码的那一刻。 */\n if (scope === 'client-filtered') {\n warnOnce(\n 'data-scope-client-filtered',\n '[fbk/data] scope 为 client-filtered:数据级权限必须由服务端过滤。\\n' +\n ' 前端隐藏不构成权限 —— 列表接口已返回全部数据,\\n' +\n ' 任何用户都能在浏览器 Network 面板看到完整内容。\\n' +\n ' 如果服务端确实做了过滤,请改为 scope: \"server-filtered\"。',\n )\n }\n\n /** 统一的错误上报。不上报 AbortError —— 取消不是错误 */\n const report = (event: PageRequestErrorEvent) => {\n if (!onError) return\n try {\n onError(event)\n } catch {\n /* 上报器自身抛错不能影响业务请求 */\n }\n }\n\n /** 参数快照:只留可复现所需的最小信息,避免大对象进日志 */\n const snapshot = (query: PageQuery): Record<string, unknown> => ({\n page: query.page,\n pageSize: query.pageSize,\n sort: query.sort,\n params: query.params,\n })\n\n return async (query) => {\n let raw: TRaw\n try {\n raw = await fetch(query)\n } catch (err) {\n /* 取消是正常流程(快速翻页时旧请求被 abort),不能当成错误上报 —— 否则监控里全是噪音。\n 判据要覆盖三种真实形状:\n · fetch 原生取消 → DOMException('AbortError')\n · axios v1 signal 取消 → CanceledError(name='CanceledError', code='ERR_CANCELED')\n · abort(customReason) → 直接以 reason 拒约,形状任意\n 最后一种无法靠形状识别,所以**第一判据看 signal 本身**:调用方已经 abort 了,\n 那么无论抛出来的是什么,都不该算错误。 */\n const canceledBySignal = query.signal?.aborted === true\n const cancelLike =\n typeof err === 'object' &&\n err !== null &&\n ((err as { name?: string }).name === 'AbortError' ||\n (err as { name?: string }).name === 'CanceledError' ||\n (err as { code?: string }).code === 'ERR_CANCELED')\n const aborted = canceledBySignal || cancelLike\n if (!aborted) {\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n cause: err,\n context: snapshot(query),\n })\n }\n throw err\n }\n\n /* 业务码判定。\n 有业务码的后端(ruoyi 的 code===200)如果不传 isSuccess,\n 失败响应会被当成空列表 —— 用户看到「暂无数据」,\n 而真实原因是 token 过期或参数错误。 */\n /* isSuccess / errorMessage 是调用方给的函数,它们自己也可能抛错 ——\n 最常见的是空 body(raw 是 null/undefined)时读 `raw.code`。\n 这两行以前在 try 之外:异常直接冒成裸 TypeError,onError 一次都收不到,\n 等于「请求失败了但监控里什么都没有」。 */\n if (isSuccess) {\n let ok: boolean\n let message: string | undefined\n try {\n ok = isSuccess(raw)\n if (!ok) message = errorMessage?.(raw)\n } catch (err) {\n const reason = err instanceof Error ? err.message : String(err)\n const wrapped = new FbkDataError(\n 'business',\n `[fbk/data] isSuccess/errorMessage 判定抛错(${reason})。响应可能是空 body 或结构不符。`,\n raw,\n )\n report({\n source: 'request',\n feature,\n message: wrapped.message,\n cause: err,\n raw,\n context: snapshot(query),\n })\n throw wrapped\n }\n\n /* 判据必须是「falsy 即失败」,不能写 ok === false:\n `isSuccess: (res) => res.code`、`(res) => res.data?.ok`、`(res) => res.status`\n 这些写法返回的是 undefined / 0 / '' ,用 === false 会把业务失败全部放过 ——\n 失败响应带空数组时用户看到「暂无数据」,不带数组时报「列表位置不是数组」,\n 把排查引到字段名上。`!ok` 才是「不是成功」的意思。 */\n if (!ok) {\n const text = message ?? '请求失败(未提供 errorMessage)'\n report({\n source: 'request',\n feature,\n message: text,\n raw,\n context: snapshot(query),\n })\n throw new FbkDataError('business', text, raw)\n }\n }\n\n try {\n const rawRows = extractRows(raw, rows)\n const totalValue = total !== undefined ? extractTotal(raw, total) : rawRows.length\n\n const list = mapRow\n ? rawRows.map((item, index) => mapRow(item, index))\n : (rawRows as unknown as T[])\n\n return { list, total: totalValue } satisfies Page<T>\n } catch (err) {\n /* 路径解析失败是**开发期错误**(字段名写错),\n 但线上同样会走到这里,所以也要上报。 */\n report({\n source: 'request',\n feature,\n message: err instanceof Error ? err.message : String(err),\n raw,\n cause: err,\n context: snapshot(query),\n })\n throw err\n }\n }\n}\n"],"names":[],"mappings":";;;AA8BO,SAAS,kBACd,QACgB;AAChB,QAAM,EAAE,OAAO,MAAM,OAAO,QAAQ,WAAW,cAAc,OAAO,SAAS,QAAA,IAAY;AAKzF,MAAI,UAAU,mBAAmB;AAC/B;AAAA,MACE;AAAA,MACA;AAAA,IAAA;AAAA,EAKJ;AAGA,QAAM,SAAS,CAAC,UAAiC;AAC/C,QAAI,CAAC,QAAS;AACd,QAAI;AACF,cAAQ,KAAK;AAAA,IACf,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,WAAW,CAAC,WAA+C;AAAA,IAC/D,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,MAAM,MAAM;AAAA,IACZ,QAAQ,MAAM;AAAA,EAAA;AAGhB,SAAO,OAAO,UAAU;AACtB,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,KAAK;AAAA,IACzB,SAAS,KAAK;AAQZ,YAAM,mBAAmB,MAAM,QAAQ,YAAY;AACnD,YAAM,aACJ,OAAO,QAAQ,YACf,QAAQ,SACN,IAA0B,SAAS,gBAClC,IAA0B,SAAS,mBACnC,IAA0B,SAAS;AACxC,YAAM,UAAU,oBAAoB;AACpC,UAAI,CAAC,SAAS;AACZ,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,UACxD,OAAO;AAAA,UACP,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AAAA,MACH;AACA,YAAM;AAAA,IACR;AAUA,QAAI,WAAW;AACb,UAAI;AACJ,UAAI;AACJ,UAAI;AACF,aAAK,UAAU,GAAG;AAClB,YAAI,CAAC,GAAI,WAAU,eAAe,GAAG;AAAA,MACvC,SAAS,KAAK;AACZ,cAAM,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAC9D,cAAM,UAAU,IAAI;AAAA,UAClB;AAAA,UACA,0CAA0C,MAAM;AAAA,UAChD;AAAA,QAAA;AAEF,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS,QAAQ;AAAA,UACjB,OAAO;AAAA,UACP;AAAA,UACA,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AACD,cAAM;AAAA,MACR;AAOA,UAAI,CAAC,IAAI;AACP,cAAM,OAAO,WAAW;AACxB,eAAO;AAAA,UACL,QAAQ;AAAA,UACR;AAAA,UACA,SAAS;AAAA,UACT;AAAA,UACA,SAAS,SAAS,KAAK;AAAA,QAAA,CACxB;AACD,cAAM,IAAI,aAAa,YAAY,MAAM,GAAG;AAAA,MAC9C;AAAA,IACF;AAEA,QAAI;AACF,YAAM,UAAU,YAAY,KAAK,IAAI;AACrC,YAAM,aAAa,UAAU,SAAY,aAAa,KAAK,KAAK,IAAI,QAAQ;AAE5E,YAAM,OAAO,SACT,QAAQ,IAAI,CAAC,MAAM,UAAU,OAAO,MAAM,KAAK,CAAC,IAC/C;AAEL,aAAO,EAAE,MAAM,OAAO,WAAA;AAAA,IACxB,SAAS,KAAK;AAGZ,aAAO;AAAA,QACL,QAAQ;AAAA,QACR;AAAA,QACA,SAAS,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,QACxD;AAAA,QACA,OAAO;AAAA,QACP,SAAS,SAAS,KAAK;AAAA,MAAA,CACxB;AACD,YAAM;AAAA,IACR;AAAA,EACF;AACF;"}
package/dist/path.mjs CHANGED
@@ -67,6 +67,15 @@ function extractTotal(raw, spec) {
67
67
  );
68
68
  }
69
69
  const num = Number(value);
70
+ if (!Number.isInteger(num) || num < 0) {
71
+ throw new FbkDataError(
72
+ "path",
73
+ `[fbk/data] 总数必须是非负整数(实际是 ${previewRaw(value)})。
74
+ 小数请四舍五入后再返回,负数通常意味着后端聚合写错了。
75
+ 实际响应:${previewRaw(raw)}`,
76
+ raw
77
+ );
78
+ }
70
79
  if (!Number.isFinite(num)) {
71
80
  throw new FbkDataError(
72
81
  "path",
package/dist/path.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"path.mjs","sources":["../src/path.ts"],"sourcesContent":["import { FbkDataError, previewRaw } from './error'\n\n/**\n * 点号路径取值。\n *\n * 为什么需要它:真实后端的列表位置五花八门 ——\n * `rows`(ruoyi)、`data.records`(很多 Spring 项目)、\n * `data.list`、`result.items`……\n *\n * 业务方只需写一个字符串,不用写提取函数。\n *\n * **支持数组下标**:`data.list.0.items` 这类结构真实存在\n * (某些接口把列表包在数组里)。\n */\nexport function getByPath(raw: unknown, path: string): unknown {\n if (!path) return raw\n\n const segments = path.split('.')\n let current: unknown = raw\n\n for (const segment of segments) {\n if (current === null || current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:在第 \"${segment}\" 段时父级为 ${current}。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n if (typeof current !== 'object') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:第 \"${segment}\" 段无法从 ${typeof current} 上取属性。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n // 数组下标:'0' 这类纯数字段\n if (Array.isArray(current) && /^\\d+$/.test(segment)) {\n current = current[Number(segment)]\n } else {\n current = (current as Record<string, unknown>)[segment]\n }\n }\n\n if (current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析结果为 undefined。` +\n `多半是字段名写错了 —— 注意:静默返回空列表会让这类错误极难排查。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n return current\n}\n\n/**\n * 从响应里取列表。\n *\n * 路径解析失败时**抛错而不是返回空数组** ——\n * 返回空数组会让用户看到「暂无数据」,而真实原因是字段名写错。\n */\nexport function extractRows<TRaw>(raw: TRaw, spec: string | ((raw: TRaw) => unknown)): unknown[] {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (!Array.isArray(value)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 列表位置不是数组(实际是 ${typeof value})。实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return value\n}\n\n/**\n * 从响应里取总数。失败时抛错。\n *\n * **null / '' / undefined 必须抛错,不能当成 0。**\n *\n * `Number(null) === 0`、`Number('') === 0` —— 这是挖过的坑:\n * 后端返回 `total: null`(「暂无数据」或字段未初始化时很常见),\n * 契约层静默变成 total=0,分页器显示「共 0 条」,\n * 而实际可能有数据。用户看到的是错误信息,且没有任何报错。\n *\n * 宁可抛错让人发现,也不要静默显示错的分页。\n */\nexport function extractTotal<TRaw>(\n raw: TRaw,\n spec: string | ((raw: TRaw) => unknown),\n): number {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (value === null || value === undefined || value === '') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置是 ${value === '' ? '空字符串' : String(value)},不是有效数字。` +\n `\\n Number(null) === 0,如果静默转换,分页器会显示「共 0 条」但实际可能有数据。` +\n `\\n 如果后端确实没有总数,请改用 total: (raw) => rows.length 或直接不传 total。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n /* 只接受「数字」和「非空白的数字字符串」。\n 放开到 Number() 会让一整类非法值静默变成 0:\n Number(' ') === 0、Number([]) === 0、Number(false) === 0\n 而 0 会在分页器上显示「共 0 条」——和历史缺陷 total:null 完全同一种伪装。 */\n const isNumericString = typeof value === 'string' && value.trim() !== ''\n if (typeof value !== 'number' && !isNumericString) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数不是数字也不是数字字符串(实际是 ${previewRaw(value)})。` +\n `\\n Number() 对空数组、布尔值、纯空白字符串都会返回 0,静默转换会让分页器显示「共 0 条」。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n const num = Number(value)\n\n if (!Number.isFinite(num)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置不是有效数字(实际是 ${previewRaw(value)})。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return num\n}\n"],"names":[],"mappings":";AAcO,SAAS,UAAU,KAAc,MAAuB;AAC7D,MAAI,CAAC,KAAM,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,MAAI,UAAmB;AAEvB,aAAW,WAAW,UAAU;AAC9B,QAAI,YAAY,QAAQ,YAAY,QAAW;AAC7C,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,cAAc,OAAO,WAAW,OAAO,SACnD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,OAAO,YAAY,UAAU;AAC/B,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,aAAa,OAAO,UAAU,OAAO,OAAO,cACxD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAGA,QAAI,MAAM,QAAQ,OAAO,KAAK,QAAQ,KAAK,OAAO,GAAG;AACnD,gBAAU,QAAQ,OAAO,OAAO,CAAC;AAAA,IACnC,OAAO;AACL,gBAAW,QAAoC,OAAO;AAAA,IACxD;AAAA,EACF;AAEA,MAAI,YAAY,QAAW;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,kBAAkB,IAAI,4DAEZ,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAQO,SAAS,YAAkB,KAAW,MAAoD;AAC/F,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,2BAA2B,OAAO,KAAK,UAAU,WAAW,GAAG,CAAC;AAAA,MAChE;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;AAcO,SAAS,aACd,KACA,MACQ;AACR,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,UAAU,QAAQ,UAAU,UAAa,UAAU,IAAI;AACzD,UAAM,IAAI;AAAA,MACR;AAAA,MACA,oBAAoB,UAAU,KAAK,SAAS,OAAO,KAAK,CAAC;AAAA;AAAA;AAAA,SAG3C,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAMA,QAAM,kBAAkB,OAAO,UAAU,YAAY,MAAM,WAAW;AACtE,MAAI,OAAO,UAAU,YAAY,CAAC,iBAAiB;AACjD,UAAM,IAAI;AAAA,MACR;AAAA,MACA,iCAAiC,WAAW,KAAK,CAAC;AAAA;AAAA,SAEpC,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAEA,QAAM,MAAM,OAAO,KAAK;AAExB,MAAI,CAAC,OAAO,SAAS,GAAG,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,6BAA6B,WAAW,KAAK,CAAC,UACpC,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;"}
1
+ {"version":3,"file":"path.mjs","sources":["../src/path.ts"],"sourcesContent":["import { FbkDataError, previewRaw } from './error'\n\n/**\n * 点号路径取值。\n *\n * 为什么需要它:真实后端的列表位置五花八门 ——\n * `rows`(ruoyi)、`data.records`(很多 Spring 项目)、\n * `data.list`、`result.items`……\n *\n * 业务方只需写一个字符串,不用写提取函数。\n *\n * **支持数组下标**:`data.list.0.items` 这类结构真实存在\n * (某些接口把列表包在数组里)。\n */\nexport function getByPath(raw: unknown, path: string): unknown {\n if (!path) return raw\n\n const segments = path.split('.')\n let current: unknown = raw\n\n for (const segment of segments) {\n if (current === null || current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:在第 \"${segment}\" 段时父级为 ${current}。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n if (typeof current !== 'object') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析失败:第 \"${segment}\" 段无法从 ${typeof current} 上取属性。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n // 数组下标:'0' 这类纯数字段\n if (Array.isArray(current) && /^\\d+$/.test(segment)) {\n current = current[Number(segment)]\n } else {\n current = (current as Record<string, unknown>)[segment]\n }\n }\n\n if (current === undefined) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 路径 \"${path}\" 解析结果为 undefined。` +\n `多半是字段名写错了 —— 注意:静默返回空列表会让这类错误极难排查。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n return current\n}\n\n/**\n * 从响应里取列表。\n *\n * 路径解析失败时**抛错而不是返回空数组** ——\n * 返回空数组会让用户看到「暂无数据」,而真实原因是字段名写错。\n */\nexport function extractRows<TRaw>(raw: TRaw, spec: string | ((raw: TRaw) => unknown)): unknown[] {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (!Array.isArray(value)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 列表位置不是数组(实际是 ${typeof value})。实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return value\n}\n\n/**\n * 从响应里取总数。失败时抛错。\n *\n * **null / '' / undefined 必须抛错,不能当成 0。**\n *\n * `Number(null) === 0`、`Number('') === 0` —— 这是挖过的坑:\n * 后端返回 `total: null`(「暂无数据」或字段未初始化时很常见),\n * 契约层静默变成 total=0,分页器显示「共 0 条」,\n * 而实际可能有数据。用户看到的是错误信息,且没有任何报错。\n *\n * 宁可抛错让人发现,也不要静默显示错的分页。\n */\nexport function extractTotal<TRaw>(\n raw: TRaw,\n spec: string | ((raw: TRaw) => unknown),\n): number {\n const value = typeof spec === 'function' ? spec(raw) : getByPath(raw, spec)\n\n if (value === null || value === undefined || value === '') {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置是 ${value === '' ? '空字符串' : String(value)},不是有效数字。` +\n `\\n Number(null) === 0,如果静默转换,分页器会显示「共 0 条」但实际可能有数据。` +\n `\\n 如果后端确实没有总数,请改用 total: (raw) => rows.length 或直接不传 total。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n /* 只接受「数字」和「非空白的数字字符串」。\n 放开到 Number() 会让一整类非法值静默变成 0:\n Number(' ') === 0、Number([]) === 0、Number(false) === 0\n 而 0 会在分页器上显示「共 0 条」——和历史缺陷 total:null 完全同一种伪装。 */\n const isNumericString = typeof value === 'string' && value.trim() !== ''\n if (typeof value !== 'number' && !isNumericString) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数不是数字也不是数字字符串(实际是 ${previewRaw(value)})。` +\n `\\n Number() 对空数组、布尔值、纯空白字符串都会返回 0,静默转换会让分页器显示「共 0 条」。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n const num = Number(value)\n\n /* 非负整数。负数与小数同样会让分页器显示错数(「共 -5 条」「共 1.5 条」),\n 与 total:null 变成 0 是同一类伪装 —— 上面刚封了 null/空串/布尔/数组,这里一并封死。 */\n if (!Number.isInteger(num) || num < 0) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数必须是非负整数(实际是 ${previewRaw(value)})。` +\n `\\n 小数请四舍五入后再返回,负数通常意味着后端聚合写错了。` +\n `\\n 实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n\n if (!Number.isFinite(num)) {\n throw new FbkDataError(\n 'path',\n `[fbk/data] 总数位置不是有效数字(实际是 ${previewRaw(value)})。` +\n `实际响应:${previewRaw(raw)}`,\n raw,\n )\n }\n return num\n}\n"],"names":[],"mappings":";AAcO,SAAS,UAAU,KAAc,MAAuB;AAC7D,MAAI,CAAC,KAAM,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,MAAI,UAAmB;AAEvB,aAAW,WAAW,UAAU;AAC9B,QAAI,YAAY,QAAQ,YAAY,QAAW;AAC7C,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,cAAc,OAAO,WAAW,OAAO,SACnD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,OAAO,YAAY,UAAU;AAC/B,YAAM,IAAI;AAAA,QACR;AAAA,QACA,kBAAkB,IAAI,aAAa,OAAO,UAAU,OAAO,OAAO,cACxD,WAAW,GAAG,CAAC;AAAA,QACzB;AAAA,MAAA;AAAA,IAEJ;AAGA,QAAI,MAAM,QAAQ,OAAO,KAAK,QAAQ,KAAK,OAAO,GAAG;AACnD,gBAAU,QAAQ,OAAO,OAAO,CAAC;AAAA,IACnC,OAAO;AACL,gBAAW,QAAoC,OAAO;AAAA,IACxD;AAAA,EACF;AAEA,MAAI,YAAY,QAAW;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,kBAAkB,IAAI,4DAEZ,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAQO,SAAS,YAAkB,KAAW,MAAoD;AAC/F,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,2BAA2B,OAAO,KAAK,UAAU,WAAW,GAAG,CAAC;AAAA,MAChE;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;AAcO,SAAS,aACd,KACA,MACQ;AACR,QAAM,QAAQ,OAAO,SAAS,aAAa,KAAK,GAAG,IAAI,UAAU,KAAK,IAAI;AAE1E,MAAI,UAAU,QAAQ,UAAU,UAAa,UAAU,IAAI;AACzD,UAAM,IAAI;AAAA,MACR;AAAA,MACA,oBAAoB,UAAU,KAAK,SAAS,OAAO,KAAK,CAAC;AAAA;AAAA;AAAA,SAG3C,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAMA,QAAM,kBAAkB,OAAO,UAAU,YAAY,MAAM,WAAW;AACtE,MAAI,OAAO,UAAU,YAAY,CAAC,iBAAiB;AACjD,UAAM,IAAI;AAAA,MACR;AAAA,MACA,iCAAiC,WAAW,KAAK,CAAC;AAAA;AAAA,SAEpC,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAEA,QAAM,MAAM,OAAO,KAAK;AAIxB,MAAI,CAAC,OAAO,UAAU,GAAG,KAAK,MAAM,GAAG;AACrC,UAAM,IAAI;AAAA,MACR;AAAA,MACA,4BAA4B,WAAW,KAAK,CAAC;AAAA;AAAA,SAE/B,WAAW,GAAG,CAAC;AAAA,MAC7B;AAAA,IAAA;AAAA,EAEJ;AAEA,MAAI,CAAC,OAAO,SAAS,GAAG,GAAG;AACzB,UAAM,IAAI;AAAA,MACR;AAAA,MACA,6BAA6B,WAAW,KAAK,CAAC,UACpC,WAAW,GAAG,CAAC;AAAA,MACzB;AAAA,IAAA;AAAA,EAEJ;AACA,SAAO;AACT;"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fbkworks/data",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "files": [