webspresso 0.0.6 → 0.0.8

package/core/orm/index.js

@@ -0,0 +1,148 @@
+/**
+ * Webspresso ORM
+ * Minimal, Eloquent-inspired ORM with Knex and Zod
+ * @module core/orm
+ */
+
+const { createSchemaHelpers, extractColumnsFromSchema, getColumnMeta } = require('./schema-helpers');
+const { defineModel, getModel, getAllModels, hasModel, clearRegistry } = require('./model');
+const { createRepository } = require('./repository');
+const { createQueryBuilder, QueryBuilder } = require('./query-builder');
+const { runTransaction, createTransactionContext } = require('./transaction');
+const { createMigrationManager } = require('./migrations');
+const { scaffoldMigration, scaffoldAlterMigration, scaffoldDropMigration } = require('./migrations/scaffold');
+const { createScopeContext } = require('./scopes');
+const { createSeeder } = require('./seeder');
+
+/**
+ * Create a database instance
+ * @param {import('./types').DatabaseConfig} config - Database configuration
+ * @returns {import('./types').DatabaseInstance}
+ */
+function createDatabase(config) {
+  // Lazy load knex to avoid requiring it if ORM is not used
+  let knex;
+  try {
+    knex = require('knex');
+  } catch {
+    throw new Error('Knex is required for ORM. Install it with: npm install knex');
+  }
+
+  // Create Knex instance
+  const knexInstance = knex(config);
+
+  // Create migration manager
+  const migrationConfig = config.migrations || {};
+  const migrate = createMigrationManager(knexInstance, migrationConfig);
+
+  // Default scope context
+  let globalScopeContext = createScopeContext();
+
+  /**
+   * Set global tenant ID
+   * @param {*} tenantId - Tenant ID
+   * @returns {DatabaseInstance}
+   */
+  function forTenant(tenantId) {
+    globalScopeContext.tenantId = tenantId;
+    return db;
+  }
+
+  /**
+   * Create a repository for a model
+   * @param {import('./types').ModelDefinition} model - Model definition
+   * @returns {import('./types').Repository}
+   */
+  function createRepo(model) {
+    return createRepository(model, knexInstance, { ...globalScopeContext });
+  }
+
+  /**
+   * Run a callback within a transaction
+   * @param {function(import('./types').TransactionContext): Promise<*>} callback
+   * @returns {Promise<*>}
+   */
+  function transaction(callback) {
+    return runTransaction(knexInstance, callback, { ...globalScopeContext });
+  }
+
+  /**
+   * Get raw Knex instance for advanced queries
+   * @returns {import('knex').Knex}
+   */
+  function raw() {
+    return knexInstance;
+  }
+
+  /**
+   * Close all database connections
+   * @returns {Promise<void>}
+   */
+  async function destroy() {
+    await knexInstance.destroy();
+  }
+
+  /**
+   * Create a seeder instance
+   * @param {Object} faker - Faker instance (@faker-js/faker)
+   * @returns {Object} Seeder API
+   */
+  function seeder(faker) {
+    return createSeeder(faker, knexInstance);
+  }
+
+  const db = {
+    knex: knexInstance,
+    createRepository: createRepo,
+    transaction,
+    migrate,
+    seeder,
+    forTenant,
+    raw,
+    destroy,
+  };
+
+  return db;
+}
+
+// Export everything
+module.exports = {
+  // Main factory
+  createDatabase,
+
+  // Schema helpers
+  createSchemaHelpers,
+  extractColumnsFromSchema,
+  getColumnMeta,
+
+  // Model
+  defineModel,
+  getModel,
+  getAllModels,
+  hasModel,
+  clearRegistry,
+
+  // Repository (for direct use if needed)
+  createRepository,
+
+  // Query builder
+  createQueryBuilder,
+  QueryBuilder,
+
+  // Transaction
+  runTransaction,
+  createTransactionContext,
+
+  // Migrations
+  createMigrationManager,
+  scaffoldMigration,
+  scaffoldAlterMigration,
+  scaffoldDropMigration,
+
+  // Scopes
+  createScopeContext,
+
+  // Seeder
+  createSeeder,
+};
+

package/core/orm/migrations/index.js

@@ -0,0 +1,205 @@
+/**
+ * Webspresso ORM - Migration Manager
+ * Wraps Knex migrations API
+ * @module core/orm/migrations
+ */
+
+const { generateMigrationTimestamp } = require('../utils');
+
+/**
+ * Create a migration manager
+ * @param {import('knex').Knex} knex - Knex instance
+ * @param {import('../types').MigrationConfig} config - Migration configuration
+ * @returns {import('../types').MigrationManager}
+ */
+function createMigrationManager(knex, config = {}) {
+  const {
+    directory = './migrations',
+    tableName = 'knex_migrations',
+  } = config;
+
+  const migrationConfig = {
+    directory,
+    tableName,
+  };
+
+  return {
+    /**
+     * Run all pending migrations
+     * @returns {Promise<import('../types').MigrationResult>}
+     */
+    async latest() {
+      const [batch, migrations] = await knex.migrate.latest(migrationConfig);
+      return {
+        batch,
+        migrations,
+      };
+    },
+
+    /**
+     * Rollback migrations
+     * @param {Object} [options={}]
+     * @param {boolean} [options.all=false] - Rollback all migrations
+     * @returns {Promise<import('../types').MigrationResult>}
+     */
+    async rollback(options = {}) {
+      const rollbackConfig = {
+        ...migrationConfig,
+        ...(options.all ? { all: true } : {}),
+      };
+      const [batch, migrations] = await knex.migrate.rollback(rollbackConfig);
+      return {
+        batch,
+        migrations,
+      };
+    },
+
+    /**
+     * Get current migration version
+     * @returns {Promise<string>}
+     */
+    async currentVersion() {
+      return knex.migrate.currentVersion(migrationConfig);
+    },
+
+    /**
+     * Get migration status
+     * @returns {Promise<import('../types').MigrationStatus[]>}
+     */
+    async status() {
+      // Get completed migrations from database
+      const completedResult = await knex.migrate.list(migrationConfig);
+      const [completed, pending] = completedResult;
+
+      const statuses = [];
+
+      // Add completed migrations
+      for (const migration of completed) {
+        statuses.push({
+          name: migration.name || migration,
+          completed: true,
+          ran_at: migration.migration_time || null,
+          batch: migration.batch || null,
+        });
+      }
+
+      // Add pending migrations
+      for (const migration of pending) {
+        statuses.push({
+          name: migration.name || migration,
+          completed: false,
+          ran_at: null,
+          batch: null,
+        });
+      }
+
+      // Sort by name
+      statuses.sort((a, b) => a.name.localeCompare(b.name));
+
+      return statuses;
+    },
+
+    /**
+     * Create a new migration file
+     * @param {string} name - Migration name
+     * @param {Object} [options={}]
+     * @param {string} [options.content] - Custom migration content
+     * @returns {Promise<string>} Created file path
+     */
+    async make(name, options = {}) {
+      const { content } = options;
+      
+      if (content) {
+        // Use custom stub with content
+        const timestamp = generateMigrationTimestamp();
+        const filename = `${timestamp}_${name}.js`;
+        
+        // Knex's make doesn't support custom content directly,
+        // so we return the filename and content for the CLI to write
+        return {
+          filename,
+          filepath: `${directory}/${filename}`,
+          content,
+        };
+      }
+
+      // Use default Knex make
+      const result = await knex.migrate.make(name, migrationConfig);
+      return {
+        filename: result.split('/').pop(),
+        filepath: result,
+        content: null,
+      };
+    },
+
+    /**
+     * Run specific migration up
+     * @param {string} name - Migration name
+     * @returns {Promise<void>}
+     */
+    async up(name) {
+      await knex.migrate.up({ ...migrationConfig, name });
+    },
+
+    /**
+     * Run specific migration down
+     * @param {string} name - Migration name
+     * @returns {Promise<void>}
+     */
+    async down(name) {
+      await knex.migrate.down({ ...migrationConfig, name });
+    },
+
+    /**
+     * Get the migration configuration
+     * @returns {Object}
+     */
+    getConfig() {
+      return { ...migrationConfig };
+    },
+
+    /**
+     * Check if migrations table exists
+     * @returns {Promise<boolean>}
+     */
+    async hasTable() {
+      return knex.schema.hasTable(tableName);
+    },
+
+    /**
+     * Unlock stuck migrations
+     * @returns {Promise<void>}
+     */
+    async unlock() {
+      await knex.migrate.forceFreeMigrationsLock(migrationConfig);
+    },
+  };
+}
+
+/**
+ * Default migration template
+ * @returns {string}
+ */
+function getDefaultMigrationTemplate() {
+  return `/**
+ * Migration: 
+ */
+
+exports.up = function(knex) {
+  return knex.schema.createTable('table_name', (table) => {
+    table.bigIncrements('id').primary();
+    table.timestamps(true, true);
+  });
+};
+
+exports.down = function(knex) {
+  return knex.schema.dropTableIfExists('table_name');
+};
+`;
+}
+
+module.exports = {
+  createMigrationManager,
+  getDefaultMigrationTemplate,
+};
+

package/core/orm/migrations/scaffold.js

@@ -0,0 +1,312 @@
+/**
+ * Webspresso ORM - Migration Scaffolding
+ * Generate migration code from model schema
+ * @module core/orm/migrations/scaffold
+ */
+
+const { getColumnMeta } = require('../schema-helpers');
+
+/**
+ * Generate migration code from a model definition
+ * @param {import('../types').ModelDefinition} model - Model definition
+ * @returns {string} Migration file content
+ */
+function scaffoldMigration(model) {
+  const { table, columns, scopes } = model;
+  
+  const columnLines = [];
+  const indexLines = [];
+  const foreignKeyLines = [];
+
+  // Process each column
+  for (const [columnName, meta] of columns.entries()) {
+    const { line, indexLine, fkLine } = generateColumnLine(columnName, meta);
+    columnLines.push(line);
+    if (indexLine) indexLines.push(indexLine);
+    if (fkLine) foreignKeyLines.push(fkLine);
+  }
+
+  // Generate the migration content
+  const lines = [
+    '/**',
+    ` * Migration: Create ${table} table`,
+    ' * Auto-generated from model schema',
+    ' */',
+    '',
+    'exports.up = function(knex) {',
+    `  return knex.schema.createTable('${table}', (table) => {`,
+  ];
+
+  // Add column definitions
+  for (const line of columnLines) {
+    lines.push(`    ${line}`);
+  }
+
+  // Add indexes
+  if (indexLines.length > 0) {
+    lines.push('');
+    lines.push('    // Indexes');
+    for (const line of indexLines) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  // Add foreign keys
+  if (foreignKeyLines.length > 0) {
+    lines.push('');
+    lines.push('    // Foreign keys');
+    for (const line of foreignKeyLines) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  lines.push('  });');
+  lines.push('};');
+  lines.push('');
+  lines.push('exports.down = function(knex) {');
+  lines.push(`  return knex.schema.dropTableIfExists('${table}');`);
+  lines.push('};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a single column line for migration
+ * @param {string} columnName - Column name
+ * @param {import('../types').ColumnMeta} meta - Column metadata
+ * @returns {{ line: string, indexLine: string|null, fkLine: string|null }}
+ */
+function generateColumnLine(columnName, meta) {
+  const parts = [];
+  let indexLine = null;
+  let fkLine = null;
+
+  // Determine column type and method
+  switch (meta.type) {
+    case 'bigint':
+      if (meta.primary && meta.autoIncrement) {
+        parts.push(`table.bigIncrements('${columnName}')`);
+      } else if (meta.references) {
+        parts.push(`table.bigInteger('${columnName}').unsigned()`);
+        fkLine = `table.foreign('${columnName}').references('${meta.referenceColumn || 'id'}').inTable('${meta.references}');`;
+      } else {
+        parts.push(`table.bigInteger('${columnName}')`);
+      }
+      break;
+
+    case 'integer':
+      if (meta.primary && meta.autoIncrement) {
+        parts.push(`table.increments('${columnName}')`);
+      } else {
+        parts.push(`table.integer('${columnName}')`);
+      }
+      break;
+
+    case 'string':
+      const maxLength = meta.maxLength || 255;
+      parts.push(`table.string('${columnName}', ${maxLength})`);
+      break;
+
+    case 'text':
+      parts.push(`table.text('${columnName}')`);
+      break;
+
+    case 'float':
+      parts.push(`table.float('${columnName}')`);
+      break;
+
+    case 'decimal':
+      const precision = meta.precision || 10;
+      const scale = meta.scale || 2;
+      parts.push(`table.decimal('${columnName}', ${precision}, ${scale})`);
+      break;
+
+    case 'boolean':
+      parts.push(`table.boolean('${columnName}')`);
+      break;
+
+    case 'date':
+      parts.push(`table.date('${columnName}')`);
+      break;
+
+    case 'datetime':
+      parts.push(`table.datetime('${columnName}')`);
+      break;
+
+    case 'timestamp':
+      parts.push(`table.timestamp('${columnName}')`);
+      break;
+
+    case 'json':
+      parts.push(`table.json('${columnName}')`);
+      break;
+
+    case 'enum':
+      const enumValues = meta.enumValues || [];
+      const valuesStr = enumValues.map(v => `'${v}'`).join(', ');
+      parts.push(`table.enum('${columnName}', [${valuesStr}])`);
+      break;
+
+    case 'uuid':
+      if (meta.primary) {
+        parts.push(`table.uuid('${columnName}')`);
+      } else if (meta.references) {
+        parts.push(`table.uuid('${columnName}')`);
+        fkLine = `table.foreign('${columnName}').references('${meta.referenceColumn || 'id'}').inTable('${meta.references}');`;
+      } else {
+        parts.push(`table.uuid('${columnName}')`);
+      }
+      break;
+
+    default:
+      parts.push(`table.string('${columnName}')`);
+  }
+
+  // Add constraints
+  if (meta.primary && !meta.autoIncrement) {
+    parts.push('.primary()');
+  }
+
+  if (meta.unique) {
+    parts.push('.unique()');
+  }
+
+  if (meta.nullable) {
+    parts.push('.nullable()');
+  } else if (!meta.primary) {
+    parts.push('.notNullable()');
+  }
+
+  if (meta.default !== undefined) {
+    if (typeof meta.default === 'string') {
+      parts.push(`.defaultTo('${meta.default}')`);
+    } else if (meta.default === null) {
+      parts.push('.defaultTo(null)');
+    } else {
+      parts.push(`.defaultTo(${meta.default})`);
+    }
+  }
+
+  // Auto timestamps get default to knex.fn.now()
+  if (meta.auto === 'create' || meta.auto === 'update') {
+    parts.push('.defaultTo(knex.fn.now())');
+  }
+
+  // Generate index line if needed
+  if (meta.index && !meta.unique && !meta.primary) {
+    indexLine = `table.index(['${columnName}']);`;
+  }
+
+  return {
+    line: parts.join('') + ';',
+    indexLine,
+    fkLine,
+  };
+}
+
+/**
+ * Generate migration code for adding columns to existing table
+ * @param {string} tableName - Table name
+ * @param {Map<string, import('../types').ColumnMeta>} columns - Columns to add
+ * @returns {string} Migration file content
+ */
+function scaffoldAlterMigration(tableName, columns) {
+  const columnLines = [];
+  const indexLines = [];
+  const foreignKeyLines = [];
+  const dropLines = [];
+
+  for (const [columnName, meta] of columns.entries()) {
+    const { line, indexLine, fkLine } = generateColumnLine(columnName, meta);
+    columnLines.push(line);
+    if (indexLine) indexLines.push(indexLine);
+    if (fkLine) foreignKeyLines.push(fkLine);
+    dropLines.push(`table.dropColumn('${columnName}');`);
+  }
+
+  const lines = [
+    '/**',
+    ` * Migration: Alter ${tableName} table`,
+    ' * Auto-generated',
+    ' */',
+    '',
+    'exports.up = function(knex) {',
+    `  return knex.schema.alterTable('${tableName}', (table) => {`,
+  ];
+
+  for (const line of columnLines) {
+    lines.push(`    ${line}`);
+  }
+
+  if (indexLines.length > 0) {
+    lines.push('');
+    for (const line of indexLines) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  if (foreignKeyLines.length > 0) {
+    lines.push('');
+    for (const line of foreignKeyLines) {
+      lines.push(`    ${line}`);
+    }
+  }
+
+  lines.push('  });');
+  lines.push('};');
+  lines.push('');
+  lines.push('exports.down = function(knex) {');
+  lines.push(`  return knex.schema.alterTable('${tableName}', (table) => {`);
+
+  for (const line of dropLines) {
+    lines.push(`    ${line}`);
+  }
+
+  lines.push('  });');
+  lines.push('};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate migration code for a drop table
+ * @param {string} tableName - Table name
+ * @returns {string} Migration file content
+ */
+function scaffoldDropMigration(tableName) {
+  return `/**
+ * Migration: Drop ${tableName} table
+ */
+
+exports.up = function(knex) {
+  return knex.schema.dropTableIfExists('${tableName}');
+};
+
+exports.down = function(knex) {
+  // Note: This down migration is empty because we don't know the original schema.
+  // If you need to restore the table, please add the schema manually.
+  return Promise.resolve();
+};
+`;
+}
+
+/**
+ * Generate migration name from model
+ * @param {import('../types').ModelDefinition} model - Model definition
+ * @param {string} [action='create'] - Action (create, alter, drop)
+ * @returns {string}
+ */
+function generateMigrationName(model, action = 'create') {
+  return `${action}_${model.table}_table`;
+}
+
+module.exports = {
+  scaffoldMigration,
+  scaffoldAlterMigration,
+  scaffoldDropMigration,
+  generateColumnLine,
+  generateMigrationName,
+};
+