@basicbenframework/core 0.1.0

package/src/db/index.js

@@ -0,0 +1,156 @@
+/**
+ * Database adapter loader.
+ * Provides a unified interface for SQLite, Postgres, Turso, PlanetScale, and Neon.
+ */
+
+import { loadConfig } from '../server/loader.js'
+import { QueryBuilder } from './QueryBuilder.js'
+
+let dbInstance = null
+
+/**
+ * Database adapter interface:
+ *
+ * - run(sql, params)     → { lastInsertRowid, changes }
+ * - get(sql, params)     → single row or undefined
+ * - all(sql, params)     → array of rows
+ * - exec(sql)            → run raw SQL (for migrations)
+ * - transaction(fn)      → wrap fn in BEGIN/COMMIT
+ * - close()              → close connection
+ */
+
+/**
+ * Get or create database connection
+ */
+export async function getDb() {
+  if (dbInstance) {
+    return dbInstance
+  }
+
+  const config = await loadConfig()
+  const dbConfig = config.db || {}
+
+  const driver = dbConfig.driver || 'sqlite'
+  const url = dbConfig.url || process.env.DATABASE_URL || './database.sqlite'
+
+  switch (driver) {
+    case 'sqlite':
+    case 'better-sqlite3': {
+      const { createSqliteAdapter } = await import('./adapters/sqlite.js')
+      dbInstance = await createSqliteAdapter(url, dbConfig)
+      break
+    }
+
+    case 'postgres':
+    case 'pg': {
+      const { createPostgresAdapter } = await import('./adapters/postgres.js')
+      dbInstance = await createPostgresAdapter(url, dbConfig)
+      break
+    }
+
+    case 'turso':
+    case 'libsql': {
+      const { createTursoAdapter } = await import('./adapters/turso.js')
+      dbInstance = await createTursoAdapter(url, dbConfig)
+      break
+    }
+
+    case 'planetscale':
+    case 'mysql': {
+      const { createPlanetScaleAdapter } = await import('./adapters/planetscale.js')
+      dbInstance = await createPlanetScaleAdapter(url, dbConfig)
+      break
+    }
+
+    case 'neon': {
+      const { createNeonAdapter } = await import('./adapters/neon.js')
+      dbInstance = await createNeonAdapter(url, dbConfig)
+      break
+    }
+
+    default:
+      throw new Error(
+        `Unknown database driver: ${driver}\n` +
+        'Supported drivers: sqlite, postgres, turso, planetscale, neon'
+      )
+  }
+
+  return dbInstance
+}
+
+/**
+ * Shorthand exports for common operations
+ * These use the default connection
+ */
+export const db = {
+  async run(sql, params) {
+    const conn = await getDb()
+    return conn.run(sql, params)
+  },
+
+  async get(sql, params) {
+    const conn = await getDb()
+    return conn.get(sql, params)
+  },
+
+  async all(sql, params) {
+    const conn = await getDb()
+    return conn.all(sql, params)
+  },
+
+  async exec(sql) {
+    const conn = await getDb()
+    return conn.exec(sql)
+  },
+
+  async transaction(fn) {
+    const conn = await getDb()
+    return conn.transaction(fn)
+  },
+
+  async close() {
+    if (dbInstance) {
+      await dbInstance.close()
+      dbInstance = null
+    }
+  },
+
+  /**
+   * Create a query builder for a table.
+   * Provides fluent API with mass assignment protection.
+   *
+   * @param {string} table - Table name
+   * @returns {Promise<QueryBuilder>}
+   */
+  async table(table) {
+    const conn = await getDb()
+    return new QueryBuilder(conn, table, conn.driver || 'sqlite')
+  }
+}
+
+/**
+ * Reset connection (for testing)
+ */
+export function resetDb() {
+  dbInstance = null
+}
+
+/**
+ * Create a query builder for a table.
+ * Provides fluent API with mass assignment protection.
+ *
+ * @param {string} table - Table name
+ * @returns {Promise<QueryBuilder>}
+ *
+ * @example
+ * const users = await query('users').where('active', true).get()
+ * await query('users').only('name', 'email').insert(req.body)
+ */
+export async function query(table) {
+  const conn = await getDb()
+  return new QueryBuilder(conn, table, conn.driver || 'sqlite')
+}
+
+// Re-export QueryBuilder and Grammar for advanced usage
+export { QueryBuilder } from './QueryBuilder.js'
+export { Grammar } from './Grammar.js'

package/src/db/migrator.js

@@ -0,0 +1,250 @@
+/**
+ * Migration runner.
+ * Tracks migrations in _migrations table, runs in order.
+ */
+
+import { readdirSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { getDb } from './index.js'
+
+const MIGRATIONS_TABLE = '_migrations'
+
+/**
+ * Create migrator instance
+ */
+export async function createMigrator(migrationsDir = 'migrations') {
+  const db = await getDb()
+  const dir = resolve(process.cwd(), migrationsDir)
+
+  // Ensure migrations table exists
+  await ensureMigrationsTable(db)
+
+  return {
+    /**
+     * Run all pending migrations
+     */
+    async migrate() {
+      const pending = await getPendingMigrations(db, dir)
+
+      if (pending.length === 0) {
+        return { ran: [], message: 'Nothing to migrate.' }
+      }
+
+      const batch = await getNextBatch(db)
+      const ran = []
+
+      for (const migration of pending) {
+        const module = await loadMigration(migration.path)
+
+        try {
+          await module.up(db)
+          await recordMigration(db, migration.name, batch)
+          ran.push(migration.name)
+        } catch (err) {
+          throw new Error(`Migration failed: ${migration.name}\n${err.message}`)
+        }
+      }
+
+      return { ran, batch }
+    },
+
+    /**
+     * Roll back the last batch of migrations
+     */
+    async rollback() {
+      const lastBatch = await getLastBatch(db)
+
+      if (!lastBatch) {
+        return { rolledBack: [], message: 'Nothing to rollback.' }
+      }
+
+      const migrations = await getMigrationsByBatch(db, lastBatch)
+      const rolledBack = []
+
+      // Roll back in reverse order
+      for (const migration of migrations.reverse()) {
+        const filePath = findMigrationFile(dir, migration.migration)
+
+        if (!filePath) {
+          throw new Error(`Migration file not found: ${migration.migration}`)
+        }
+
+        const module = await loadMigration(filePath)
+
+        try {
+          await module.down(db)
+          await removeMigration(db, migration.migration)
+          rolledBack.push(migration.migration)
+        } catch (err) {
+          throw new Error(`Rollback failed: ${migration.migration}\n${err.message}`)
+        }
+      }
+
+      return { rolledBack, batch: lastBatch }
+    },
+
+    /**
+     * Drop all tables and re-run all migrations
+     */
+    async fresh() {
+      // Get all tables
+      const tables = await getAllTables(db)
+
+      // Drop all tables (except sqlite internal tables)
+      for (const table of tables) {
+        if (!table.startsWith('sqlite_')) {
+          await db.exec(`DROP TABLE IF EXISTS "${table}"`)
+        }
+      }
+
+      // Re-create migrations table
+      await ensureMigrationsTable(db)
+
+      // Run all migrations
+      return this.migrate()
+    },
+
+    /**
+     * Get migration status
+     */
+    async status() {
+      const files = getMigrationFiles(dir)
+      const ran = await getRanMigrations(db)
+      const ranSet = new Set(ran.map(m => m.migration))
+
+      return files.map(file => ({
+        name: file.name,
+        ran: ranSet.has(file.name),
+        batch: ran.find(m => m.migration === file.name)?.batch || null
+      }))
+    }
+  }
+}
+
+/**
+ * Create migrations table if it doesn't exist
+ */
+async function ensureMigrationsTable(db) {
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      migration TEXT NOT NULL UNIQUE,
+      batch INTEGER NOT NULL,
+      ran_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    )
+  `)
+}
+
+/**
+ * Get list of migration files
+ */
+function getMigrationFiles(dir) {
+  if (!existsSync(dir)) {
+    return []
+  }
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.js') && !f.endsWith('.test.js'))
+    .sort()
+    .map(f => ({
+      name: f.replace('.js', ''),
+      path: join(dir, f)
+    }))
+}
+
+/**
+ * Get migrations that haven't been run
+ */
+async function getPendingMigrations(db, dir) {
+  const files = getMigrationFiles(dir)
+  const ran = await getRanMigrations(db)
+  const ranSet = new Set(ran.map(m => m.migration))
+
+  return files.filter(f => !ranSet.has(f.name))
+}
+
+/**
+ * Get all ran migrations
+ */
+async function getRanMigrations(db) {
+  return db.all(`SELECT * FROM ${MIGRATIONS_TABLE} ORDER BY batch, id`)
+}
+
+/**
+ * Get next batch number
+ */
+async function getNextBatch(db) {
+  const result = await db.get(`SELECT MAX(batch) as max FROM ${MIGRATIONS_TABLE}`)
+  return (result?.max || 0) + 1
+}
+
+/**
+ * Get last batch number
+ */
+async function getLastBatch(db) {
+  const result = await db.get(`SELECT MAX(batch) as max FROM ${MIGRATIONS_TABLE}`)
+  return result?.max || null
+}
+
+/**
+ * Get migrations by batch
+ */
+async function getMigrationsByBatch(db, batch) {
+  return db.all(`SELECT * FROM ${MIGRATIONS_TABLE} WHERE batch = ? ORDER BY id`, [batch])
+}
+
+/**
+ * Record that a migration has run
+ */
+async function recordMigration(db, name, batch) {
+  await db.run(
+    `INSERT INTO ${MIGRATIONS_TABLE} (migration, batch) VALUES (?, ?)`,
+    [name, batch]
+  )
+}
+
+/**
+ * Remove migration record
+ */
+async function removeMigration(db, name) {
+  await db.run(`DELETE FROM ${MIGRATIONS_TABLE} WHERE migration = ?`, [name])
+}
+
+/**
+ * Load migration module
+ */
+async function loadMigration(filePath) {
+  const fileUrl = pathToFileURL(filePath).href
+  return import(fileUrl)
+}
+
+/**
+ * Find migration file by name
+ */
+function findMigrationFile(dir, name) {
+  const files = getMigrationFiles(dir)
+  const match = files.find(f => f.name === name)
+  return match?.path || null
+}
+
+/**
+ * Get all table names (for fresh command)
+ */
+async function getAllTables(db) {
+  // SQLite
+  const sqliteTables = await db.all(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+  ).catch(() => [])
+
+  if (sqliteTables.length > 0) {
+    return sqliteTables.map(t => t.name)
+  }
+
+  // Postgres
+  const pgTables = await db.all(
+    "SELECT tablename FROM pg_tables WHERE schemaname = 'public'"
+  ).catch(() => [])
+
+  return pgTables.map(t => t.tablename)
+}

package/src/db/seeder.js

@@ -0,0 +1,124 @@
+/**
+ * Database seeder.
+ * Runs seed files to populate the database with initial/test data.
+ */
+
+import { readdirSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { getDb } from './index.js'
+
+/**
+ * Create seeder instance
+ *
+ * @param {string} seedsDir - Path to seeds directory (default: 'seeds')
+ */
+export async function createSeeder(seedsDir = 'seeds') {
+  const db = await getDb()
+  const dir = resolve(process.cwd(), seedsDir)
+
+  return {
+    /**
+     * Run all seed files
+     *
+     * @returns {Promise<{ ran: string[] }>}
+     */
+    async runAll() {
+      const files = getSeedFiles(dir)
+
+      if (files.length === 0) {
+        return { ran: [], message: 'No seed files found.' }
+      }
+
+      const ran = []
+
+      for (const seed of files) {
+        await this.runSeed(seed.name, seed.path)
+        ran.push(seed.name)
+      }
+
+      return { ran }
+    },
+
+    /**
+     * Run a specific seed file
+     *
+     * @param {string} name - Seed file name (without extension)
+     * @returns {Promise<void>}
+     */
+    async run(name) {
+      const files = getSeedFiles(dir)
+      const seed = files.find(f => f.name === name || f.name === `${name}.js`)
+
+      if (!seed) {
+        throw new Error(`Seed file not found: ${name}`)
+      }
+
+      await this.runSeed(seed.name, seed.path)
+      return { ran: [seed.name] }
+    },
+
+    /**
+     * Run a seed file by path
+     *
+     * @param {string} name - Seed name for logging
+     * @param {string} filePath - Full path to seed file
+     */
+    async runSeed(name, filePath) {
+      const module = await loadSeed(filePath)
+
+      if (typeof module.seed !== 'function' && typeof module.default !== 'function') {
+        throw new Error(
+          `Seed file ${name} must export a 'seed' function or default function`
+        )
+      }
+
+      const seedFn = module.seed || module.default
+
+      try {
+        await seedFn(db)
+      } catch (err) {
+        throw new Error(`Seed failed: ${name}\n${err.message}`)
+      }
+    },
+
+    /**
+     * List all available seed files
+     *
+     * @returns {string[]}
+     */
+    list() {
+      return getSeedFiles(dir).map(f => f.name)
+    }
+  }
+}
+
+/**
+ * Get list of seed files
+ *
+ * @param {string} dir - Seeds directory
+ * @returns {{ name: string, path: string }[]}
+ */
+function getSeedFiles(dir) {
+  if (!existsSync(dir)) {
+    return []
+  }
+
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.js') && !f.endsWith('.test.js'))
+    .sort()
+    .map(f => ({
+      name: f.replace('.js', ''),
+      path: join(dir, f)
+    }))
+}
+
+/**
+ * Load seed module
+ *
+ * @param {string} filePath - Path to seed file
+ */
+async function loadSeed(filePath) {
+  const fileUrl = pathToFileURL(filePath).href
+  return import(fileUrl)
+}

package/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * BasicBen framework public API
+ */
+
+export const VERSION = '0.1.0'
+
+// Database
+export { db, query, getDb, QueryBuilder, Grammar } from './db/index.js'
+
+// These will be implemented in later phases
+// export { validate, rules } from './validation/index.js'
+// export { signJwt, verifyJwt } from './auth/jwt.js'

package/src/scaffolding/index.js

@@ -0,0 +1,152 @@
+/**
+ * Scaffolding system.
+ * Reads stub files, replaces placeholders, writes to target directory.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const stubsDir = resolve(__dirname, '../../stubs')
+
+/**
+ * Generate a file from a stub template
+ *
+ * @param {string} stubName - Name of stub file (without .stub extension)
+ * @param {string} targetPath - Where to write the generated file
+ * @param {Object} replacements - Key-value pairs for placeholder replacement
+ */
+export function generate(stubName, targetPath, replacements = {}) {
+  const stubPath = join(stubsDir, `${stubName}.stub`)
+
+  if (!existsSync(stubPath)) {
+    throw new Error(`Stub not found: ${stubName}.stub`)
+  }
+
+  // Check if target already exists
+  const fullTargetPath = resolve(process.cwd(), targetPath)
+  if (existsSync(fullTargetPath)) {
+    throw new Error(`File already exists: ${targetPath}`)
+  }
+
+  // Read stub
+  let content = readFileSync(stubPath, 'utf8')
+
+  // Replace placeholders: {{name}}, {{Name}}, {{table}}, etc.
+  for (const [key, value] of Object.entries(replacements)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g')
+    content = content.replace(pattern, value)
+  }
+
+  // Ensure directory exists
+  const targetDir = dirname(fullTargetPath)
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+  }
+
+  // Write file
+  writeFileSync(fullTargetPath, content)
+
+  return fullTargetPath
+}
+
+/**
+ * Transform name to different cases
+ */
+export function transformName(name) {
+  // Remove common suffixes if present
+  const baseName = name
+    .replace(/Controller$/i, '')
+    .replace(/Model$/i, '')
+    .replace(/Middleware$/i, '')
+
+  return {
+    // Original input
+    original: name,
+
+    // PascalCase: UserController
+    pascal: toPascalCase(baseName),
+
+    // camelCase: userController
+    camel: toCamelCase(baseName),
+
+    // snake_case: user_controller
+    snake: toSnakeCase(baseName),
+
+    // kebab-case: user-controller
+    kebab: toKebabCase(baseName),
+
+    // lowercase: user
+    lower: baseName.toLowerCase(),
+
+    // Plural forms (simple)
+    pluralLower: pluralize(baseName.toLowerCase()),
+    pluralSnake: pluralize(toSnakeCase(baseName))
+  }
+}
+
+/**
+ * Convert to PascalCase
+ */
+function toPascalCase(str) {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '')
+    .replace(/^(.)/, (c) => c.toUpperCase())
+}
+
+/**
+ * Convert to camelCase
+ */
+function toCamelCase(str) {
+  const pascal = toPascalCase(str)
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1)
+}
+
+/**
+ * Convert to snake_case
+ */
+function toSnakeCase(str) {
+  return str
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/^_/, '')
+    .replace(/[-\s]+/g, '_')
+}
+
+/**
+ * Convert to kebab-case
+ */
+function toKebabCase(str) {
+  return toSnakeCase(str).replace(/_/g, '-')
+}
+
+/**
+ * Simple pluralization
+ */
+function pluralize(str) {
+  if (str.endsWith('y')) {
+    return str.slice(0, -1) + 'ies'
+  }
+  if (str.endsWith('s') || str.endsWith('x') || str.endsWith('ch') || str.endsWith('sh')) {
+    return str + 'es'
+  }
+  return str + 's'
+}
+
+/**
+ * Generate timestamp for migration files
+ */
+export function timestamp() {
+  const now = new Date()
+  const pad = (n) => String(n).padStart(2, '0')
+
+  return [
+    now.getFullYear(),
+    pad(now.getMonth() + 1),
+    pad(now.getDate()),
+    pad(now.getHours()),
+    pad(now.getMinutes()),
+    pad(now.getSeconds())
+  ].join('')
+}