@strav/database 0.1.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@strav/database",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Database layer for the Strav framework — query builder, ORM, schema builder, and migrations",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "framework",
+    "typescript",
+    "strav",
+    "database",
+    "orm"
+  ],
+  "files": [
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./database": "./src/database/index.ts",
+    "./database/*": "./src/database/*.ts",
+    "./orm": "./src/orm/index.ts",
+    "./orm/*": "./src/orm/*.ts",
+    "./schema": "./src/schema/index.ts",
+    "./schema/*": "./src/schema/*.ts",
+    "./helpers": "./src/helpers/index.ts",
+    "./helpers/*": "./src/helpers/*.ts",
+    "./providers": "./src/providers/index.ts",
+    "./providers/*": "./src/providers/*.ts"
+  },
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0"
+  },
+  "dependencies": {
+    "@types/luxon": "^3.7.1",
+    "luxon": "^3.7.2",
+    "reflect-metadata": "^0.2.2"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/database/database.ts

@@ -0,0 +1,181 @@
+import { SQL } from 'bun'
+import Configuration from '@stravigor/kernel/config/configuration'
+import { inject } from '@stravigor/kernel/core/inject'
+import { ConfigurationError } from '@stravigor/kernel/exceptions/errors'
+import { env } from '@stravigor/kernel/helpers/env'
+import { createSchemaAwareSQL } from './domain/wrapper'
+import { getCurrentSchema, hasSchemaContext } from './domain/context'
+
+/**
+ * Database connection wrapper backed by {@link SQL Bun.sql}.
+ *
+ * Reads connection credentials from the `database.*` configuration keys
+ * (loaded from `config/database.ts` / `.env`). Falls back to reading
+ * `DB_*` environment variables directly when no config file is present.
+ *
+ * Register as a singleton in the DI container so a single connection pool
+ * is shared across the application.
+ *
+ * @example
+ * container.singleton(Configuration)
+ * container.singleton(Database)
+ * const db = container.resolve(Database)
+ * const rows = await db.sql`SELECT 1 AS result`
+ */
+@inject
+export default class Database {
+  private static _connection: SQL | null = null
+  private static _schemaConnection: SQL | null = null
+  private connection: SQL
+  private schemaConnection: SQL
+  private multiSchemaEnabled: boolean
+
+  constructor(protected config: Configuration) {
+    // Close any previously orphaned connection (e.g. from hot reload)
+    if (Database._connection) {
+      Database._connection.close()
+    }
+    if (Database._schemaConnection) {
+      Database._schemaConnection = null
+    }
+
+    this.connection = new SQL({
+      hostname: config.get('database.host') ?? env('DB_HOST', '127.0.0.1'),
+      port: config.get('database.port') ?? env.int('DB_PORT', 5432),
+      username: config.get('database.username') ?? env('DB_USER', 'postgres'),
+      password: config.get('database.password') ?? env('DB_PASSWORD', ''),
+      database: config.get('database.database') ?? env('DB_DATABASE', 'strav'),
+      max: config.get('database.pool') ?? env.int('DB_POOL_MAX', 10),
+      idleTimeout: config.get('database.idleTimeout') ?? env.int('DB_IDLE_TIMEOUT', 20),
+    })
+    Database._connection = this.connection
+
+    // Check if multi-schema mode is enabled
+    this.multiSchemaEnabled = config.get('database.multiSchema.enabled') ?? false
+
+    // Create schema-aware wrapper if multi-schema is enabled
+    if (this.multiSchemaEnabled) {
+      this.schemaConnection = createSchemaAwareSQL(this.connection)
+      Database._schemaConnection = this.schemaConnection
+    } else {
+      this.schemaConnection = this.connection
+      Database._schemaConnection = this.connection
+    }
+  }
+
+  /** The underlying Bun SQL tagged-template client. */
+  get sql(): SQL {
+    // Return schema-aware connection if in schema context and multi-schema is enabled
+    if (this.multiSchemaEnabled && hasSchemaContext()) {
+      return this.createSchemaConnection()
+    }
+    return this.connection
+  }
+
+  /** Create a schema-specific connection with search_path set */
+  private createSchemaConnection(): SQL {
+    const schema = getCurrentSchema()
+    const baseConn = this.connection
+
+    // Create a proxy that sets search_path before each query
+    return new Proxy(baseConn, {
+      get(target, prop) {
+        const value = Reflect.get(target, prop)
+
+        // Intercept 'unsafe' method to inject search_path
+        if (prop === 'unsafe') {
+          return async function(sql: string, params?: any[]) {
+            // For queries that should not be prefixed (like SET commands)
+            if (sql.trim().toUpperCase().startsWith('SET')) {
+              return target.unsafe(sql, params)
+            }
+
+            // Execute with search_path set
+            const searchPathSql = `SET search_path TO "${schema}", public`
+            await target.unsafe(searchPathSql)
+            return target.unsafe(sql, params)
+          }
+        }
+
+        // Handle tagged template function
+        if (typeof value === 'function') {
+          return value.bind(target)
+        }
+
+        return value
+      },
+
+      // Handle tagged template literals
+      apply(target, thisArg, argArray) {
+        return (async () => {
+          const schema = getCurrentSchema()
+          await target.unsafe(`SET search_path TO "${schema}", public`)
+          return Reflect.apply(target as any, thisArg, argArray)
+        })()
+      },
+    }) as SQL
+  }
+
+  /** The global SQL connection, available after DI bootstrap. */
+  static get raw(): SQL {
+    if (!Database._connection) {
+      throw new ConfigurationError(
+        'Database not configured. Resolve Database through the container first.'
+      )
+    }
+
+    // Return schema-aware connection if available and in schema context
+    if (Database._schemaConnection && hasSchemaContext()) {
+      const schema = getCurrentSchema()
+      const baseConn = Database._connection
+
+      // Create inline schema-aware proxy
+      return new Proxy(baseConn, {
+        get(target, prop) {
+          const value = Reflect.get(target, prop)
+
+          if (prop === 'unsafe') {
+            return async function(sql: string, params?: any[]) {
+              if (sql.trim().toUpperCase().startsWith('SET')) {
+                return target.unsafe(sql, params)
+              }
+              await target.unsafe(`SET search_path TO "${schema}", public`)
+              return target.unsafe(sql, params)
+            }
+          }
+
+          if (typeof value === 'function') {
+            return value.bind(target)
+          }
+
+          return value
+        },
+
+        apply(target, thisArg, argArray) {
+          return (async () => {
+            await target.unsafe(`SET search_path TO "${schema}", public`)
+            return Reflect.apply(target as any, thisArg, argArray)
+          })()
+        },
+      }) as SQL
+    }
+
+    return Database._connection
+  }
+
+  /** Close the connection pool. */
+  async close(): Promise<void> {
+    await this.connection.close()
+    if (Database._connection === this.connection) {
+      Database._connection = null
+    }
+    if (Database._schemaConnection) {
+      Database._schemaConnection = null
+    }
+  }
+
+  /** Check if multi-schema mode is enabled */
+  get isMultiSchema(): boolean {
+    return this.multiSchemaEnabled
+  }
+}

package/src/database/domain/context.ts

@@ -0,0 +1,84 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+/**
+ * Schema context for multi-domain database operations.
+ * Stores the current domain's PostgreSQL schema name.
+ */
+export interface SchemaContext {
+  /** The PostgreSQL schema name for the current domain */
+  schema: string
+  /** Whether to bypass schema isolation (for admin/global operations) */
+  bypass?: boolean
+}
+
+/**
+ * AsyncLocalStorage for schema context.
+ * Automatically propagates schema context through async operations.
+ */
+export const schemaStorage = new AsyncLocalStorage<SchemaContext>()
+
+/**
+ * Execute a function within a schema context.
+ * All database operations within the callback will use the specified schema.
+ *
+ * @example
+ * // In HTTP middleware
+ * await withSchema('company_123', async () => {
+ *   // All queries here automatically use company_123 schema
+ *   const users = await User.all()
+ *   const orders = await query(Order).where('status', 'pending').all()
+ * })
+ *
+ * @example
+ * // In background jobs
+ * await withSchema(job.domainId, async () => {
+ *   await processInvoices()
+ * })
+ */
+export async function withSchema<T>(
+  schema: string,
+  callback: () => T | Promise<T>
+): Promise<T> {
+  return schemaStorage.run({ schema }, callback)
+}
+
+/**
+ * Execute a function with schema isolation bypassed.
+ * Useful for admin operations that need to access all schemas.
+ *
+ * @example
+ * await withoutSchema(async () => {
+ *   // Query runs without schema restriction
+ *   await db.sql`SELECT * FROM information_schema.schemata`
+ * })
+ */
+export async function withoutSchema<T>(
+  callback: () => T | Promise<T>
+): Promise<T> {
+  return schemaStorage.run({ schema: 'public', bypass: true }, callback)
+}
+
+/**
+ * Get the current schema context.
+ * Returns null if not within a schema context.
+ */
+export function getCurrentSchemaContext(): SchemaContext | null {
+  return schemaStorage.getStore() ?? null
+}
+
+/**
+ * Get the current schema name.
+ * Returns 'public' if not within a schema context.
+ */
+export function getCurrentSchema(): string {
+  const context = getCurrentSchemaContext()
+  return context?.bypass ? 'public' : (context?.schema ?? 'public')
+}
+
+/**
+ * Check if currently running within a schema context.
+ */
+export function hasSchemaContext(): boolean {
+  const context = getCurrentSchemaContext()
+  return context !== null && !context.bypass
+}

package/src/database/domain/index.ts

@@ -0,0 +1,17 @@
+export {
+  type SchemaContext,
+  schemaStorage,
+  withSchema,
+  withoutSchema,
+  getCurrentSchemaContext,
+  getCurrentSchema,
+  hasSchemaContext,
+} from './context'
+
+export { SchemaManager } from './manager'
+
+export {
+  createSchemaAwareSQL,
+  setSearchPath,
+  resetSearchPath,
+} from './wrapper'

package/src/database/domain/manager.ts

@@ -0,0 +1,274 @@
+import type { SQL } from 'bun'
+import Database from '../database'
+import MigrationRunner from '../migration/runner'
+import MigrationTracker from '../migration/tracker'
+import { withSchema, withoutSchema } from './context'
+import { inject } from '@stravigor/kernel/core/inject'
+
+/**
+ * Schema manager for multi-domain database operations.
+ * Handles schema creation, deletion, and migrations per domain.
+ */
+@inject
+export class SchemaManager {
+  private db: SQL
+  private database: Database
+
+  constructor(database: Database) {
+    this.database = database
+    this.db = database.sql
+  }
+
+  /**
+   * Create a new schema for a domain.
+   *
+   * @example
+   * const manager = container.resolve(SchemaManager)
+   * await manager.createSchema('company_123')
+   */
+  async createSchema(schema: string): Promise<void> {
+    await withoutSchema(async () => {
+      // Validate schema name (prevent SQL injection)
+      if (!/^[a-z0-9_]+$/.test(schema)) {
+        throw new Error(`Invalid schema name: ${schema}. Only lowercase letters, numbers, and underscores are allowed.`)
+      }
+
+      // Create the schema
+      await this.db.unsafe(`CREATE SCHEMA IF NOT EXISTS "${schema}"`)
+
+      // Grant permissions to the current user
+      const currentUser = await this.getCurrentUser()
+      if (currentUser) {
+        await this.db.unsafe(`GRANT ALL ON SCHEMA "${schema}" TO "${currentUser}"`)
+      }
+    })
+  }
+
+  /**
+   * Delete a domain's schema and all its data.
+   * USE WITH CAUTION - This is irreversible!
+   *
+   * @example
+   * await manager.deleteSchema('company_123')
+   */
+  async deleteSchema(schema: string): Promise<void> {
+    await withoutSchema(async () => {
+      // Validate schema name
+      if (!/^[a-z0-9_]+$/.test(schema)) {
+        throw new Error(`Invalid schema name: ${schema}`)
+      }
+
+      // Don't allow deletion of system schemas
+      if (['public', 'pg_catalog', 'information_schema'].includes(schema)) {
+        throw new Error(`Cannot delete system schema: ${schema}`)
+      }
+
+      // Drop the schema and all objects within it
+      await this.db.unsafe(`DROP SCHEMA IF EXISTS "${schema}" CASCADE`)
+    })
+  }
+
+  /**
+   * Check if a schema exists.
+   *
+   * @example
+   * const exists = await manager.schemaExists('company_123')
+   */
+  async schemaExists(schema: string): Promise<boolean> {
+    const result = await withoutSchema(async () => {
+      return this.db.unsafe(
+        `SELECT EXISTS (
+          SELECT 1 FROM information_schema.schemata
+          WHERE schema_name = $1
+        ) as exists`,
+        [schema]
+      )
+    })
+
+    return result[0]?.exists ?? false
+  }
+
+  /**
+   * List all domain schemas (excluding system schemas).
+   *
+   * @example
+   * const schemas = await manager.listSchemas()
+   * console.log(schemas) // ['company_123', 'factory_456']
+   */
+  async listSchemas(): Promise<string[]> {
+    const result = await withoutSchema(async () => {
+      return this.db.unsafe(`
+        SELECT schema_name
+        FROM information_schema.schemata
+        WHERE schema_name NOT IN ('public', 'pg_catalog', 'information_schema', 'pg_toast')
+          AND schema_name NOT LIKE 'pg_%'
+        ORDER BY schema_name
+      `)
+    })
+
+    return result.map((row: any) => row.schema_name)
+  }
+
+  /**
+   * Run migrations for a specific schema.
+   *
+   * @example
+   * await manager.migrateSchema('company_123')
+   */
+  async migrateSchema(schema: string, migrationsPath: string = 'database/migrations/domains'): Promise<void> {
+    await withSchema(schema, async () => {
+      const tracker = new MigrationTracker(this.database, 'domains')
+      const runner = new MigrationRunner(this.database, tracker, migrationsPath, 'domains')
+      await runner.run()
+    })
+  }
+
+  /**
+   * Run migrations for all schemas.
+   *
+   * @example
+   * await manager.migrateAllSchemas()
+   */
+  async migrateAllSchemas(migrationsPath?: string): Promise<void> {
+    const schemas = await this.listSchemas()
+
+    for (const schema of schemas) {
+      console.log(`Migrating schema: ${schema}`)
+      await this.migrateSchema(schema, migrationsPath)
+    }
+  }
+
+  /**
+   * Copy schema structure from one schema to another.
+   * Useful for creating new domains with the same structure.
+   *
+   * @example
+   * await manager.cloneSchema('public', 'company_123')
+   */
+  async cloneSchema(sourceSchema: string, targetSchema: string): Promise<void> {
+    await withoutSchema(async () => {
+      // Validate schema names
+      if (!/^[a-z0-9_]+$/.test(sourceSchema) || !/^[a-z0-9_]+$/.test(targetSchema)) {
+        throw new Error('Invalid schema name')
+      }
+
+      // Create target schema
+      await this.createSchema(targetSchema)
+
+      // Get all tables from source schema
+      const tables = await this.db.unsafe(`
+        SELECT tablename
+        FROM pg_tables
+        WHERE schemaname = $1
+      `, [sourceSchema])
+
+      // Copy each table structure (without data)
+      for (const { tablename } of tables as Array<{ tablename: string }>) {
+        await this.db.unsafe(`
+          CREATE TABLE "${targetSchema}"."${tablename}"
+          (LIKE "${sourceSchema}"."${tablename}" INCLUDING ALL)
+        `)
+      }
+
+      // Copy sequences
+      const sequences = await this.db.unsafe(`
+        SELECT sequence_name
+        FROM information_schema.sequences
+        WHERE sequence_schema = $1
+      `, [sourceSchema])
+
+      for (const { sequence_name } of sequences) {
+        const seqDef = await this.db.unsafe(`
+          SELECT pg_get_serial_sequence($1, $2) as seq_def
+        `, [`${sourceSchema}.${sequence_name}`, 'id'])
+
+        if (seqDef[0]?.seq_def) {
+          await this.db.unsafe(`
+            CREATE SEQUENCE "${targetSchema}"."${sequence_name}"
+          `)
+        }
+      }
+    })
+  }
+
+  /**
+   * Get the current database user.
+   */
+  private async getCurrentUser(): Promise<string | null> {
+    const result = await this.db.unsafe('SELECT current_user')
+    return result[0]?.current_user ?? null
+  }
+
+  /**
+   * Execute a raw SQL query within a specific schema context.
+   *
+   * @example
+   * const users = await manager.executeSchema('company_123',
+   *   'SELECT * FROM users WHERE active = $1', [true]
+   * )
+   */
+  async executeSchema<T = any>(
+    schema: string,
+    sql: string,
+    params?: any[]
+  ): Promise<T[]> {
+    return withSchema(schema, async () => {
+      return this.db.unsafe(sql, params) as Promise<T[]>
+    })
+  }
+
+  /**
+   * Get table statistics for a schema.
+   *
+   * @example
+   * const stats = await manager.getSchemaStats('company_123')
+   */
+  async getSchemaStats(schema: string): Promise<{
+    tables: number
+    totalRows: number
+    sizeInBytes: number
+  }> {
+    const result = await withoutSchema(async () => {
+      // Count tables
+      const tableCount = await this.db.unsafe(`
+        SELECT COUNT(*) as count
+        FROM information_schema.tables
+        WHERE table_schema = $1
+          AND table_type = 'BASE TABLE'
+      `, [schema])
+
+      // Get total row count across all tables
+      const tables = await this.db.unsafe(`
+        SELECT tablename
+        FROM pg_tables
+        WHERE schemaname = $1
+      `, [schema])
+
+      let totalRows = 0
+      for (const { tablename } of tables as Array<{ tablename: string }>) {
+        const countResult = await this.db.unsafe(
+          `SELECT COUNT(*) as count FROM "${schema}"."${tablename}"`
+        )
+        totalRows += Number(countResult[0]?.count ?? 0)
+      }
+
+      // Get schema size
+      const sizeResult = await this.db.unsafe(`
+        SELECT pg_size_pretty(
+          SUM(pg_total_relation_size(quote_ident(schemaname)||'.'||quote_ident(tablename)))
+        ) as size,
+        SUM(pg_total_relation_size(quote_ident(schemaname)||'.'||quote_ident(tablename))) as bytes
+        FROM pg_tables
+        WHERE schemaname = $1
+      `, [schema])
+
+      return {
+        tables: Number(tableCount[0]?.count ?? 0),
+        totalRows,
+        sizeInBytes: Number(sizeResult[0]?.bytes ?? 0),
+      }
+    })
+
+    return result
+  }
+}