webspresso 0.0.6 → 0.0.7

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,
+};
+

package/core/orm/model.js

@@ -0,0 +1,178 @@
+/**
+ * Webspresso ORM - Model Definition
+ * Define models and maintain a registry
+ * @module core/orm/model
+ */
+
+const { extractColumnsFromSchema } = require('./schema-helpers');
+
+/**
+ * Global model registry
+ * @type {Map<string, import('./types').ModelDefinition>}
+ */
+const modelRegistry = new Map();
+
+/**
+ * Define a new model
+ * @param {import('./types').ModelOptions} options - Model configuration
+ * @returns {import('./types').ModelDefinition}
+ */
+function defineModel(options) {
+  const {
+    name,
+    table,
+    schema,
+    primaryKey = 'id',
+    relations = {},
+    scopes = {},
+  } = options;
+
+  // Validate required fields
+  if (!name || typeof name !== 'string') {
+    throw new Error('Model name is required and must be a string');
+  }
+  if (!table || typeof table !== 'string') {
+    throw new Error('Model table is required and must be a string');
+  }
+  if (!schema || typeof schema.parse !== 'function') {
+    throw new Error('Model schema is required and must be a Zod schema');
+  }
+
+  // Check for duplicate registration
+  if (modelRegistry.has(name)) {
+    throw new Error(`Model "${name}" is already defined`);
+  }
+
+  // Extract column metadata from schema
+  const columns = extractColumnsFromSchema(schema);
+
+  // Validate relations
+  for (const [relationName, relation] of Object.entries(relations)) {
+    if (!['belongsTo', 'hasMany', 'hasOne'].includes(relation.type)) {
+      throw new Error(
+        `Invalid relation type "${relation.type}" for "${relationName}" in model "${name}"`
+      );
+    }
+    if (typeof relation.model !== 'function') {
+      throw new Error(
+        `Relation "${relationName}" in model "${name}" must have a model function`
+      );
+    }
+    if (!relation.foreignKey || typeof relation.foreignKey !== 'string') {
+      throw new Error(
+        `Relation "${relationName}" in model "${name}" must have a foreignKey string`
+      );
+    }
+  }
+
+  // Create model definition
+  const model = {
+    name,
+    table,
+    schema,
+    primaryKey,
+    relations,
+    scopes: {
+      softDelete: scopes.softDelete || false,
+      timestamps: scopes.timestamps || false,
+      tenant: scopes.tenant || null,
+    },
+    columns,
+  };
+
+  // Register model
+  modelRegistry.set(name, model);
+
+  return model;
+}
+
+/**
+ * Get a model by name
+ * @param {string} name - Model name
+ * @returns {import('./types').ModelDefinition|undefined}
+ */
+function getModel(name) {
+  return modelRegistry.get(name);
+}
+
+/**
+ * Get all registered models
+ * @returns {Map<string, import('./types').ModelDefinition>}
+ */
+function getAllModels() {
+  return new Map(modelRegistry);
+}
+
+/**
+ * Check if a model exists
+ * @param {string} name - Model name
+ * @returns {boolean}
+ */
+function hasModel(name) {
+  return modelRegistry.has(name);
+}
+
+/**
+ * Clear the model registry (useful for testing)
+ */
+function clearRegistry() {
+  modelRegistry.clear();
+}
+
+/**
+ * Unregister a model by name
+ * @param {string} name - Model name
+ * @returns {boolean} Whether the model was removed
+ */
+function unregisterModel(name) {
+  return modelRegistry.delete(name);
+}
+
+/**
+ * Resolve a relation's model (handles lazy loading)
+ * @param {import('./types').RelationDefinition} relation - Relation definition
+ * @returns {import('./types').ModelDefinition}
+ */
+function resolveRelationModel(relation) {
+  const model = relation.model();
+  if (!model || !model.name) {
+    throw new Error('Invalid relation model reference');
+  }
+  return model;
+}
+
+/**
+ * Get the foreign key column info for a relation
+ * @param {import('./types').ModelDefinition} model - Parent model
+ * @param {string} relationName - Relation name
+ * @returns {{ localKey: string, foreignKey: string, relatedModel: import('./types').ModelDefinition }}
+ */
+function getRelationKeys(model, relationName) {
+  const relation = model.relations[relationName];
+  if (!relation) {
+    throw new Error(`Relation "${relationName}" not found on model "${model.name}"`);
+  }
+
+  const relatedModel = resolveRelationModel(relation);
+  const localKey = relation.localKey || model.primaryKey;
+
+  return {
+    localKey,
+    foreignKey: relation.foreignKey,
+    relatedModel,
+  };
+}
+
+module.exports = {
+  defineModel,
+  getModel,
+  getAllModels,
+  hasModel,
+  clearRegistry,
+  unregisterModel,
+  resolveRelationModel,
+  getRelationKeys,
+  // Export registry for testing
+  _registry: modelRegistry,
+};
+