@ai0x0/utils 0.6.0 → 0.6.1

package/lib/backend/actions/get-list-query.js

@@ -6,11 +6,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc2) => {
+var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc2 = __getOwnPropDesc(from, key)) || desc2.enumerable });
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
   }
   return to;
 };
@@ -23,145 +23,20 @@ __export(get_list_query_exports, {
 });
 module.exports = __toCommonJS(get_list_query_exports);
 var import_drizzle_orm = require("drizzle-orm");
-var import_scope = require("../scope");
-function getListQuery({
-  db,
-  fields,
-  jsonArrayFields,
-  params,
-  relations,
-  scope,
-  table
-}) {
-  const {
-    page = 1,
-    pageSize = 10,
-    orderBy = "createdAt",
-    orderDir = "desc",
-    ...filters
-  } = params;
-  function buildBaseQuery(table2, fields2, relations2) {
-    let queryFields = { ...fields2 };
-    if (relations2 == null ? void 0 : relations2.length) {
-      for (const { select } of relations2) {
-        queryFields = { ...queryFields, ...select };
-      }
-    }
-    const query2 = db.select(queryFields).from(table2);
-    if (relations2 == null ? void 0 : relations2.length) {
-      query2.groupBy(
-        table2.id,
-        ...relations2.filter(({ groupBy }) => groupBy).filter(({ table: table3 }) => table3).map(({ table: table3 }) => table3.id)
-      );
-    }
-    return query2;
-  }
-  function findTargetColumn(key, table2, relations2) {
-    var _a;
-    return (_a = [table2].concat(
-      (relations2 == null ? void 0 : relations2.filter(({ table: table3 }) => table3).map(({ table: table3 }) => table3)) || []
-    ).find((table3) => table3[key])) == null ? void 0 : _a[key];
-  }
-  function addCondition(conditions2, key, value, targetColumn) {
-    const isIdField = /id/i.test(key);
-    const isJsonArray = jsonArrayFields == null ? void 0 : jsonArrayFields.includes(key);
-    if (typeof value === "string") {
-      if (value.includes(",")) {
-        const values = value.split(",").map((val) => val.trim()).filter(Boolean);
-        if (values.length > 0) {
-          if (isJsonArray) {
-            conditions2.push(
-              import_drizzle_orm.sql`
-                EXISTS (
-                  SELECT 1 FROM jsonb_array_elements_text(${targetColumn}) tag
-                  WHERE tag LIKE ${`%${values[0]}%`}
-                )
-              `
-            );
-          } else if (isIdField) {
-            conditions2.push((0, import_drizzle_orm.inArray)(targetColumn, values));
-          } else {
-            conditions2.push(
-              (0, import_drizzle_orm.or)(
-                ...values.map((val) => (0, import_drizzle_orm.ilike)(targetColumn, `%${val}%`))
-              )
-            );
-          }
-        }
-      } else {
-        if (isJsonArray) {
-          conditions2.push(
-            import_drizzle_orm.sql`
-              EXISTS (
-                SELECT 1 FROM jsonb_array_elements_text(${targetColumn}) tag
-                WHERE tag LIKE ${`%${value}%`}
-              )
-            `
-          );
-        } else if (isIdField) {
-          conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
-        } else {
-          conditions2.push((0, import_drizzle_orm.ilike)(targetColumn, `%${value}%`));
-        }
-      }
-    } else {
-      conditions2.push((0, import_drizzle_orm.eq)(targetColumn, value));
-    }
-  }
-  function buildConditions(filters2, table2, relations2) {
-    const conditions2 = [];
-    for (const [key, value] of Object.entries(filters2)) {
-      if (!value) {
-        continue;
-      }
-      if (key.endsWith("AtFrom") || key.endsWith("AtTo")) {
-        const baseFieldName = key.replace(/(AtFrom|AtTo)$/, "");
-        const targetColumn2 = findTargetColumn(
-          `${baseFieldName}At`,
-          table2,
-          relations2
-        );
-        if (!targetColumn2) {
-          continue;
-        }
-        if (key.endsWith("AtFrom")) {
-          conditions2.push((0, import_drizzle_orm.gte)(targetColumn2, new Date(value)));
-        } else if (key.endsWith("AtTo")) {
-          conditions2.push((0, import_drizzle_orm.lte)(targetColumn2, new Date(value)));
-        }
-        continue;
-      }
-      const targetColumn = findTargetColumn(
-        key,
-        table2,
-        relations2
-      );
-      if (!targetColumn) {
-        continue;
-      }
-      addCondition(conditions2, key, value, targetColumn);
-    }
-    return conditions2;
-  }
-  function buildOrderBy(table2, orderBy2, orderDir2) {
-    const orderColumn = table2[orderBy2];
-    return orderDir2 === "asc" ? (0, import_drizzle_orm.asc)(orderColumn) : (0, import_drizzle_orm.desc)(orderColumn);
-  }
-  const baseQuery = buildBaseQuery(table, fields, relations);
-  const scopeSql = (0, import_scope.scopeCondition)(table, scope);
-  const conditions = scopeSql ? [scopeSql] : [];
-  conditions.push(...buildConditions(filters, table, relations));
-  const query = baseQuery.where(conditions.length > 0 ? (0, import_drizzle_orm.and)(...conditions) : void 0).orderBy(buildOrderBy(table, orderBy, orderDir)).limit(pageSize).offset((page - 1) * pageSize);
-  const countQuery = db.select({ count: import_drizzle_orm.sql`COUNT(DISTINCT ${table.id})` }).from(table).where(conditions.length > 0 ? (0, import_drizzle_orm.and)(...conditions) : void 0);
-  if (relations == null ? void 0 : relations.length) {
-    for (const { table: relationTable, sql: joinSql } of relations) {
-      if (relationTable) {
-        query.leftJoin(relationTable, joinSql);
-        countQuery.leftJoin(relationTable, joinSql);
-      }
-    }
-  }
-  return { countQuery, query };
+var import_get_list_query_core = require("./get-list-query-core");
+var run = (0, import_get_list_query_core.createGetListQuery)({
+  contains: (column, keyword) => (0, import_drizzle_orm.ilike)(column, `%${keyword}%`),
+  // jsonb 数组展开成行再逐个 LIKE。列存的是 text[] 形状的 jsonb（见 createTableSchema 的
+  // jsonArrayFields），所以用 _text 那个变体，取到的 tag 直接就是字符串。
+  jsonArrayContains: (column, keyword) => import_drizzle_orm.sql`
+    EXISTS (
+      SELECT 1 FROM jsonb_array_elements_text(${column}) tag
+      WHERE tag LIKE ${`%${keyword}%`}
+    )
+  `
+});
+function getListQuery(args) {
+  return run(args);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/lib/backend/actions/write-action-core.d.ts

@@ -0,0 +1,18 @@
+import { ScopeArg } from "../scope.js";
+/** 核心用得到表的哪一部分：只有 id。dialect 各自的 Table 类型不进来。 */
+export interface WriteActionTable {
+    id: unknown;
+}
+interface WriteActionDeps<TTable extends WriteActionTable> {
+    db: any;
+    table: TTable;
+}
+export declare function createPutActionCore<TTable extends WriteActionTable>({ db, table, }: WriteActionDeps<TTable>): (body: Record<string, unknown>, { scope }: {
+    scope: ScopeArg;
+}) => Promise<unknown>;
+export declare function createDeleteActionCore<TTable extends WriteActionTable>({ db, table, }: WriteActionDeps<TTable>): ({ id }: {
+    id: string;
+}, { scope }: {
+    scope: ScopeArg;
+}) => Promise<any>;
+export {};

package/lib/backend/actions/write-action-core.js

@@ -0,0 +1,70 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/actions/write-action-core.ts
+var write_action_core_exports = {};
+__export(write_action_core_exports, {
+  createDeleteActionCore: () => createDeleteActionCore,
+  createPutActionCore: () => createPutActionCore
+});
+module.exports = __toCommonJS(write_action_core_exports);
+var import_drizzle_orm = require("drizzle-orm");
+var import_scope = require("../scope");
+var import_errors = require("../errors");
+var import_transform_body = require("./transform-body");
+function byId(table, id, scope) {
+  const guard = (0, import_scope.scopeCondition)(table, scope);
+  const same = (0, import_drizzle_orm.eq)(table.id, id);
+  return guard ? (0, import_drizzle_orm.and)(same, guard) : same;
+}
+function createPutActionCore({
+  db,
+  table
+}) {
+  return async (body, { scope }) => {
+    const id = body.id;
+    if (!id) {
+      throw new import_errors.HttpError(400, "缺少 id");
+    }
+    const [data] = await db.update(table).set((0, import_transform_body.transformBody)(body)).where(byId(table, id, scope)).returning();
+    if (!data && scope !== import_scope.NO_SCOPE) {
+      throw new import_errors.HttpError(404, "未找到编辑对象，或没有权限");
+    }
+    return data;
+  };
+}
+function createDeleteActionCore({
+  db,
+  table
+}) {
+  return async ({ id }, { scope }) => {
+    if (!id) {
+      throw new import_errors.HttpError(400, "缺少 id");
+    }
+    const rows = await db.delete(table).where(byId(table, id, scope)).returning();
+    if (rows.length === 0 && scope !== import_scope.NO_SCOPE) {
+      throw new import_errors.HttpError(404, "未找到删除对象，或没有权限");
+    }
+    return rows;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDeleteActionCore,
+  createPutActionCore
+});

package/lib/backend/schemas/common.d.ts

@@ -0,0 +1,112 @@
+import { z } from "zod";
+/**
+ * 业务侧 insert schema 需要从 drizzle-zod 生成的 schema 中排除的基础字段。
+ * 这些字段由后端在 createPostAction 中自动写入。
+ *
+ * 使用方式（在业务 schema 中）：
+ *   const insertFooSchema = createInsertSchema(foos)
+ *     .omit(BASIC_INSERT_OMIT)
+ *     .extend({ ... });
+ *
+ * 说明：上游导出为 const 而不是 helper function，是为了避免经过泛型
+ * wrapper 后 TS 把 drizzle-zod 推导出的深层条件 Shape 归约成 Omit，
+ * 从而在下游 `.extend(...)` 时丢失原有字段类型。
+ */
+export declare const BASIC_INSERT_OMIT: {
+    readonly id: true;
+    readonly creatorId: true;
+    readonly editorId: true;
+    readonly accessedAt: true;
+    readonly createdAt: true;
+    readonly updatedAt: true;
+};
+/**
+ * 业务侧 update schema 需要从 drizzle-zod 生成的 schema 中排除的基础字段。
+ * update 保留 id（随后用 `.required({ id: true })` 变成必填），其余由
+ * 后端 createPutAction 自动维护。
+ */
+export declare const BASIC_UPDATE_OMIT: {
+    readonly creatorId: true;
+    readonly editorId: true;
+    readonly accessedAt: true;
+    readonly createdAt: true;
+    readonly updatedAt: true;
+};
+export declare const queryListSchema: <Incoming extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: Incoming) => z.ZodObject<(("orderBy" | "orderDir" | "pageSize" | "creatorId" | "current" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} & Incoming["shape"] : ({
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof Incoming["shape"] ? never : K]: {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}[K]; } : never) & (Incoming["shape"] extends infer T_2 extends z.core.util.SomeObject ? { [K_1 in keyof T_2]: Incoming["shape"][K_1]; } : never)) extends infer T ? { [k in keyof T]: (("orderBy" | "orderDir" | "pageSize" | "creatorId" | "current" | "createdAtFrom" | "createdAtTo") & keyof Incoming["shape"] extends never ? {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} & Incoming["shape"] : ({
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+} extends infer T_1 extends z.core.util.SomeObject ? { [K in keyof T_1 as K extends keyof Incoming["shape"] ? never : K]: {
+    current: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pageSize: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    createdAtFrom: z.ZodOptional<z.ZodString>;
+    createdAtTo: z.ZodOptional<z.ZodString>;
+    orderBy: z.ZodOptional<z.ZodString>;
+    creatorId: z.ZodOptional<z.ZodString>;
+    orderDir: z.ZodOptional<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}[K]; } : never) & (Incoming["shape"] extends infer T_2 extends z.core.util.SomeObject ? { [K_1 in keyof T_2]: Incoming["shape"][K_1]; } : never))[k]; } : never, Incoming["_zod"]["config"]>;
+export declare const listBodySchema: <T extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>(schema: T) => z.ZodObject<{
+    total: z.ZodNumber;
+    data: z.ZodArray<T>;
+}, z.core.$strip>;
+/**
+ * 给 schema 上已有的字段挂说明。字段不在这个 schema 里就跳过 —— 同一张表的
+ * insert / update / select 三份含的列不一样（basicFields 只在 select 里），一份说明表要能同时
+ * 喂给三者，就不能对「字段一定存在」有要求。**不给不存在的字段凭空造一个。**
+ */
+export declare const describeFields: <T extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: T, notes: Record<string, string>) => T;
+export declare const describeBasicFields: <T extends z.ZodObject<z.core.$ZodLooseShape, z.core.$strip>>(schema: T) => T;

package/lib/backend/schemas/common.js

@@ -0,0 +1,112 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/backend/schemas/common.ts
+var common_exports = {};
+__export(common_exports, {
+  BASIC_INSERT_OMIT: () => BASIC_INSERT_OMIT,
+  BASIC_UPDATE_OMIT: () => BASIC_UPDATE_OMIT,
+  describeBasicFields: () => describeBasicFields,
+  describeFields: () => describeFields,
+  listBodySchema: () => listBodySchema,
+  queryListSchema: () => queryListSchema
+});
+module.exports = __toCommonJS(common_exports);
+var import_zod = require("zod");
+var BASIC_INSERT_OMIT = {
+  id: true,
+  creatorId: true,
+  editorId: true,
+  accessedAt: true,
+  createdAt: true,
+  updatedAt: true
+};
+var BASIC_UPDATE_OMIT = {
+  creatorId: true,
+  editorId: true,
+  accessedAt: true,
+  createdAt: true,
+  updatedAt: true
+};
+var queryListSchema = (schema) => import_zod.z.object({
+  current: import_zod.z.string().optional().default("1").describe("Page number, starting at 1."),
+  pageSize: import_zod.z.string().optional().default("10").describe(
+    "Rows per page. Omitting it yields only 10 — pass a larger value to get the whole set."
+  ),
+  createdAtFrom: import_zod.z.string().optional().describe(
+    "Keep only rows created at or after this instant (ISO 8601, e.g. 2026-08-01T00:00:00Z)."
+  ),
+  createdAtTo: import_zod.z.string().optional().describe("Keep only rows created at or before this instant."),
+  orderBy: import_zod.z.string().optional().describe(
+    "Column to sort by — a column name of this resource (createdAt / updatedAt and the like)."
+  ),
+  creatorId: import_zod.z.string().optional().describe(
+    "Keep only rows created by this user. Useful in shared spaces to filter down to one member."
+  ),
+  orderDir: import_zod.z.enum(["asc", "desc"]).optional().describe("Sort ascending or descending.")
+}).merge(schema);
+var listBodySchema = (schema) => import_zod.z.object({
+  total: import_zod.z.number().describe(
+    "Total number of rows matching the filters — not the length of `data`. Use it to decide whether another page exists."
+  ),
+  data: import_zod.z.array(schema).describe("This page's rows.")
+});
+var BASIC_FIELD_NOTES = {
+  creatorId: "User id of the creator. Stamped by the server; clients cannot send it.",
+  editorId: "User id of whoever changed this row last. Stamped by the server; clients cannot send it.",
+  id: "Primary key of this row (uuid)."
+};
+var BASIC_TIMESTAMP_NOTES = {
+  accessedAt: "When this row was last accessed.",
+  createdAt: "When this row was created.",
+  updatedAt: "When this row was last modified."
+};
+var describeFields = (schema, notes) => {
+  const overlay = {};
+  for (const [field, note] of Object.entries(notes)) {
+    const existing = schema.shape[field];
+    if (existing) {
+      overlay[field] = existing.describe(note);
+    }
+  }
+  return Object.keys(overlay).length ? schema.extend(overlay) : schema;
+};
+var describeBasicFields = (schema) => {
+  const withNotes = describeFields(schema, BASIC_FIELD_NOTES);
+  const overlay = {};
+  for (const [field, note] of Object.entries(BASIC_TIMESTAMP_NOTES)) {
+    const existing = withNotes.shape[field];
+    if (existing) {
+      overlay[field] = existing.meta({
+        description: note,
+        format: "date-time",
+        type: "string"
+      });
+    }
+  }
+  return Object.keys(overlay).length ? withNotes.extend(overlay) : withNotes;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BASIC_INSERT_OMIT,
+  BASIC_UPDATE_OMIT,
+  describeBasicFields,
+  describeFields,
+  listBodySchema,
+  queryListSchema
+});