tempest-db-js 0.4.0 → 0.5.0

package/README.md

@@ -5,7 +5,7 @@
 
 📖 **Documentation:** [Português (BR)](https://mauriciobenjamin700.github.io/tempest-db-js/) · [English (US)](https://mauriciobenjamin700.github.io/tempest-db-js/en/)
 
-> ✅ **Status: alpha (v0.4.0), published on [npm](https://www.npmjs.com/package/tempest-db-js).** The full path works end-to-end — declarative models with **foreign keys, UNIQUE and table constraints**, typed query builder (aggregations, `DISTINCT`, upsert), **real SQLite + PostgreSQL execution**, a **MySQL** dialect, joins, relations, Alembic-style migrations (sync + **async** runner) with a `tempest-db` CLI, a typed `BaseRepository`, and an opt-in active-record layer. The public API may still shift before v1.0.
+> ✅ **Status: alpha (v0.5.0), published on [npm](https://www.npmjs.com/package/tempest-db-js).** The full path works end-to-end — declarative models with **foreign keys, UNIQUE, table constraints, explicit column names and PostgreSQL arrays**, a typed query builder (aggregations, `DISTINCT`, upsert with **partial-index predicates**, **`FOR UPDATE SKIP LOCKED`**, SQL expressions in writes), **real SQLite + PostgreSQL execution**, a **MySQL** dialect, joins, relations, Alembic-style migrations (sync + **async** runner) with a `tempest-db` CLI, a typed `BaseRepository`, an opt-in active-record layer, and a `session.raw` escape hatch. The public API may still shift before v1.0.
 
 ## Why tempest-db-js
 
@@ -76,6 +76,12 @@ Typed extras, each with a [docs recipe](https://mauriciobenjamin700.github.io/te
 - **Upsert** — `insert(Row).values(...).onConflictDoUpdate(["key"], { ... })` / `.onConflictDoNothing(["key"])` (portable SQLite ↔ PostgreSQL).
 - **Active-record (opt-in)** — `activeRecord(User, session)` → `save`/`update`/`delete`/`reload` over `.data`; the plain-object default is unchanged.
 - **Query logging & errors** — `createEngine(url, { onQuery })` traces every statement; a failed statement throws `QueryExecutionError` carrying the SQL + params.
+- **Durable queues** — `select(Job).where(...).limit(10).forUpdate({ skipLocked: true })` inside a transaction hands each worker a disjoint batch, and `set({ attempts: sql.raw("attempts + 1") })` increments in the database instead of read-modify-write. SQLite throws rather than emitting an unlocked `SELECT`.
+- **Partial-index upsert** — `onConflictDoNothing(["consumer", "idempotencyKey"], { where: { idempotencyKey: { isNull: false } } })` repeats the index predicate PostgreSQL requires to match a **partial** unique index as a conflict target.
+- **Column names** — `.name("consumer_name")` per column, or `static naming = "snake_case"` per table: a `snake_case` schema behind a `camelCase` model, mapped everywhere including the migration IR (so no false drift).
+- **PostgreSQL arrays** — `column.array(column.text())` → `text[]` typed as `string[]`, with `contains` (`@>`), `containedBy` (`<@`) and `overlaps` (`&&`) in `where`.
+- **Case-insensitive lookups** — `{ ieq: probe }` → `lower(col) = lower($1)`: no wildcards, matches a `lower(col)` functional index. (`ilike` is pattern matching — `{ ilike: "%" }` matches every row.)
+- **Raw SQL escape hatch** — `session.raw(sql, params, { as: Model })` for the query the builder cannot yet express, always parameterized and integrated with logging, errors and transactions.
 
 ## Migrations CLI
 
@@ -106,7 +112,7 @@ HTTP integration recipes (Hono, Express, Fastify) live in the [docs](https://mau
 
 ## Roadmap
 
-See [ROADMAP.md](./ROADMAP.md). Shipped (v0.4.0): declarative schema with foreign keys / UNIQUE / table constraints, SQLite + PostgreSQL execution (both tested in CI, Postgres against a live database), a MySQL dialect, joins, relations, sync + async migration runners with a `tempest-db` CLI, repository, aggregations/upsert, opt-in active-record. Next: MySQL execution in CI + `RETURNING` round-trip, async CLI wiring, then `tempest-ts-sdk`.
+See [ROADMAP.md](./ROADMAP.md). Shipped (v0.5.0): declarative schema with foreign keys / UNIQUE / table constraints / explicit column names / PostgreSQL arrays, SQLite + PostgreSQL execution (both tested in CI, Postgres against a live database), a MySQL dialect, row locking, SQL expressions in writes, partial-index upsert, `session.raw`, joins, relations, sync + async migration runners with a `tempest-db` CLI, repository, aggregations/upsert, opt-in active-record. Next: subqueries in `IN`/`EXISTS` and `HAVING`, MySQL execution in CI + `RETURNING` round-trip, async CLI wiring, then `tempest-ts-sdk`.
 
 ## Development
 

package/dist/bin.cjs

@@ -100,6 +100,22 @@ function makeRevisionId(label, parents) {
   return hash.toString(16).padStart(8, "0");
 }
 
+// src/expressions.ts
+function renderPortableToken(token, dialect) {
+  switch (token) {
+    case "now":
+      return dialect === "postgresql" ? "now()" : "CURRENT_TIMESTAMP";
+    case "current_date":
+      return "CURRENT_DATE";
+    case "current_time":
+      return "CURRENT_TIME";
+    case "uuidv4":
+      if (dialect === "postgresql") return "gen_random_uuid()";
+      if (dialect === "mysql") return "(UUID())";
+      return "(lower(hex(randomblob(16))))";
+  }
+}
+
 // src/migrations/ddl.ts
 function quoteId(name, dialect) {
   return dialect === "mysql" ? `\`${name.replace(/`/g, "``")}\`` : `"${name.replace(/"/g, '""')}"`;
@@ -123,6 +139,8 @@ function renderColumnType(type, dialect) {
         return "NUMERIC";
       case "blob":
         return "BLOB";
+      case "array":
+        throw new Error(unsupportedArray("sqlite"));
       default:
         return "TEXT";
     }
@@ -164,6 +182,8 @@ function renderColumnType(type, dialect) {
         return "CHAR(36)";
       case "enum":
         return `ENUM(${(meta.values ?? []).map(quoteLiteral).join(", ")})`;
+      case "array":
+        throw new Error(unsupportedArray("mysql"));
     }
   }
   switch (kind) {
@@ -202,27 +222,39 @@ function renderColumnType(type, dialect) {
       return "UUID";
     case "enum":
       return "TEXT";
+    case "array":
+      return `${renderColumnType(arrayElement(meta.element), dialect)}[]`;
+  }
+}
+function unsupportedArray(dialect) {
+  return `column.array() is PostgreSQL-only \u2014 ${dialect} has no native array type. Model the column as JSON there, accepting that array operators will not work.`;
+}
+function arrayElement(element) {
+  if (!element) {
+    throw new Error(
+      "An array column has no element type \u2014 build it with column.array()."
+    );
   }
+  return element;
 }
-function renderDefault(def, dialect) {
+function renderDefault(def, dialect, type) {
   if (def.kind === "expression") {
     const expr = def.expression;
-    if (typeof expr === "object") return expr.raw;
-    switch (expr) {
-      case "now":
-        return dialect === "postgresql" ? "now()" : "CURRENT_TIMESTAMP";
-      case "current_date":
-        return "CURRENT_DATE";
-      case "current_time":
-        return "CURRENT_TIME";
-      case "uuidv4":
-        if (dialect === "postgresql") return "gen_random_uuid()";
-        if (dialect === "mysql") return "(UUID())";
-        return "(lower(hex(randomblob(16))))";
+    if (typeof expr === "object") {
+      if ("raw" in expr) return expr.raw;
+      throw new Error(
+        "sql.expr`...` binds parameters and cannot be rendered as a DEFAULT \u2014 use sql.raw()."
+      );
     }
+    return renderPortableToken(expr, dialect);
   }
   const value = def.value;
   if (value === null) return "NULL";
+  if (Array.isArray(value) && type?.kind === "array") {
+    const elementType = renderColumnType(arrayElement(type.meta.element), dialect);
+    const items = value.map((v) => renderDefault({ kind: "literal", value: v }, dialect));
+    return `ARRAY[${items.join(", ")}]::${elementType}[]`;
+  }
   if (typeof value === "boolean") {
     return dialect === "postgresql" ? value ? "TRUE" : "FALSE" : value ? "1" : "0";
   }
@@ -268,7 +300,9 @@ function tableConstraintClauses(table, dialect) {
 function renderColumnDef(col, dialect) {
   let sql = `${quoteId(col.name, dialect)} ${renderColumnType(col.type, dialect)}`;
   if (col.notNull) sql += " NOT NULL";
-  if (col.default !== null) sql += ` DEFAULT ${renderDefault(col.default, dialect)}`;
+  if (col.default !== null) {
+    sql += ` DEFAULT ${renderDefault(col.default, dialect, col.type)}`;
+  }
   sql += columnConstraintSuffix(col, dialect);
   return sql;
 }
@@ -292,7 +326,9 @@ function renderCreateTable(table, dialect) {
       typeStmts.push(`CREATE TYPE ${quoteId(typeName, dialect)} AS ENUM (${values})`);
       let def = `${quoteId(c.name, dialect)} ${quoteId(typeName, dialect)}`;
       if (c.notNull) def += " NOT NULL";
-      if (c.default !== null) def += ` DEFAULT ${renderDefault(c.default, dialect)}`;
+      if (c.default !== null) {
+        def += ` DEFAULT ${renderDefault(c.default, dialect, c.type)}`;
+      }
       return def + columnConstraintSuffix(c, dialect);
     }
     if (dialect === "postgresql" && isAutoIncrementPk(table, c)) {
@@ -436,7 +472,7 @@ function renderAlterColumn(table, to, dialect) {
     to.notNull ? `ALTER TABLE ${t} ALTER COLUMN ${c} SET NOT NULL` : `ALTER TABLE ${t} ALTER COLUMN ${c} DROP NOT NULL`
   );
   stmts.push(
-    to.default !== null ? `ALTER TABLE ${t} ALTER COLUMN ${c} SET DEFAULT ${renderDefault(to.default, dialect)}` : `ALTER TABLE ${t} ALTER COLUMN ${c} DROP DEFAULT`
+    to.default !== null ? `ALTER TABLE ${t} ALTER COLUMN ${c} SET DEFAULT ${renderDefault(to.default, dialect, to.type)}` : `ALTER TABLE ${t} ALTER COLUMN ${c} DROP DEFAULT`
   );
   return stmts;
 }
@@ -611,6 +647,9 @@ function heads(migrations) {
 function isDefaultValue(value) {
   return typeof value === "object" && value !== null && "kind" in value && (value.kind === "literal" || value.kind === "expression");
 }
+function bindsParameters(value) {
+  return value.kind === "expression" && typeof value.expression === "object" && "parts" in value.expression;
+}
 function parseReference(ref, options) {
   const dot = ref.lastIndexOf(".");
   if (dot <= 0 || dot === ref.length - 1) {
@@ -624,48 +663,71 @@ function parseReference(ref, options) {
   };
 }
 var Column = class _Column {
-  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null) {
+  constructor(type, flags, defaultValue = null, onUpdateValue = null, reference = null, dbName = null) {
     this.type = type;
     this.flags = flags;
     this.defaultValue = defaultValue;
     this.onUpdateValue = onUpdateValue;
     this.reference = reference;
+    this.dbName = dbName;
   }
   type;
   flags;
   defaultValue;
   onUpdateValue;
   reference;
-  primaryKey() {
+  dbName;
+  /** Clone this column with one facet replaced, carrying every other over. */
+  derive(patch) {
     return new _Column(
       this.type,
-      { ...this.flags, primaryKey: true, hasDefault: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
+      patch.flags ?? this.flags,
+      patch.defaultValue !== void 0 ? patch.defaultValue : this.defaultValue,
+      patch.onUpdateValue !== void 0 ? patch.onUpdateValue : this.onUpdateValue,
+      patch.reference !== void 0 ? patch.reference : this.reference,
+      patch.dbName !== void 0 ? patch.dbName : this.dbName
     );
   }
+  primaryKey() {
+    return this.derive({ flags: { ...this.flags, primaryKey: true, hasDefault: true } });
+  }
   notNull() {
-    return new _Column(
-      this.type,
-      { ...this.flags, notNull: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
-    );
+    return this.derive({ flags: { ...this.flags, notNull: true } });
   }
   /**
    * Add a `UNIQUE` constraint to the column (mirrors SQLAlchemy's
    * `mapped_column(unique=True)`). DDL-only — does not change the inferred type.
    */
   unique() {
-    return new _Column(
-      this.type,
-      { ...this.flags, unique: true },
-      this.defaultValue,
-      this.onUpdateValue,
-      this.reference
-    );
+    return this.derive({ flags: { ...this.flags, unique: true } });
+  }
+  /**
+   * Map this property to a differently-named database column, à la SQLAlchemy's
+   * `mapped_column("consumer_name")` (Django's `db_column`, Prisma's `@map`).
+   *
+   * The override applies everywhere the name reaches SQL — select, insert,
+   * update, delete, where, order by, group by, returning, conflict targets, the
+   * migration IR and the drift check — while the TypeScript row keeps the
+   * property name. Use it to keep a `snake_case` schema behind a `camelCase`
+   * model; {@link Model.naming} does the same for a whole table at once.
+   *
+   * @param dbName The real column name in the database.
+   * @returns A new column bound to that name.
+   * @throws Error When `dbName` is empty.
+   *
+   * @example
+   * ```ts
+   * class ApiKey extends Model {
+   *   static tablename = "api_keys";
+   *   consumerName = column.text().name("consumer_name").notNull();
+   * }
+   * ```
+   */
+  name(dbName) {
+    if (dbName.length === 0) {
+      throw new Error("column.name() requires a non-empty database column name.");
+    }
+    return this.derive({ dbName });
   }
   /**
    * Declare a foreign-key reference to another table's column, à la SQLAlchemy's
@@ -678,37 +740,50 @@ var Column = class _Column {
    * @throws Error When `ref` is not a valid `"table.column"` string.
    */
   references(ref, options) {
-    return new _Column(
-      this.type,
-      this.flags,
-      this.defaultValue,
-      this.onUpdateValue,
-      parseReference(ref, options)
-    );
+    return this.derive({ reference: parseReference(ref, options) });
   }
   /**
    * Set the insert-time default: a constant value of type `T`, or a portable
    * server-side expression from {@link sql} (e.g. `sql.now()`, `sql.uuidv4()`).
+   *
+   * @param value The literal default, or a {@link sql} expression.
+   * @returns A new column carrying the default.
+   * @throws Error When given a `sql.expr` fragment — a `DEFAULT` clause has
+   *   nowhere to bind parameters; use `sql.raw()` for a verbatim expression.
    */
   default(value) {
     const resolved = isDefaultValue(value) ? value : { kind: "literal", value };
-    return new _Column(
-      this.type,
-      { ...this.flags, hasDefault: true },
-      resolved,
-      this.onUpdateValue,
-      this.reference
-    );
+    if (bindsParameters(resolved)) {
+      throw new Error(
+        "sql.expr`...` binds parameters and cannot be a column default \u2014 use sql.raw() for a verbatim DEFAULT expression."
+      );
+    }
+    return this.derive({
+      flags: { ...this.flags, hasDefault: true },
+      defaultValue: resolved
+    });
   }
   /**
    * Re-apply a value whenever the row is updated (e.g. an `updated_at` column
    * with `sql.now()`). Mirrors SQLAlchemy's `onupdate`.
+   *
+   * @param value The literal value, or a {@link sql} expression.
+   * @returns A new column carrying the on-update value.
+   * @throws Error When given a `sql.expr` fragment (see {@link Column.default}).
    */
   onUpdate(value) {
     const resolved = isDefaultValue(value) ? value : { kind: "literal", value };
-    return new _Column(this.type, this.flags, this.defaultValue, resolved, this.reference);
+    if (bindsParameters(resolved)) {
+      throw new Error(
+        "sql.expr`...` binds parameters and cannot be an onUpdate default \u2014 use sql.raw() for a verbatim expression."
+      );
+    }
+    return this.derive({ onUpdateValue: resolved });
   }
 };
+function toSnakeCase(name) {
+  return name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
 var columnsCache = /* @__PURE__ */ new WeakMap();
 function columnsOf(model) {
   const cached = columnsCache.get(model);
@@ -723,16 +798,43 @@ function columnsOf(model) {
   columnsCache.set(model, out);
   return out;
 }
+var nameMapCache = /* @__PURE__ */ new WeakMap();
+function columnNamesOf(model) {
+  const cached = nameMapCache.get(model);
+  if (cached !== void 0) return cached;
+  const strategy = model.naming ?? "preserve";
+  const map = {};
+  const seen = /* @__PURE__ */ new Map();
+  let renamed = false;
+  for (const [prop, col] of Object.entries(columnsOf(model))) {
+    const dbName = col.dbName ?? (strategy === "snake_case" ? toSnakeCase(prop) : prop);
+    const collision = seen.get(dbName);
+    if (collision !== void 0) {
+      throw new Error(
+        `${model.tablename}: properties "${collision}" and "${prop}" both map to column "${dbName}".`
+      );
+    }
+    seen.set(dbName, prop);
+    map[prop] = dbName;
+    if (dbName !== prop) renamed = true;
+  }
+  const result = renamed ? map : null;
+  nameMapCache.set(model, result);
+  return result;
+}
 
 // src/migrations/ir.ts
 function constraintName(prefix, table, columns) {
   return `${prefix}_${table}_${columns.join("_")}`;
 }
 function reflectTable(model) {
+  const names = columnNamesOf(model);
+  const toColumn = (prop) => names?.[prop] ?? prop;
   const columns = {};
   const primaryKey = [];
-  for (const [name, col] of Object.entries(columnsOf(model))) {
+  for (const [prop, col] of Object.entries(columnsOf(model))) {
     const isPk = col.flags.primaryKey;
+    const name = toColumn(prop);
     columns[name] = {
       name,
       type: col.type,
@@ -747,15 +849,16 @@ function reflectTable(model) {
   const uniqueConstraints = [];
   const foreignKeys = [];
   for (const c of model.tableArgs?.() ?? []) {
+    const cols = c.columns.map(toColumn);
     if (c.kind === "unique") {
       uniqueConstraints.push({
-        name: c.name ?? constraintName("uq", model.tablename, c.columns),
-        columns: c.columns
+        name: c.name ?? constraintName("uq", model.tablename, cols),
+        columns: cols
       });
     } else {
       foreignKeys.push({
-        name: c.name ?? constraintName("fk", model.tablename, c.columns),
-        columns: c.columns,
+        name: c.name ?? constraintName("fk", model.tablename, cols),
+        columns: cols,
         refTable: c.refTable,
         refColumns: c.refColumns,
         onDelete: c.onDelete,