@palbase/backend 33.0.2 → 34.1.0

package/dist/db/index.cjs

@@ -27,11 +27,14 @@ __export(db_exports, {
   TABLE_META: () => TABLE_META,
   TxPlanError: () => TxPlanError,
   TxRefError: () => TxRefError,
+  assertQueryManifest: () => assertQueryManifest,
   bigint: () => bigint,
   boolean: () => boolean,
   dec: () => dec,
+  defineQuery: () => defineQuery,
   defineSchema: () => defineSchema,
   defineTable: () => defineTable,
+  defineWorkload: () => defineWorkload,
   enumType: () => enumType,
   inc: () => inc,
   installationRef: () => installationRef,
@@ -43,6 +46,7 @@ __export(db_exports, {
   openai: () => openai,
   ownedByUser: () => ownedByUser,
   policy: () => policy,
+  queryManifest: () => queryManifest,
   raw: () => raw,
   text: () => text,
   timestamp: () => timestamp,
@@ -59,6 +63,7 @@ function qualifiedTableKey(schemaName, tableName) {
 __name(qualifiedTableKey, "qualifiedTableKey");
 
 // src/db/policy.ts
+var import_zod = require("zod");
 var PolicyExprRef = class _PolicyExprRef {
   static {
     __name(this, "PolicyExprRef");
@@ -291,6 +296,24 @@ function policy(name) {
   return new PolicyBuilder(name);
 }
 __name(policy, "policy");
+function reservedCanRelation(tableName, columns) {
+  if (tableName === "can") {
+    return `a table named "can" would put a relation named "can" on every parent it references \u2014 rename the table`;
+  }
+  for (const [col, b] of Object.entries(columns)) {
+    const def = b._def;
+    if (def.referencesThunk === void 0 && def.selfRefColumn === void 0) continue;
+    if (def.reverseAs === "can") {
+      return `column "${col}" names its reverse relation "can" \u2014 the parent's rows would carry a relation where can is reserved; pick another reverseAs`;
+    }
+    const forward = def.owns === true ? "owner" : def.refAs ?? (col.endsWith("_id") ? col.slice(0, -3) : col);
+    if (forward === "can") {
+      return `column "${col}" would be read as a relation named "can" (${def.refAs === void 0 ? "derived from the column name" : "its as: option"}) \u2014 can is reserved for the policy echo; rename it`;
+    }
+  }
+  return null;
+}
+__name(reservedCanRelation, "reservedCanRelation");
 
 // src/db/schema.ts
 var IndexBuilder = class {
@@ -364,6 +387,10 @@ function defineTable(name, input) {
   if (name.trim() === "") {
     throw new Error("defineTable(name, \u2026): name must not be empty");
   }
+  {
+    const reserved = reservedCanRelation(name, input.columns);
+    if (reserved !== null) throw new Error(`defineTable(${JSON.stringify(name)}): ${reserved}`);
+  }
   const policies = (input.policies?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map(toPolicyDef);
   const rls = policies.length > 0 || input.rls !== false;
   const owned = {};
@@ -392,6 +419,7 @@ function defineTable(name, input) {
   const declaredIndexes = (input.indexes?.(exprCtx(Object.keys(input.columns), 0, name)) ?? []).map((i) => i instanceof IndexBuilder ? i._def : i);
   if (declaredIndexes.length > 0) def.indexes = declaredIndexes;
   if (input.appendOnly === true) def.appendOnly = true;
+  if (input.ignored === true) def.ignored = true;
   if (input.search !== void 0) {
     const s = input.search;
     if (s.from !== void 0) {
@@ -451,6 +479,13 @@ function defineTable(name, input) {
 }
 __name(defineTable, "defineTable");
 var declaringSchemaOf = /* @__PURE__ */ new WeakMap();
+function declaredTableKey(table) {
+  const metadata = table[TABLE_META];
+  const schema = declaringSchemaOf.get(metadata);
+  if (schema === void 0) throw new Error(`defineQuery: table ${metadata.name} must belong to defineSchema before defining its query`);
+  return qualifiedTableKey(schema, metadata.name);
+}
+__name(declaredTableKey, "declaredTableKey");
 function resolveReferences(tables, schemaName) {
   for (const table of Object.values(tables)) {
     for (const [colName, builder] of Object.entries(table.columns)) {
@@ -541,6 +576,187 @@ function defineSchema(name, input) {
 }
 __name(defineSchema, "defineSchema");
 
+// src/db/query.ts
+var import_zod2 = require("zod");
+var import_zod_to_openapi = require("@asteasolutions/zod-to-openapi");
+
+// src/db/query-contract.ts
+function queryColumnContract(column) {
+  const def = column && typeof column === "object" && "_def" in column ? column._def : column;
+  if (!def?.type) throw new Error("Query contract requires declared column types");
+  if (def.transform !== void 0 && def.codec === void 0) throw new Error("Query contracts require a named codec instead of a free-form column transform");
+  return {
+    type: def.type,
+    nullable: def.nullable === true,
+    ...def.codec === void 0 ? {} : {
+      codec: def.codec
+    },
+    ...def.enumValues === void 0 ? {} : {
+      enumValues: [
+        ...def.enumValues
+      ]
+    },
+    ...def.dimensions === void 0 ? {} : {
+      dimensions: def.dimensions
+    }
+  };
+}
+__name(queryColumnContract, "queryColumnContract");
+function stableContract(value) {
+  if (Array.isArray(value)) return `[${value.map(stableContract).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableContract(value[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+__name(stableContract, "stableContract");
+
+// src/db/query.ts
+(0, import_zod_to_openapi.extendZodWithOpenApi)(import_zod2.z);
+function responseColumn(column, validator) {
+  const contract = queryColumnContract(column);
+  let schema;
+  if (validator) return validator;
+  if (contract.codec === "number") schema = import_zod2.z.number().finite();
+  else if (contract.codec === "decimal") schema = import_zod2.z.string();
+  else switch (contract.type) {
+    case "integer":
+      schema = import_zod2.z.number().int().min(-2147483648).max(2147483647);
+      break;
+    case "boolean":
+      schema = import_zod2.z.boolean();
+      break;
+    case "vector":
+      schema = import_zod2.z.array(import_zod2.z.number().finite());
+      break;
+    case "enum": {
+      const values = contract.enumValues;
+      if (!values?.length) throw new Error("Query response requires declared enum values");
+      schema = import_zod2.z.enum(values);
+      break;
+    }
+    case "uuid":
+    case "text":
+    case "timestamp":
+    case "numeric":
+    case "bigint":
+      schema = import_zod2.z.string();
+      break;
+    case "jsonb":
+      throw new Error("Query response requires a fields validator for a selected jsonb column: its TypeScript payload is erased at runtime");
+    default:
+      throw new Error(`Query response does not support column type ${contract.type}`);
+  }
+  return contract.nullable ? schema.nullable() : schema;
+}
+__name(responseColumn, "responseColumn");
+function defineQuery(name, options) {
+  if (typeof name !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,127}$/.test(name)) throw new Error("defineQuery requires a stable name of 1\u2013128 letters, digits or underscores");
+  const table = declaredTableKey(options.table);
+  const select = [
+    ...options.select
+  ];
+  if (!select.length || new Set(select).size !== select.length) throw new Error(`Query ${name}: select must be explicit, nonempty and distinct`);
+  const shape = {}, columns = {};
+  for (const key of select) {
+    if (!Object.hasOwn(options.table[TABLE_META].columns, key)) throw new Error(`Query ${name}: unknown column ${key}`);
+    columns[key] = queryColumnContract(options.table[key]);
+    shape[key] = responseColumn(options.table[key], options.fields?.[key]);
+  }
+  const response = import_zod2.z.array(import_zod2.z.object(shape).strict());
+  const queryInput = options.input, where = options.where, limit = options.limit;
+  const orderBy = options.orderBy === void 0 ? void 0 : JSON.parse(JSON.stringify(options.orderBy));
+  const prepare = /* @__PURE__ */ __name((input) => {
+    const parsed = queryInput.parse(input);
+    const filter = where === void 0 ? {} : where(parsed);
+    if (!filter || typeof filter !== "object" || Array.isArray(filter) || typeof filter.then === "function") {
+      throw new Error(`Query ${name}: where must return a synchronous filter object`);
+    }
+    const size = typeof limit === "function" ? limit(parsed) : limit;
+    if (limit !== void 0 && (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0)) throw new Error(`Query ${name}: limit must produce a nonnegative safe integer`);
+    return {
+      name,
+      table,
+      columns: JSON.parse(JSON.stringify(columns)),
+      where: filter,
+      options: {
+        select: [
+          ...select
+        ],
+        ...orderBy === void 0 ? {} : {
+          orderBy: structuredClone(orderBy)
+        },
+        ...limit === void 0 ? {} : {
+          limit: size
+        }
+      }
+    };
+  }, "prepare");
+  const attach = /* @__PURE__ */ __name((schema) => {
+    const api = {
+      queryName: name,
+      input: queryInput,
+      prepare,
+      async run(database, input) {
+        const request = prepare(input);
+        const rows = await ("$readQuery" in database ? database.$readQuery(request) : database.readQuery(request));
+        return schema.parse(rows);
+      },
+      sql(database, input) {
+        const request = prepare(input);
+        return "$compileQuery" in database ? database.$compileQuery(request) : database.compileQuery(request);
+      },
+      explain(database, input) {
+        const request = prepare(input);
+        return "$explainQuery" in database ? database.$explainQuery(request) : database.explainQuery(request);
+      },
+      contract() {
+        const registry = new import_zod_to_openapi.OpenAPIRegistry();
+        registry.register(`${name}Input`, queryInput);
+        registry.register(`${name}Response`, schema);
+        return JSON.parse(JSON.stringify({
+          name,
+          table,
+          select,
+          columns,
+          components: new import_zod_to_openapi.OpenApiGeneratorV31(registry.definitions).generateComponents().components
+        }));
+      }
+    };
+    for (const key of [
+      "min",
+      "max",
+      "length",
+      "describe",
+      "openapi"
+    ]) {
+      const modify = schema[key].bind(schema);
+      Object.defineProperty(schema, key, {
+        value: /* @__PURE__ */ __name((...args) => attach(modify(...args)), "value"),
+        configurable: true
+      });
+    }
+    return Object.assign(schema, api);
+  }, "attach");
+  return attach(response);
+}
+__name(defineQuery, "defineQuery");
+function queryManifest(queries) {
+  const sorted = [
+    ...queries
+  ].sort((a, b) => a.queryName.localeCompare(b.queryName));
+  if (new Set(sorted.map((query) => query.queryName)).size !== sorted.length) throw new Error("Query manifest contains duplicate names");
+  return JSON.parse(stableContract({
+    version: 1,
+    queries: sorted.map((query) => query.contract())
+  }));
+}
+__name(queryManifest, "queryManifest");
+function assertQueryManifest(queries, baseline) {
+  if (stableContract(queryManifest(queries)) !== stableContract(baseline)) {
+    throw new Error("Query contract drift: compare queryManifest() with the committed manifest and review the API/client changes before updating it");
+  }
+}
+__name(assertQueryManifest, "assertQueryManifest");
+
 // src/db/extensions.ts
 var PALBASE_EXTENSIONS = [
   // Search & text
@@ -1506,6 +1722,13 @@ function translateRejection(err, builder) {
 }
 __name(translateRejection, "translateRejection");
 
+// src/db/sqlstate.ts
+var SQLSTATE = Object.freeze({
+  serializationFailure: "40001",
+  deadlockDetected: "40P01",
+  commandGuardFailed: "PBC01"
+});
+
 // src/errors.ts
 var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
 var HttpError = class extends Error {
@@ -1550,6 +1773,39 @@ var HttpError = class extends Error {
   }
 };
 
+// src/db/workload.ts
+function defineWorkload(name, options) {
+  const result = {
+    name,
+    concurrency: options.concurrency,
+    queueLimit: options.queueLimit,
+    tenantConcurrency: options.tenantConcurrency ?? options.concurrency,
+    tenantQueueLimit: options.tenantQueueLimit ?? options.queueLimit,
+    queueTimeoutMs: options.queueTimeoutMs ?? 1e3,
+    tenantClaim: options.tenantClaim ?? "tenant_id"
+  };
+  validateWorkload(result);
+  return Object.freeze(result);
+}
+__name(defineWorkload, "defineWorkload");
+function validateWorkload(value) {
+  if (typeof value.name !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value.name)) throw new Error("workload name must be 1\u201364 letters/digits/dots/dashes");
+  for (const name of [
+    "concurrency",
+    "tenantConcurrency",
+    "queueLimit",
+    "tenantQueueLimit",
+    "queueTimeoutMs"
+  ]) {
+    const n = value[name], min = name.endsWith("Limit") ? 0 : 1;
+    const max = name === "queueTimeoutMs" ? 6e4 : name.endsWith("Limit") ? 1e4 : 1e3;
+    if (!Number.isInteger(n) || n < min || n > max) throw new Error(`workload ${name} must be an integer between ${min} and ${max}`);
+  }
+  if (value.tenantConcurrency > value.concurrency || value.tenantQueueLimit > value.queueLimit) throw new Error("workload tenant limits cannot exceed global limits");
+  if (typeof value.tenantClaim !== "string" || !/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(value.tenantClaim)) throw new Error("workload tenantClaim must be a top-level claim name");
+}
+__name(validateWorkload, "validateWorkload");
+
 // src/db/typed-db.ts
 function makeTypedTable(name, raw2) {
   return {
@@ -1561,7 +1817,14 @@ function makeTypedTable(name, raw2) {
     }), "put"),
     update: /* @__PURE__ */ __name((q) => raw2.update(name, q.where.id, q.set), "update"),
     delete: /* @__PURE__ */ __name((id) => raw2.delete(name, id), "delete"),
+    findUnique: /* @__PURE__ */ __name((q) => raw2.findUnique(name, q.where, {
+      select: q.select
+    }), "findUnique"),
     findById: /* @__PURE__ */ __name((id) => raw2.findById(name, id), "findById"),
+    page: /* @__PURE__ */ __name((q) => {
+      const { where, ...opts } = q ?? {};
+      return raw2.page(name, where, opts);
+    }, "page"),
     findMany: /* @__PURE__ */ __name((q) => {
       const { where, ...opts } = q ?? {};
       return raw2.findMany(name, where, opts);
@@ -1579,17 +1842,33 @@ function makeTypedDB(schema, raw2) {
   for (const key of Object.keys(schema.tables)) {
     const tableDef = schema.tables[key];
     if (tableDef !== void 0) {
-      tables[key] = makeTypedTable(tableDef.name, raw2);
+      tables[key] = makeTypedTable(qualifiedTableKey(schema.name, tableDef.name), raw2);
     }
   }
   const result = {
     tables,
+    diagnostics: /* @__PURE__ */ __name(() => raw2.diagnostics(), "diagnostics"),
+    readQuery: /* @__PURE__ */ __name((query) => raw2.readQuery(query), "readQuery"),
+    compileQuery: /* @__PURE__ */ __name((query) => raw2.compileQuery(query), "compileQuery"),
+    explainQuery: /* @__PURE__ */ __name((query) => raw2.explainQuery(query), "explainQuery"),
+    command(fn, options) {
+      const builder = new TxPlanBuilder();
+      const planTables = Object.fromEntries(Object.entries(schema.tables).map(([key, table]) => [
+        key,
+        builder.table(qualifiedTableKey(schema.name, table.name))
+      ]));
+      return runTxPlan({
+        txPlan: /* @__PURE__ */ __name((plan) => raw2.command(plan, options), "txPlan")
+      }, {
+        tables: planTables
+      }, builder, fn);
+    },
     transaction(fn) {
       const builder = new TxPlanBuilder();
       const planTables = {};
       for (const key of Object.keys(schema.tables)) {
         const tableDef = schema.tables[key];
-        if (tableDef !== void 0) planTables[key] = builder.table(tableDef.name);
+        if (tableDef !== void 0) planTables[key] = builder.table(qualifiedTableKey(schema.name, tableDef.name));
       }
       return runTxPlan(raw2, {
         tables: planTables
@@ -1607,11 +1886,14 @@ __name(makeTypedDB, "makeTypedDB");
   TABLE_META,
   TxPlanError,
   TxRefError,
+  assertQueryManifest,
   bigint,
   boolean,
   dec,
+  defineQuery,
   defineSchema,
   defineTable,
+  defineWorkload,
   enumType,
   inc,
   installationRef,
@@ -1623,6 +1905,7 @@ __name(makeTypedDB, "makeTypedDB");
   openai,
   ownedByUser,
   policy,
+  queryManifest,
   raw,
   text,
   timestamp,