@stacksjs/database 0.70.87 → 0.70.88

package/dist/drivers/dynamodb.d.ts

@@ -1,200 +0,0 @@
-import type { Model } from '@stacksjs/types';
-/**
- * Marshall a JS object to DynamoDB format
- */
-declare function marshall(obj: Record<string, unknown>): DynamoItem;
-/**
- * Unmarshall a DynamoDB object to JS format
- */
-declare function unmarshall(obj: DynamoItem): Record<string, unknown>;
-/**
- * Generate key pattern for an entity
- */
-export declare function generateKeyPattern(entityName: string, idField?: string): string;
-/**
- * Parse a key pattern and extract values
- */
-export declare function parseKeyPattern(pattern: string, key: string): Record<string, string>;
-/**
- * Build a key from a pattern and values
- */
-export declare function buildKey(pattern: string, values: Record<string, string>): string;
-/**
- * Create a new DynamoDB client instance
- */
-export declare function createDynamo(): DynamoClient;
-/**
- * DynamoDB client singleton
- */
-export declare const dynamo: DynamoClient;
-/**
- * Minimal AWS-SDK `DynamoDBClient` shape — just the methods this
- * driver calls. Typed locally so callers wiring their own SDK
- * client into `setClient()` get a clear compile-time contract
- * instead of a runtime "function not found" surprise.
- */
-export declare interface DynamoSdkClient {
-  query: (req: Record<string, unknown>) => Promise<{
-    Items?: DynamoItem[]
-    Count?: number
-    ScannedCount?: number
-    LastEvaluatedKey?: DynamoItem
-  }>
-  scan: (req: Record<string, unknown>) => Promise<{
-    Items?: DynamoItem[]
-    Count?: number
-    ScannedCount?: number
-    LastEvaluatedKey?: DynamoItem
-  }>
-  getItem: (req: Record<string, unknown>) => Promise<{ Item?: DynamoItem }>
-  putItem: (req: Record<string, unknown>) => Promise<unknown>
-  deleteItem: (req: Record<string, unknown>) => Promise<unknown>
-  updateItem: (req: Record<string, unknown>) => Promise<unknown>
-  batchWriteItem: (req: Record<string, unknown>) => Promise<unknown>
-  transactWriteItems: (req: Record<string, unknown>) => Promise<unknown>
-}
-/**
- * DynamoDB connection configuration
- */
-export declare interface DynamoConnectionConfig {
-  region: string
-  table: string
-  endpoint?: string
-  credentials?: {
-    accessKeyId: string
-    secretAccessKey: string
-    sessionToken?: string
-  }
-  pkAttribute?: string
-  skAttribute?: string
-  entityTypeAttribute?: string
-  keyDelimiter?: string
-}
-/**
- * Entity mapping for single-table design
- */
-export declare interface SingleTableEntityMapping {
-  entityType: string
-  pkPattern: string
-  skPattern?: string
-  gsi1pk?: string
-  gsi1sk?: string
-  gsi2pk?: string
-  gsi2sk?: string
-}
-/**
- * Sort key builder for fluent API
- */
-export declare interface SortKeyBuilder {
-  equals(value: string): EntityQueryBuilder
-  beginsWith(prefix: string): EntityQueryBuilder
-  between(start: string, end: string): EntityQueryBuilder
-  lt(value: string): EntityQueryBuilder
-  lte(value: string): EntityQueryBuilder
-  gt(value: string): EntityQueryBuilder
-  gte(value: string): EntityQueryBuilder
-}
-/**
- * Batch write operation
- */
-export declare interface BatchWriteOperation {
-  put?: { entity: string, item: Record<string, unknown> }
-  delete?: { entity: string, pk: string, sk: string }
-}
-/**
- * Transact write operation
- */
-export declare interface TransactWriteOperation {
-  put?: { entity: string, item: Record<string, unknown>, condition?: string }
-  update?: { entity: string, pk: string, sk?: string, set?: Record<string, unknown>, add?: Record<string, number>, remove?: string[] }
-  delete?: { entity: string, pk: string, sk: string, condition?: string }
-  conditionCheck?: { entity: string, pk: string, sk: string, condition: string }
-}
-/**
- * Query result
- */
-export declare interface QueryResult<T = unknown> {
-  items: T[]
-  count: number
-  scannedCount?: number
-  lastKey?: Record<string, unknown>
-}
-/**
- * DynamoDB AttributeValue discriminated union (stacksjs/stacks#1894 T-8).
- *
- * Mirrors the wire format AWS SDK's `DynamoDBClient` produces and
- * consumes, declared locally so this package doesn't take a hard
- * dependency on `@aws-sdk/client-dynamodb` just for its types. Each
- * concrete variant carries its own typed payload; consumers narrow
- * via `'S' in attr` / etc.
- *
- * Why not just import from AWS SDK: the framework's DynamoDB driver
- * ships as an optional peer integration. Pulling AWS SDK as a type-
- * level dep would force every Stacks app to install it whether or
- * not they use the driver.
- */
-export type DynamoAttributeValue = | { S: string }
-  | { N: string }
-  | { B: Uint8Array | string }
-  | { BOOL: boolean }
-  | { NULL: true }
-  | { L: DynamoAttributeValue[] }
-  | { M: Record<string, DynamoAttributeValue> }
-  | { SS: string[] }
-  | { NS: string[] }
-  | { BS: Array<Uint8Array | string> }
-/** Marshalled item — the on-the-wire representation. */
-export type DynamoItem = Record<string, DynamoAttributeValue>;
-/**
- * Entity-centric query builder for DynamoDB
- */
-export declare class EntityQueryBuilder<T = unknown> {
-  constructor(client: DynamoSdkClient | undefined, tableName: string, config: { pkAttribute: string, skAttribute: string, entityTypeAttribute: string, keyDelimiter: string });
-  entity(entityType: string): this;
-  pk(value: string): this;
-  get sk(): SortKeyBuilder;
-  index(indexName: string): this;
-  project(...attributes: string[]): this;
-  filter(attribute: string, operator: string, value?: unknown): this;
-  where(attribute: string, value: unknown): this;
-  whereIn(attribute: string, values: unknown[]): this;
-  limit(count: number): this;
-  asc(): this;
-  desc(): this;
-  consistent(): this;
-  startFrom(key: Record<string, unknown>): this;
-  toRequest(): Record<string, unknown>;
-  get(): Promise<T[]>;
-  first(): Promise<T | undefined>;
-  getAll(): Promise<T[]>;
-  count(): Promise<number>;
-}
-/**
- * DynamoDB client with entity-centric API
- */
-declare class DynamoClient {
-  connection(config: DynamoConnectionConfig): this;
-  isConfigured(): boolean;
-  setClient(client: DynamoSdkClient): this;
-  getClient(): DynamoSdkClient | undefined;
-  registerEntity(mapping: SingleTableEntityMapping): this;
-  registerModel(model: Model): this;
-  getEntityMapping(entityType: string): SingleTableEntityMapping | undefined;
-  entity<T = any>(entityType: string): EntityQueryBuilder<T>;
-  batchWrite(operations: BatchWriteOperation[]): Promise<void>;
-  transactWrite(operations: TransactWriteOperation[]): Promise<void>;
-  put(entity: string, item: Record<string, unknown>): Promise<void>;
-  get<T = any>(pk: string, sk?: string): Promise<T | undefined>;
-  delete(pk: string, sk?: string): Promise<void>;
-  update(pk: string, sk: string | undefined, updates: Record<string, unknown>): Promise<void>;
-  getTableName(): string;
-  getConfig(): {
-    tableName: string
-    pkAttribute: string
-    skAttribute: string
-    entityTypeAttribute: string
-    keyDelimiter: string
-  };
-}
-// Export marshall/unmarshall utilities
-export { marshall, unmarshall };

package/dist/drivers/helpers.d.ts

@@ -1,35 +0,0 @@
-import type { Attribute, AttributesElements, Model } from '@stacksjs/types';
-import type { DateValidatorType, EnumValidatorType, NumberValidatorType, StringValidatorType, ValidationType } from '@stacksjs/ts-validation';
-export declare function deleteMigrationFiles(): Promise<void>;
-export declare function deleteFrameworkModels(): Promise<void>;
-export declare function getLastMigrationFields(modelName: string): Promise<AttributesElements>;
-export declare function modelTableName(model: Model | string): Promise<string>;
-export declare function hasTableBeenMigrated(tableName: string): Promise<boolean>;
-export declare function hasMigrationBeenCreated(tableName: string): Promise<boolean>;
-export declare function getExecutedMigrations(): Promise<{ name: string }[]>;
-export declare function prepareTextColumnType(validator: StringValidatorType, driver?: string): string;
-// Add new function for date/time column types
-export declare function prepareDateTimeColumnType(validator: DateValidatorType, driver?: string): string;
-export declare function compareRanges(range1: Range, range2: Range): boolean;
-export declare function checkPivotMigration(dynamicPart: string): Promise<boolean>;
-export declare function pluckChanges(array1: string[], array2: string[]): { added: string[], removed: string[] } | null;
-export declare function arrangeColumns(attributes: AttributesElements | undefined): Array<[string, Attribute]>;
-export declare function isArrayEqual(arr1: (number | undefined)[], arr2: (number | undefined)[]): boolean;
-export declare function findDifferingKeys(obj1: any, obj2: any): { key: string, max: number, min: number }[];
-export declare function fetchTables(): Promise<string[]>;
-export declare function getUpvoteTableName(model: Model, tableName: string): string | undefined;
-/**
- * Foreign-key column of the likes pivot. MUST mirror the runtime default in
- * orm/src/traits/likeable.ts (`${tableName.replace(/s$/, '')}_id`) — a pivot
- * generated with any other column name is a table `like()` cannot write to.
- */
-export declare function getLikeableForeignKey(model: Model, tableName: string): string;
-export declare function prepareNumberColumnType(validator: NumberValidatorType, driver?: string): string;
-// Add new function for enum column types
-export declare function prepareEnumColumnType(validator: EnumValidatorType, driver?: string): string;
-export declare function mapFieldTypeToColumnType(validator: ValidationType, driver?: string): string;
-export declare function checkIsRequired(rule: string): boolean;
-declare interface Range {
-  min: number
-  max: number
-}

package/dist/drivers/index.d.ts

@@ -1,16 +0,0 @@
-/**
- * Drivers — barrel export.
- *
- * Helpers shared across driver implementations live in `./helpers.ts` (NOT
- * inline here) so driver modules can import them without re-importing this
- * barrel and triggering a self-cycle. See `./helpers.ts` for the rationale.
- */
-export * from './helpers';
-export * from './mysql';
-export * from './postgres';
-export * from './sqlite';
-export { generateIndexCreationSQL } from './mysql';
-export { generateIndexCreationSQL as generatePostgresIndexCreationSQL } from './postgres';
-export { generateIndexCreationSQL as generateSqliteIndexCreationSQL } from './sqlite';
-export * from './defaults/index';
-export * from './dynamodb';

package/dist/drivers/mysql.d.ts

@@ -1,7 +0,0 @@
-import type { Ok } from '@stacksjs/error-handling';
-export declare function resetMysqlDatabase(): Promise<Ok<string, never>>;
-export declare function dropMysqlTables(): Promise<void>;
-export declare function generateMysqlMigration(modelPath: string): Promise<void>;
-export declare function generateMysqlTraitMigrations(): Promise<void>;
-export declare function createAlterTableMigration(modelPath: string): Promise<void>;
-export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;

package/dist/drivers/postgres.d.ts

@@ -1,7 +0,0 @@
-import type { Ok } from '@stacksjs/error-handling';
-export declare function dropPostgresTables(): Promise<void>;
-export declare function generatePostgresTraitMigrations(): Promise<void>;
-export declare function resetPostgresDatabase(): Promise<Ok<string, never>>;
-export declare function generatePostgresMigration(modelPath: string): Promise<void>;
-export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;
-export declare function fetchPostgresTables(): Promise<string[]>;

package/dist/drivers/sqlite.d.ts

@@ -1,20 +0,0 @@
-import type { Ok } from '@stacksjs/error-handling';
-export declare function resetSqliteDatabase(): Promise<Ok<string, never>>;
-/**
- * Configure SQLite for the Stacks workload. Idempotent — the pragmas are
- * cheap to re-apply, but each one is a no-op once set so repeated calls
- * during dev hot-reload don't accumulate state.
- *
- * Connection bootstrap now applies SQLITE_BOOTSTRAP_PRAGMAS automatically
- * inside @stacksjs/query-builder's wrapped `createQueryBuilder`
- * (stacksjs/stacks#1951); this export remains for explicit re-application.
- * See the shared list in @stacksjs/query-builder for what each pragma does
- * and why it must be set per connection.
- */
-export declare function configureSqlitePragmas(): Promise<void>;
-export declare function dropSqliteTables(): Promise<void>;
-export declare function fetchSqliteFile(): string;
-export declare function fetchTestSqliteFile(): string;
-export declare function generateSqliteMigration(modelPath: string): Promise<void>;
-export declare function copyModelFiles(modelPath: string): Promise<void>;
-export declare function generateIndexCreationSQL(tableName: string, index: { name: string, columns: string[], unique?: boolean, where?: string }): string;

package/dist/factory.d.ts

@@ -1,41 +0,0 @@
-import type { Attribute, Model } from '@stacksjs/types';
-import type { SeedResult } from './seeder';
-/**
- * Build the internal `SeederModel`-shaped payload that `seedModelDirect`
- * expects from a public-API call. Pure function — exported separately
- * so tests can assert the override-precedence rules without touching
- * the database.
- *
- * Precedence (lowest → highest): per-attribute `factory` output →
- * global `options.with` → per-row `options.rows[i]`. All keys are
- * snake-cased before insert so callers can use the model's camelCase
- * attribute names without thinking about column naming.
- */
-export declare function buildSeederPayload(modelInput: unknown, options?: GenerateOptions): {
-  name: string
-  table: string
-  count: number
-  fixtures: Array<Record<string, unknown>>
-  attributes: Record<string, Attribute>
-  model: Model
-};
-/**
- * Generate factory rows for a model and insert them. Designed to be
- * called from a class seeder.
- *
- * Honours the model's per-attribute `factory: faker => …` declarations
- * — exactly the same code path as the legacy auto-walker — but without
- * the implicit "every model with `useSeeder` fires on every run"
- * coupling. See stacksjs/stacks#1919 for the rationale.
- */
-export declare function generate(modelInput: unknown, options?: GenerateOptions): Promise<SeedResult>;
-export declare const factory: {
-  generate: typeof generate
-};
-export declare interface GenerateOptions {
-  count?: number
-  fresh?: boolean
-  verbose?: boolean
-  with?: Record<string, unknown>
-  rows?: Array<Record<string, unknown>>
-}

package/dist/fk-audit.d.ts

@@ -1,101 +0,0 @@
-/**
- * Glob, but resilient to "directory doesn't exist yet" (the userland
- * `app/Models/` directory in particular often doesn't exist when the
- * audit runs in framework tests or scaffolded apps that haven't
- * created any models yet). Avoids the Bun Glob ENOENT.
- */
-export declare function safeGlob(pattern: string): string[];
-/**
- * Walk every model file (user + framework defaults) and return the
- * full list of declared `belongsTo` foreign keys.
- *
- * Convention: `Comment` with `belongsTo: ['Post']` implies the FK
- * `comments.post_id → posts.id`. Same shape the migration generator
- * uses, so we keep it consistent here. Other relationship types
- * (`hasOne`, `hasMany`, `belongsToMany` through tables) imply FKs in
- * the *other* direction or in pivot tables — we only check
- * `belongsTo` here for the simplest, highest-signal audit.
- */
-export declare function getDeclaredFKs(): Promise<DeclaredFK[]>;
-/**
- * Query the live database for every foreign key constraint, returning
- * a normalised shape. Dialect-aware: PRAGMA on SQLite,
- * information_schema on MySQL / PostgreSQL.
- */
-export declare function getLiveFKs(): Promise<LiveFK[]>;
-/**
- * Diff declared FKs against live FKs. Returns the declared FKs that
- * have no matching row in the live database — these are the silent
- * "FK should be enforcing referential integrity but isn't" cases that
- * motivated this audit.
- *
- * Match key is `fromTable.fromColumn → toTable.toColumn` (case-
- * insensitive). Extra live FKs (present in DB but not in any model)
- * are not reported — those usually come from manual migrations or
- * external tooling, both legitimate.
- */
-export declare function auditForeignKeys(): Promise<FkAuditResult>;
-/**
- * Scan the live database for rows whose foreign key references a
- * parent row that doesn't exist. SQLite's `PRAGMA foreign_key_check`
- * does this regardless of the `foreign_keys` pragma state and excludes
- * NULL-FK rows. The violating column is resolved by joining the
- * reported `fkid` against `PRAGMA foreign_key_list(table)`.
- */
-export declare function findFkOrphans(dialect?: 'sqlite' | 'mysql' | 'postgres' | 'other'): Promise<FkOrphanReport>;
-// stacksjs/stacks#1916 — Foreign-key audit. Compares each model's
-// declared `belongsTo` relationships against the FKs that actually
-// exist in the live database. Drives `buddy doctor`'s FK integrity
-// check, surfaces the "you flipped DB_CONNECTION but the FKs didn't
-// follow" failure mode that motivated #1915 and #1916.
-//
-// Two halves:
-//
-//   1. Declared FKs: walk model files, look at `belongsTo`, compute
-//      the implied FK shape `{ fromTable, fromColumn, toTable,
-//      toColumn }`. Convention is `<related>_id` → `<related>.id`,
-//      same as the migration generator.
-//
-//   2. Live FKs: query the live database. SQLite via
-//      `PRAGMA foreign_key_list("…")`, MySQL/Postgres via
-//      `information_schema.key_column_usage`.
-export declare interface DeclaredFK {
-  fromTable: string
-  fromColumn: string
-  toTable: string
-  toColumn: string
-  model: string
-}
-export declare interface LiveFK {
-  fromTable: string
-  fromColumn: string
-  toTable: string
-  toColumn: string
-}
-export declare interface FkAuditResult {
-  declared: DeclaredFK[]
-  live: LiveFK[]
-  missing: DeclaredFK[]
-}
-// stacksjs/stacks#1951 — FK orphan detection. FK enforcement flipped
-// ON (utils.ts bootstrap pragmas) against databases that were written
-// while `foreign_keys = OFF`, so legacy rows can reference parents that
-// no longer exist. Those orphans silently turn previously-working
-// deletes/inserts into runtime FK failures. This READ-ONLY scan finds
-// them so `buddy doctor` can report before they bite.
-//
-// SQLite-specific: MySQL/Postgres enforce FKs natively, so the
-// FK-off-legacy-data failure mode can't arise there — we degrade to
-// `supported: false` rather than run an expensive per-FK anti-join.
-export declare interface FkOrphan {
-  table: string
-  column: string
-  parent: string
-  count: number
-  sampleRowids: number[]
-}
-export declare interface FkOrphanReport {
-  supported: boolean
-  total: number
-  orphans: FkOrphan[]
-}

package/dist/index.d.ts

@@ -1,149 +0,0 @@
-export type {
-  DatabaseConnectionConfig,
-  DatabaseOptions,
-} from './database';
-export type {
-  DatabaseConnections,
-  DynamoDbConfig,
-  FullDatabaseConfig,
-  MysqlConfig,
-  PostgresConfig,
-  SqliteConfig,
-} from './driver-config';
-export type { GenerateOptions } from './factory';
-export type { ScaffoldOptions, ScaffoldResult } from './seed-scaffold';
-export type { DeclaredFK, FkAuditResult, FkOrphan, FkOrphanReport, LiveFK } from './fk-audit';
-export type { DeclaredUnique, LiveUniqueIndex, UniqueAuditResult } from './unique-audit';
-export type {
-  QueryBuilder,
-  QueryBuilderConfig,
-  Seeder as QueryBuilderSeeder,
-  SupportedDialect,
-} from '@stacksjs/query-builder';
-export type {
-  DynamoConnectionConfig,
-  SingleTableEntityMapping,
-  SortKeyBuilder,
-  BatchWriteOperation,
-  TransactWriteOperation,
-  QueryResult,
-} from './drivers/dynamodb';
-/**
- * @stacksjs/database
- *
- * Database module powered by bun-query-builder.
- * Provides database initialization, driver configuration, migrations,
- * seeding, and a fluent query builder interface.
- *
- * @example
- * ```ts
- * import { Database, db, createSqliteDatabase } from '@stacksjs/database'
- *
- * // Use the default db instance (configured from environment)
- * const users = await db.selectFrom('users').where('active', '=', true).get()
- *
- * // Or create a custom database instance
- * const customDb = new Database({
- *   driver: 'postgres',
- *   connection: {
- *     database: 'myapp',
- *     host: 'localhost',
- *     port: 5432,
- *     username: 'postgres',
- *     password: 'secret'
- *   }
- * })
- *
- * // Helper functions for quick setup
- * const sqliteDb = createSqliteDatabase('database/app.sqlite')
- * ```
- */
-// Database initialization and management
-export {
-  Database,
-  createDatabase,
-  createMysqlDatabase,
-  createPostgresDatabase,
-  createSqliteDatabase,
-} from './database';
-// Driver configuration
-export {
-  detectDriver,
-  driverDefaults,
-  getConfigFromEnv,
-  getConnectionString,
-  mergeWithDefaults,
-  validateDriverConfig,
-} from './driver-config';
-// Core database utilities and default instance
-export * from './utils';
-// Types (compatibility layer for Kysely types)
-export * from './types';
-// Migrations
-export * from './migrations';
-// Query logger DI hook (router calls setQueryTracker on init)
-export { setQueryTracker, logQuery } from './query-logger';
-// Class-based seeders (supplements the model-attribute auto-seeder)
-export { Seeder, runClassSeeders } from './class-seeder';
-// Zero-downtime migration helpers
-export { addColumnSafely, backfillInBatches, renameColumnSafely } from './safe-migrations';
-// Seeding
-export * from './seeder';
-// stacksjs/stacks#1919 — public factory API. The canonical replacement
-// for the legacy `useSeeder` trait + auto-walker. Class seeders call
-// `factory.generate(Model, opts)` explicitly so there's one
-// orchestration layer per table, no double-fire on tables that have
-// both a `useSeeder` trait and a class seeder file.
-export { factory, generate as factoryGenerate } from './factory';
-// `buddy seed:scaffold` codemod — generates class-seeder files for
-// every model with a `useSeeder` trait, easing the migration off the
-// auto-walker.
-export { scaffoldClassSeedersFromModels, renderSeederFile } from './seed-scaffold';
-// Driver utilities
-export * from './drivers/index';
-// Custom migrations (jobs, errors, etc.)
-export * from './custom/index';
-// Auth tables migration
-export * from './auth-tables';
-// uuid column guarantee for `useUuid` models (stacksjs/status#1 Phase 9)
-export * from './uuid-columns';
-// Notification tables migration (stacksjs/stacks#1937)
-export { migrateNotificationTables } from './notification-tables';
-// RBAC tables migration (stacksjs/stacks#1941 Phase A)
-export { migrateRbacTables } from './rbac-tables';
-// SQL dialect helpers & connection defaults
-export * from './sql-helpers';
-export * from './defaults';
-// Foreign-key audit (stacksjs/stacks#1916) — compare declared
-// `belongsTo` relationships against live FKs.
-export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from './fk-audit';
-// Unique-index drift audit (stacksjs/stacks#1952) — compare declared
-// `unique: true` attributes / indexes against live UNIQUE indexes.
-export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from './unique-audit';
-// Transaction context: AsyncLocalStorage-based scope so side-effect
-// emitters (queue dispatch, mailer send) can buffer themselves
-// until the surrounding `db.transaction(...)` commits
-// (stacksjs/stacks#1882).
-export {
-  __flushAfterCommitNow,
-  __pendingAfterCommitCount,
-  enqueueAfterCommit,
-  isInTransaction,
-  runInTransactionScope,
-} from './transaction-context';
-// Re-export bun-query-builder functions and types
-export {
-  createQueryBuilder,
-  setConfig,
-} from '@stacksjs/query-builder';
-// DynamoDB entity-centric API
-export {
-  createDynamo,
-  dynamo,
-  EntityQueryBuilder,
-  generateKeyPattern,
-  parseKeyPattern,
-  buildKey,
-  marshall,
-  unmarshall,
-} from './drivers/dynamodb';