@stacksjs/database 0.70.88 → 0.70.91

package/dist/table.js

@@ -0,0 +1,26 @@
+import { log } from "@stacksjs/logging";
+import { Column } from "./column";
+
+export class Table {
+  columns = [];
+  increments(name) {
+    const column = new Column(name, "integer", {
+      primaryKey: !0,
+      autoIncrement: !0
+    });
+    this.columns.push(column);
+    return column;
+  }
+  string(name, varchar = 255) {
+    const column = new Column(name, `varchar(${varchar})`);
+    this.columns.push(column);
+    return column;
+  }
+  timestamps() {
+    this.columns.push(new Column("created_at", "timestamp"));
+    this.columns.push(new Column("updated_at", "timestamp"));
+  }
+  execute() {
+    log.info(`Creating table with columns: ${this.columns.map((col) => col.name).join(", ")}`);
+  }
+}

package/dist/tools/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/setup.js

@@ -0,0 +1,6 @@
+import { dynamoDb } from "dynamodb-tooling";
+const port = 8000;
+dynamoDb.launch({
+  port,
+  additionalArgs: ["-sharedDb"]
+});

package/dist/transaction-context.d.ts

@@ -0,0 +1,52 @@
+/**
+ * True if the current async context is inside an active transaction
+ * scope. Queue dispatch (and other side-effect emitters) read this
+ * to decide between immediate execution and buffering.
+ */
+export declare function isInTransaction(): boolean;
+/**
+ * Enqueue a callback to fire after the surrounding transaction
+ * commits. Returns:
+ *   - `true`  — buffered; caller should NOT execute the side-effect now
+ *   - `false` — no active transaction; caller should execute immediately
+ *
+ * This is the low-level primitive. Higher-level facades (queue
+ * dispatch, mailer send, event emit) wrap it with their own
+ * "respect transaction context unless overridden" logic.
+ */
+export declare function enqueueAfterCommit(callback: AfterCommitCallback): boolean;
+/**
+ * Run `fn` inside a transaction scope. Returns whatever `fn`
+ * returns. On success, fires every buffered after-commit callback
+ * in insertion order. On error, discards them — the transaction
+ * rolled back so the side-effects shouldn't happen.
+ *
+ * Used by `@stacksjs/orm`'s `transaction()` wrapper to thread the
+ * scope through user code. Apps don't call this directly.
+ *
+ * Nested calls reuse the outer scope rather than nesting — flush
+ * happens on the OUTERMOST commit, matching the savepoint
+ * semantics of every relational database. The depth counter is
+ * tracked so the outer call knows when it owns the flush.
+ */
+export declare function runInTransactionScope<T>(fn: () => Promise<T>, options?: { onError?: (err: unknown, index: number) => void }): Promise<T>;
+/**
+ * Test-only escape hatch — manually flush the current scope's
+ * buffered callbacks without ending the transaction. Production
+ * code never needs this; tests use it to assert intermediate
+ * state. Returns the number of callbacks fired.
+ */
+export declare function __flushAfterCommitNow(): Promise<number>;
+/**
+ * Test-only escape hatch — peek at the number of buffered
+ * callbacks without firing them. Returns 0 outside a scope.
+ */
+export declare function __pendingAfterCommitCount(): number;
+/**
+ * One buffered side-effect waiting for the surrounding transaction
+ * to commit. Errors thrown during flush are NOT re-thrown — the
+ * transaction itself already committed, so failing the whole flow
+ * after-the-fact would corrupt the caller's mental model. Errors
+ * are logged via `onError` if the scope supplied one.
+ */
+declare type AfterCommitCallback = () => Promise<void> | void;

package/dist/transaction-context.js

@@ -0,0 +1,62 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const transactionStorage = new AsyncLocalStorage;
+export function isInTransaction() {
+  return transactionStorage.getStore() !== void 0;
+}
+export function enqueueAfterCommit(callback) {
+  const scope = transactionStorage.getStore();
+  if (!scope)
+    return !1;
+  scope.pending.push(callback);
+  return !0;
+}
+export async function runInTransactionScope(fn, options = {}) {
+  const existing = transactionStorage.getStore();
+  if (existing) {
+    existing.depth += 1;
+    try {
+      return await fn();
+    } finally {
+      existing.depth -= 1;
+    }
+  }
+  const scope = {
+    pending: [],
+    depth: 1,
+    onError: options.onError
+  };
+  let result;
+  try {
+    result = await transactionStorage.run(scope, fn);
+  } catch (err) {
+    scope.pending.length = 0;
+    throw err;
+  }
+  await flushScope(scope);
+  return result;
+}
+async function flushScope(scope) {
+  for (let i = 0;i < scope.pending.length; i++)
+    try {
+      await scope.pending[i]();
+    } catch (err) {
+      if (scope.onError)
+        try {
+          scope.onError(err, i);
+        } catch {}
+      else
+        console.error("[transaction-context] after-commit callback threw:", err);
+    }
+  scope.pending.length = 0;
+}
+export async function __flushAfterCommitNow() {
+  const scope = transactionStorage.getStore();
+  if (!scope)
+    return 0;
+  const count = scope.pending.length;
+  await flushScope(scope);
+  return count;
+}
+export function __pendingAfterCommitCount() {
+  return transactionStorage.getStore()?.pending.length ?? 0;
+}

package/dist/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * SQL template tag function.
+ * Creates parameterized SQL queries from template literals.
+ *
+ * @example
+ * ```ts
+ * const query = sql`SELECT * FROM users WHERE id = ${userId}`
+ * ```
+ */
+export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): Sql;
+/**
+ * Type for raw SQL expressions.
+ * Used when building dynamic SQL queries.
+ */
+export declare interface RawBuilder<T = unknown> {
+  readonly sql: string
+  readonly parameters?: unknown[]
+  readonly __result?: T
+}
+/**
+ * SQL template tag type.
+ * Used for tagged template literals that produce SQL.
+ */
+export declare interface Sql {
+  readonly sql: string
+  readonly parameters: unknown[]
+}
+/**
+ * Reference to a column for use inside an expression. Returned by
+ * {@link StacksExpressionBuilder.ref} and accepted everywhere a value
+ * or column is expected (e.g. inside `sql\`\${ref} > 0\`\`).
+ *
+ * The shape matches `sql.ref()`'s return so a raw fragment from either
+ * source is interoperable.
+ */
+export declare interface ColumnRef {
+  readonly raw: string
+  as: (alias: string) => ColumnRef
+}
+/**
+ * Fluent aggregate-function builder accessible via
+ * `eb.fn.count(...)`, `eb.fn.sum(...)`, etc. The chained `.as(name)`
+ * names the resulting column in the projection; `.filterWhere(...)`
+ * scopes the aggregate to a sub-population (`COUNT(*) FILTER (WHERE
+ * status = 'success')` style).
+ */
+export declare interface AggregateExpression {
+  as: (alias: string) => AggregateExpression
+  filterWhere: (column: string, op: ExpressionOperator | string, value: unknown) => AggregateExpression
+}
+/**
+ * Aggregate-function accessor exposed on the expression builder.
+ *
+ * Covers the call sites in commerce today (`count`, `sum`, `avg`,
+ * `min`, `max`). Other Kysely-side aggregates (`countAll`,
+ * `coalesce`, etc.) can be added here as call sites surface; we
+ * deliberately don't widen to "everything Kysely exposes" because
+ * that surface keeps growing and an `any`-typed escape hatch always
+ * exists (`eb.fn as any).newThing(...)`) if a one-off bypass is
+ * genuinely needed.
+ */
+export declare interface ExpressionFunctions {
+  countAll: () => AggregateExpression
+  count: (column: string) => AggregateExpression
+  sum: (column: string) => AggregateExpression
+  avg: (column: string) => AggregateExpression
+  min: (column: string) => AggregateExpression
+  max: (column: string) => AggregateExpression
+}
+/**
+ * Minimal typed expression-builder surface for sub-query / inline-
+ * expression callbacks (stacksjs/stacks#1892, T-2 from #1875).
+ *
+ * Background: the framework's commerce module passed `(eb: any) => …`
+ * to `.where()` / `.select()` callbacks across 80+ sites. The `any`
+ * escape meant typos like `eb.compare(...)` (no such method — it's
+ * `cmpr`) only surfaced at runtime, and any later rename in
+ * bun-query-builder couldn't break here at type-check time.
+ *
+ * This interface declares the methods commerce actually uses today —
+ * `or`, `cmpr`, `ref`, `raw`, plus the `fn` aggregate accessor. It
+ * intentionally does NOT claim to be the full Kysely
+ * `ExpressionBuilder<DB, TB>` type:
+ *
+ *   - Stacks's `Database` is still typed as `any` (no generated
+ *     schema map yet) so the table-aware narrowing Kysely offers
+ *     can't be expressed here yet.
+ *   - bun-query-builder doesn't currently re-export its internal
+ *     `ExpressionBuilder` type, so we can't alias to the canonical
+ *     shape upstream.
+ *
+ * When either of those changes upstream, swap this interface's
+ * implementation in one place rather than re-typing every call site.
+ */
+export declare interface StacksExpressionBuilder {
+  (left: unknown, op: ExpressionOperator | string, right: unknown): unknown
+  or: (expressions: ReadonlyArray<unknown>) => unknown
+  and?: (expressions: ReadonlyArray<unknown>) => unknown
+  cmpr: (left: unknown, op: ExpressionOperator, right: unknown) => unknown
+  ref: (column: string) => ColumnRef
+  raw: (value: string) => ColumnRef
+  fn: ExpressionFunctions
+  readonly [extra: string]: unknown
+}
+/**
+ * Database types - Compatibility layer
+ *
+ * These types provide backwards compatibility with code that
+ * previously used Kysely types. They work with bun-query-builder's
+ * native type system.
+ */
+/**
+ * Marks a column as auto-generated (e.g., auto-increment primary keys).
+ * When inserting, this field is optional. When selecting, it's required.
+ */
+export type Generated<T> = T;
+/**
+ * Marks a column as always generated (computed columns).
+ * This field cannot be inserted or updated directly.
+ */
+export type GeneratedAlways<T> = T;
+/**
+ * Utility type for insert operations.
+ * Makes Generated fields optional, keeps required fields required.
+ */
+export type Insertable<T> = {
+  [K in keyof T]?: T[K]
+}
+/**
+ * Utility type for select operations.
+ * All fields are as defined in the table type.
+ */
+export type Selectable<T> = T;
+/**
+ * Utility type for update operations.
+ * All fields are optional since you may update only some fields.
+ */
+export type Updateable<T> = Partial<T>;
+/**
+ * Database type alias for backwards compatibility.
+ * Use the query builder from bun-query-builder instead.
+ */
+export type Database = any;
+/**
+ * Comparison operator accepted by {@link StacksExpressionBuilder.cmpr}
+ * and friends. Mirrors the standard SQL operators the underlying
+ * Kysely-style builder supports.
+ */
+export type ExpressionOperator = | '=' | '!=' | '<>' | '<' | '<=' | '>' | '>='
+  | 'in' | 'not in' | 'is' | 'is not'
+  | 'like' | 'not like' | 'ilike' | 'not ilike';

package/dist/types.js

@@ -0,0 +1,23 @@
+export function sql(strings, ...values) {
+  const sqlParts = [], parameters = [];
+  for (let i = 0;i < strings.length; i++) {
+    sqlParts.push(strings[i]);
+    if (i < values.length)
+      if (values[i] && typeof values[i] === "object" && "raw" in values[i])
+        sqlParts.push(values[i].raw);
+      else {
+        sqlParts.push("?");
+        parameters.push(values[i]);
+      }
+  }
+  return {
+    sql: sqlParts.join(""),
+    parameters
+  };
+}
+sql.raw = function raw(value) {
+  return { raw: value };
+};
+sql.ref = function ref(column) {
+  return { raw: column };
+};

package/dist/unique-audit.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Walk every model file (user + framework defaults) and return the
+ * full list of declared unique constraints — both single-column
+ * `unique: true` attributes and `unique: true` composite indexes.
+ */
+export declare function getDeclaredUniques(): Promise<DeclaredUnique[]>;
+/**
+ * Query the live database for every UNIQUE index, returning a
+ * normalised `{ table, name, columns }` shape. Dialect-aware: PRAGMA
+ * on SQLite, information_schema / pg_index on MySQL / PostgreSQL.
+ *
+ * The optional `dialect` parameter is the test seam — production code
+ * leaves it undefined so it's derived from `DB_CONNECTION`.
+ */
+export declare function getLiveUniqueIndexes(dialect?: Dialect): Promise<LiveUniqueIndex[]>;
+/**
+ * Diff declared unique constraints against live UNIQUE indexes. A
+ * declared entry is satisfied iff some live unique index on the same
+ * table has an equal column SET (sorted, case-insensitive). Declared
+ * entries whose table is absent from the live DB go to `skippedTables`
+ * (feature-gated commerce/CMS models legitimately have no table yet)
+ * rather than `missing`.
+ */
+export declare function auditUniqueIndexes(dialect?: Dialect): Promise<UniqueAuditResult>;
+// stacksjs/stacks#1952 — Unique-index drift audit. Compares each
+// model's declared uniqueness (`unique: true` attributes and
+// `unique: true` composite indexes) against the UNIQUE indexes that
+// actually exist in the live database.
+//
+// This is the `buddy doctor` companion to the migrate-side self-heal
+// (#1952): `buddy migrate` already re-queues missing unique-index
+// migrations, but that only fires when you run migrate, doesn't help
+// apps scaffolded during the stub era (whose own repos carry
+// `SELECT 1;` stub migrations), and hard-fails mid-migrate on
+// pre-existing duplicate rows instead of reporting first. This audit
+// surfaces the drift read-only, before you migrate.
+//
+// Matching is by COLUMN SET, never by index name — the generator
+// emits names like `users_users_email_unique` while migration
+// filenames say `users_email_unique`, so names are not stable.
+export declare interface DeclaredUnique {
+  table: string
+  columns: string[]
+  model: string
+  source: 'attribute' | 'index'
+  indexName?: string
+}
+export declare interface LiveUniqueIndex {
+  table: string
+  name: string
+  columns: string[]
+}
+export declare interface UniqueAuditResult {
+  supported: boolean
+  declared: DeclaredUnique[]
+  live: LiveUniqueIndex[]
+  missing: DeclaredUnique[]
+  skippedTables: string[]
+}
+declare type Dialect = 'sqlite' | 'mysql' | 'postgres' | 'other';

package/dist/unique-audit.js

@@ -0,0 +1,174 @@
+import { path } from "@stacksjs/path";
+import { plural, snakeCase } from "@stacksjs/strings";
+import { safeGlob } from "./fk-audit";
+export async function getDeclaredUniques() {
+  const modelFiles = [
+    ...safeGlob(path.userModelsPath("*.ts")),
+    ...safeGlob(path.storagePath("framework/defaults/app/Models/**/*.ts"))
+  ], declared = [];
+  for (const modelFile of modelFiles) {
+    let model;
+    try {
+      model = (await import(modelFile)).default;
+    } catch {
+      continue;
+    }
+    if (!model || typeof model !== "object")
+      continue;
+    const table = model.table || plural(snakeCase(model.name || "")), modelName = model.name || "", attributes = model.attributes;
+    if (attributes && typeof attributes === "object") {
+      for (const [field, attr] of Object.entries(attributes))
+        if (attr && typeof attr === "object" && attr.unique === !0)
+          declared.push({
+            table,
+            columns: [snakeCase(field)],
+            model: modelName,
+            source: "attribute"
+          });
+    }
+    const indexes = model.indexes;
+    if (Array.isArray(indexes)) {
+      for (const index of indexes)
+        if (index && index.unique === !0 && Array.isArray(index.columns) && index.columns.length > 0)
+          declared.push({
+            table,
+            columns: index.columns.map((c) => snakeCase(c)),
+            model: modelName,
+            source: "index",
+            indexName: index.name
+          });
+    }
+  }
+  return declared;
+}
+export async function getLiveUniqueIndexes(dialect) {
+  const { db } = await import("./utils"), d = dialect ?? await currentDialect();
+  if (d === "sqlite")
+    return getSqliteLiveUniques(db);
+  if (d === "mysql")
+    return getMysqlLiveUniques(db);
+  if (d === "postgres")
+    return getPostgresLiveUniques(db);
+  return [];
+}
+export async function auditUniqueIndexes(dialect) {
+  const d = dialect ?? await currentDialect();
+  if (d !== "sqlite" && d !== "mysql" && d !== "postgres")
+    return { supported: !1, declared: [], live: [], missing: [], skippedTables: [] };
+  const declared = await getDeclaredUniques(), live = await getLiveUniqueIndexes(d), liveTables = await getLiveTables(d), liveByTable = new Map;
+  for (const idx of live) {
+    const t = idx.table.toLowerCase(), key = columnSetKey(idx.columns);
+    if (!liveByTable.has(t))
+      liveByTable.set(t, new Set);
+    liveByTable.get(t).add(key);
+  }
+  const missing = [], skippedTables = new Set;
+  for (const decl of declared) {
+    const t = decl.table.toLowerCase();
+    if (!liveTables.has(t)) {
+      skippedTables.add(decl.table);
+      continue;
+    }
+    const key = columnSetKey(decl.columns);
+    if (!(liveByTable.get(t)?.has(key) ?? !1))
+      missing.push(decl);
+  }
+  return { supported: !0, declared, live, missing, skippedTables: [...skippedTables] };
+}
+async function getLiveTables(dialect) {
+  const { db } = await import("./utils");
+  let rows = [];
+  if (dialect === "sqlite") {
+    const r = await db.unsafe("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").execute();
+    rows = (Array.isArray(r) ? r : []).map((x) => x.name);
+  } else if (dialect === "mysql") {
+    const r = await db.unsafe("SELECT TABLE_NAME AS name FROM information_schema.TABLES WHERE TABLE_SCHEMA = DATABASE()").execute();
+    rows = (Array.isArray(r) ? r : []).map((x) => x.name ?? x.TABLE_NAME);
+  } else if (dialect === "postgres") {
+    const r = await db.unsafe("SELECT tablename AS name FROM pg_tables WHERE schemaname = 'public'").execute();
+    rows = (Array.isArray(r) ? r : []).map((x) => x.name ?? x.tablename);
+  }
+  return new Set(rows.filter((n) => typeof n === "string" && n.length > 0).map((n) => n.toLowerCase()));
+}
+function columnSetKey(columns) {
+  return [...columns].map((c) => c.toLowerCase()).sort().join(",");
+}
+async function currentDialect() {
+  const driver = ((await import("@stacksjs/env")).env?.DB_CONNECTION ?? "sqlite").toLowerCase();
+  if (driver === "sqlite" || driver === "mysql" || driver === "postgres")
+    return driver;
+  return "other";
+}
+async function getSqliteLiveUniques(db) {
+  const tables = await db.unsafe("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").execute(), rows = Array.isArray(tables) ? tables : [], out = [];
+  for (const row of rows) {
+    const table = row.name;
+    if (!table)
+      continue;
+    if (!/^[a-z_]\w*$/i.test(table))
+      continue;
+    const indexRows = await db.unsafe(`PRAGMA index_list("${table}")`).execute();
+    for (const idx of Array.isArray(indexRows) ? indexRows : []) {
+      const r = idx;
+      if (Number(r.unique) !== 1 || !r.name)
+        continue;
+      if (!/^[a-z_]\w*$/i.test(r.name))
+        continue;
+      const colRows = await db.unsafe(`PRAGMA index_info("${r.name}")`).execute(), columns = (Array.isArray(colRows) ? colRows : []).map((c) => String(c.name ?? "")).filter((c) => c.length > 0);
+      if (columns.length > 0)
+        out.push({ table, name: r.name, columns });
+    }
+  }
+  return out;
+}
+async function getMysqlLiveUniques(db) {
+  const rows = await db.unsafe(`
+    SELECT TABLE_NAME, INDEX_NAME, COLUMN_NAME, SEQ_IN_INDEX
+    FROM information_schema.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND NON_UNIQUE = 0
+    ORDER BY TABLE_NAME, INDEX_NAME, SEQ_IN_INDEX
+  `).execute();
+  return groupIndexRows(Array.isArray(rows) ? rows : [], (r) => ({
+    table: String(r.TABLE_NAME ?? r.table_name ?? ""),
+    name: String(r.INDEX_NAME ?? r.index_name ?? ""),
+    column: String(r.COLUMN_NAME ?? r.column_name ?? "")
+  }));
+}
+async function getPostgresLiveUniques(db) {
+  const rows = await db.unsafe(`
+    SELECT
+      t.relname AS table_name,
+      ix.relname AS index_name,
+      a.attname AS column_name,
+      k.ord AS seq_in_index
+    FROM pg_index i
+    JOIN pg_class t ON t.oid = i.indrelid
+    JOIN pg_class ix ON ix.oid = i.indexrelid
+    JOIN pg_namespace n ON n.oid = t.relnamespace
+    JOIN LATERAL unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord) ON true
+    JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = k.attnum
+    WHERE i.indisunique = true
+      AND n.nspname = 'public'
+    ORDER BY table_name, index_name, seq_in_index
+  `).execute();
+  return groupIndexRows(Array.isArray(rows) ? rows : [], (r) => ({
+    table: String(r.table_name ?? ""),
+    name: String(r.index_name ?? ""),
+    column: String(r.column_name ?? "")
+  }));
+}
+function groupIndexRows(rows, pick) {
+  const map = new Map;
+  for (const row of rows) {
+    const { table, name, column } = pick(row);
+    if (!table || !name || !column)
+      continue;
+    const key = `${table} ${name}`, existing = map.get(key);
+    if (existing)
+      existing.columns.push(column);
+    else
+      map.set(key, { table, name, columns: [column] });
+  }
+  return [...map.values()];
+}