@ai0x0/utils 0.6.0 → 0.7.0

package/lib/backend/actions/paging.js

@@ -0,0 +1,50 @@
+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/paging.ts
+var paging_exports = {};
+__export(paging_exports, {
+  DEFAULT_PAGE_SIZE: () => DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE: () => MAX_PAGE_SIZE,
+  normalizePaging: () => normalizePaging
+});
+module.exports = __toCommonJS(paging_exports);
+var MAX_PAGE_SIZE = 1e4;
+var DEFAULT_PAGE_SIZE = 10;
+function toPositiveInt(value, fallback) {
+  const parsed = Math.floor(Number(value));
+  return Number.isFinite(parsed) && parsed >= 1 ? parsed : fallback;
+}
+function normalizePaging({
+  current,
+  pageSize
+}) {
+  return {
+    current: toPositiveInt(current, 1),
+    pageSize: Math.min(
+      toPositiveInt(pageSize, DEFAULT_PAGE_SIZE),
+      MAX_PAGE_SIZE
+    )
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_PAGE_SIZE,
+  MAX_PAGE_SIZE,
+  normalizePaging
+});

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<(("current" | "pageSize" | "orderBy" | "orderDir" | "creatorId" | "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]: (("current" | "pageSize" | "orderBy" | "orderDir" | "creatorId" | "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. Capped at 10000; compare `total` against what you received to tell whether more remain."
+  ),
+  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
+});