@servora/proto-utils 0.0.1

package/dist/query.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @servora/proto-utils — Proto/Kratos API 查询工具
+ *
+ * Kratos gRPC-gateway 的 ListRequest 约定：
+ *   filter   = JSON 序列化的过滤条件对象，空值字段会被省略
+ *   order_by = JSON 序列化的排序字段数组，前缀 "-" 表示降序
+ *   update_mask = 逗号分隔的字段名，用于 Proto FieldMask 部分更新
+ *
+ * 所有函数均返回新值，不修改入参。
+ */
+/**
+ * 将过滤条件序列化为 Kratos ListRequest.filter 字符串。
+ *
+ * - null/undefined 入参返回 undefined（不传 filter 参数）
+ * - 自动过滤空值字段（null、undefined、空字符串）
+ * - 过滤后为空对象时返回 undefined
+ *
+ * @example
+ * makeFilter({ name: 'foo', status: null })
+ * // → '{"name":"foo"}'
+ *
+ * makeFilter({})
+ * // → undefined
+ */
+export declare function makeFilter(fields?: null | Record<string, unknown>): string | undefined;
+/**
+ * 将排序字段序列化为 Kratos ListRequest.order_by 字符串。
+ *
+ * - 前缀 "-" 表示降序，无前缀表示升序
+ * - 默认按 "-created_at" 降序（当入参为 null/undefined 时）
+ * - 空数组时返回 undefined
+ *
+ * @example
+ * makeOrderBy(['-created_at', 'name'])
+ * // → '["-created_at","name"]'
+ *
+ * makeOrderBy()
+ * // → '["-created_at"]'
+ */
+export declare function makeOrderBy(fields?: null | string[]): string | undefined;
+/**
+ * 生成 Proto FieldMask 字符串，用于 UpdateRequest.update_mask。
+ *
+ * - 自动包含 "id" 字段（Proto UpdateRequest 的标准约定）
+ * - 去重，保持传入顺序，id 追加到末尾
+ * - 不修改入参数组
+ *
+ * @example
+ * makeUpdateMask(['name', 'avatar'])
+ * // → 'name,avatar,id'
+ *
+ * makeUpdateMask(['name', 'id', 'avatar'])
+ * // → 'name,avatar,id'  （id 不重复出现）
+ */
+export declare function makeUpdateMask(fields: string[]): string;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAIxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAGvD"}

package/dist/query.js

@@ -0,0 +1,75 @@
+/**
+ * @servora/proto-utils — Proto/Kratos API 查询工具
+ *
+ * Kratos gRPC-gateway 的 ListRequest 约定：
+ *   filter   = JSON 序列化的过滤条件对象，空值字段会被省略
+ *   order_by = JSON 序列化的排序字段数组，前缀 "-" 表示降序
+ *   update_mask = 逗号分隔的字段名，用于 Proto FieldMask 部分更新
+ *
+ * 所有函数均返回新值，不修改入参。
+ */
+/** 过滤掉 null、undefined、空字符串的字段 */
+function omitEmpty(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== null && v !== undefined && v !== ''));
+}
+/**
+ * 将过滤条件序列化为 Kratos ListRequest.filter 字符串。
+ *
+ * - null/undefined 入参返回 undefined（不传 filter 参数）
+ * - 自动过滤空值字段（null、undefined、空字符串）
+ * - 过滤后为空对象时返回 undefined
+ *
+ * @example
+ * makeFilter({ name: 'foo', status: null })
+ * // → '{"name":"foo"}'
+ *
+ * makeFilter({})
+ * // → undefined
+ */
+export function makeFilter(fields) {
+    if (fields == null)
+        return undefined;
+    const cleaned = omitEmpty(fields);
+    if (Object.keys(cleaned).length === 0)
+        return undefined;
+    return JSON.stringify(cleaned);
+}
+/**
+ * 将排序字段序列化为 Kratos ListRequest.order_by 字符串。
+ *
+ * - 前缀 "-" 表示降序，无前缀表示升序
+ * - 默认按 "-created_at" 降序（当入参为 null/undefined 时）
+ * - 空数组时返回 undefined
+ *
+ * @example
+ * makeOrderBy(['-created_at', 'name'])
+ * // → '["-created_at","name"]'
+ *
+ * makeOrderBy()
+ * // → '["-created_at"]'
+ */
+export function makeOrderBy(fields) {
+    const resolved = fields ?? ['-created_at'];
+    if (resolved.length === 0)
+        return undefined;
+    return JSON.stringify(resolved);
+}
+/**
+ * 生成 Proto FieldMask 字符串，用于 UpdateRequest.update_mask。
+ *
+ * - 自动包含 "id" 字段（Proto UpdateRequest 的标准约定）
+ * - 去重，保持传入顺序，id 追加到末尾
+ * - 不修改入参数组
+ *
+ * @example
+ * makeUpdateMask(['name', 'avatar'])
+ * // → 'name,avatar,id'
+ *
+ * makeUpdateMask(['name', 'id', 'avatar'])
+ * // → 'name,avatar,id'  （id 不重复出现）
+ */
+export function makeUpdateMask(fields) {
+    const without = fields.filter((f) => f !== 'id');
+    return [...without, 'id'].join(',');
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iCAAiC;AACjC,SAAS,SAAS,CAAC,GAA4B;IAC7C,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CACxB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CACrD,CACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CACxB,MAAuC;IAEvC,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,SAAS,CAAA;IACpC,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAA;IACjC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,CAAA;IAC1C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAC3C,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,MAAgB;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAA;IAChD,OAAO,CAAC,GAAG,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACrC,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@servora/proto-utils",
+    "version": "0.0.1",
+    "description": "Proto/Kratos API 查询工具：filter 序列化、order_by 编码、FieldMask 生成",
+    "type": "module",
+    "exports": {
+        "./query": {
+            "types": "./dist/query.d.ts",
+            "import": "./dist/query.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "!src/**/*_test.ts"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "clean": "rm -rf dist",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Servora-Kit/servora-web.git",
+        "directory": "packages/proto-utils"
+    },
+    "homepage": "https://github.com/Servora-Kit/servora-web/tree/main/packages/proto-utils",
+    "bugs": {
+        "url": "https://github.com/Servora-Kit/servora-web/issues"
+    },
+    "license": "MIT",
+    "sideEffects": false,
+    "devDependencies": {
+        "typescript": "^5.7.2"
+    }
+}

package/src/query.ts

@@ -0,0 +1,81 @@
+/**
+ * @servora/proto-utils — Proto/Kratos API 查询工具
+ *
+ * Kratos gRPC-gateway 的 ListRequest 约定：
+ *   filter   = JSON 序列化的过滤条件对象，空值字段会被省略
+ *   order_by = JSON 序列化的排序字段数组，前缀 "-" 表示降序
+ *   update_mask = 逗号分隔的字段名，用于 Proto FieldMask 部分更新
+ *
+ * 所有函数均返回新值，不修改入参。
+ */
+
+/** 过滤掉 null、undefined、空字符串的字段 */
+function omitEmpty(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(
+      ([, v]) => v !== null && v !== undefined && v !== '',
+    ),
+  )
+}
+
+/**
+ * 将过滤条件序列化为 Kratos ListRequest.filter 字符串。
+ *
+ * - null/undefined 入参返回 undefined（不传 filter 参数）
+ * - 自动过滤空值字段（null、undefined、空字符串）
+ * - 过滤后为空对象时返回 undefined
+ *
+ * @example
+ * makeFilter({ name: 'foo', status: null })
+ * // → '{"name":"foo"}'
+ *
+ * makeFilter({})
+ * // → undefined
+ */
+export function makeFilter(
+  fields?: null | Record<string, unknown>,
+): string | undefined {
+  if (fields == null) return undefined
+  const cleaned = omitEmpty(fields)
+  if (Object.keys(cleaned).length === 0) return undefined
+  return JSON.stringify(cleaned)
+}
+
+/**
+ * 将排序字段序列化为 Kratos ListRequest.order_by 字符串。
+ *
+ * - 前缀 "-" 表示降序，无前缀表示升序
+ * - 默认按 "-created_at" 降序（当入参为 null/undefined 时）
+ * - 空数组时返回 undefined
+ *
+ * @example
+ * makeOrderBy(['-created_at', 'name'])
+ * // → '["-created_at","name"]'
+ *
+ * makeOrderBy()
+ * // → '["-created_at"]'
+ */
+export function makeOrderBy(fields?: null | string[]): string | undefined {
+  const resolved = fields ?? ['-created_at']
+  if (resolved.length === 0) return undefined
+  return JSON.stringify(resolved)
+}
+
+/**
+ * 生成 Proto FieldMask 字符串，用于 UpdateRequest.update_mask。
+ *
+ * - 自动包含 "id" 字段（Proto UpdateRequest 的标准约定）
+ * - 去重，保持传入顺序，id 追加到末尾
+ * - 不修改入参数组
+ *
+ * @example
+ * makeUpdateMask(['name', 'avatar'])
+ * // → 'name,avatar,id'
+ *
+ * makeUpdateMask(['name', 'id', 'avatar'])
+ * // → 'name,avatar,id'  （id 不重复出现）
+ */
+export function makeUpdateMask(fields: string[]): string {
+  const without = fields.filter((f) => f !== 'id')
+  return [...without, 'id'].join(',')
+}