webspresso 0.0.100 → 0.0.102

package/core/orm/factory.js

@@ -0,0 +1,250 @@
+/**
+ * Webspresso ORM - Model Factory & Seeding (AdonisJS Lucid-inspired)
+ * Declarative mock data generation and seeding for tests and development
+ * @module core/orm/factory
+ */
+
+/**
+ * Fallback lightweight mock faker when @faker-js/faker is not present
+ */
+function createMinimalFaker() {
+  let counter = 1000;
+  return {
+    person: {
+      fullName: () => `User_${++counter}`,
+      firstName: () => `First_${++counter}`,
+      lastName: () => `Last_${++counter}`,
+    },
+    internet: {
+      email: () => `user_${++counter}@example.com`,
+      userName: () => `user_${++counter}`,
+      url: () => `https://example.com/item/${++counter}`,
+    },
+    lorem: {
+      sentence: (words = 5) => `Sample text description ${++counter}`,
+      paragraph: () => `Sample paragraph for model testing with counter ${++counter}.`,
+      words: (n = 3) => `words_${++counter}`,
+    },
+    number: {
+      int: (opts = { min: 1, max: 1000 }) => {
+        const min = opts.min ?? 1;
+        const max = opts.max ?? 1000;
+        return Math.floor(Math.random() * (max - min + 1)) + min;
+      },
+      float: (opts = { min: 1, max: 100, precision: 0.01 }) => {
+        const min = opts.min ?? 1;
+        const max = opts.max ?? 100;
+        return Number((Math.random() * (max - min) + min).toFixed(2));
+      },
+    },
+    date: {
+      recent: () => new Date(),
+      past: () => new Date(Date.now() - 86400000 * 30),
+      future: () => new Date(Date.now() + 86400000 * 30),
+    },
+    datatype: {
+      boolean: () => Math.random() > 0.5,
+    },
+    string: {
+      nanoid: () => `nano_${Math.random().toString(36).slice(2, 10)}`,
+      uuid: () => `00000000-0000-4000-8000-${String(++counter).padStart(12, '0')}`,
+    },
+  };
+}
+
+function resolveFaker() {
+  try {
+    const fakerMod = require('@faker-js/faker');
+    return fakerMod.faker || fakerMod.default?.faker || fakerMod;
+  } catch {
+    return createMinimalFaker();
+  }
+}
+
+/**
+ * Factory Builder for generating single or multiple model instances
+ */
+class FactoryBuilder {
+  /**
+   * @param {string} modelName
+   * @param {Function} definitionFn
+   * @param {Map<string, Function|Object>} states
+   */
+  constructor(modelName, definitionFn, states = new Map()) {
+    this._modelName = modelName;
+    this._definitionFn = definitionFn;
+    this._states = states;
+    this._appliedStates = [];
+    this._count = 1;
+    this._overrides = {};
+  }
+
+  /**
+   * Set number of records to generate
+   * @param {number} n
+   * @returns {FactoryBuilder}
+   */
+  count(n) {
+    const clone = this._clone();
+    clone._count = Math.max(1, Math.floor(n));
+    return clone;
+  }
+
+  /**
+   * Apply one or more named states
+   * @param {...string} stateNames
+   * @returns {FactoryBuilder}
+   */
+  state(...stateNames) {
+    return this.apply(...stateNames);
+  }
+
+  /**
+   * Apply one or more named states
+   * @param {...string} stateNames
+   * @returns {FactoryBuilder}
+   */
+  apply(...stateNames) {
+    const clone = this._clone();
+    clone._appliedStates.push(...stateNames);
+    return clone;
+  }
+
+  /**
+   * Merge field overrides
+   * @param {Object} overrides
+   * @returns {FactoryBuilder}
+   */
+  merge(overrides = {}) {
+    const clone = this._clone();
+    clone._overrides = { ...clone._overrides, ...overrides };
+    return clone;
+  }
+
+  /**
+   * Build single raw record object without persisting
+   * @param {number} index
+   * @param {Object} [additionalOverrides={}]
+   * @returns {Object}
+   */
+  _buildOne(index = 0, additionalOverrides = {}) {
+    const faker = resolveFaker();
+    let data = this._definitionFn({ faker, index }) || {};
+
+    for (const stateName of this._appliedStates) {
+      const stateHandler = this._states.get(stateName);
+      if (stateHandler) {
+        const stateData =
+          typeof stateHandler === 'function'
+            ? stateHandler({ faker, index, current: data })
+            : stateHandler;
+        data = { ...data, ...stateData };
+      }
+    }
+
+    return { ...data, ...this._overrides, ...additionalOverrides };
+  }
+
+  /**
+   * Generate raw data objects in memory (does not insert into DB)
+   * @param {Object} [overrides={}]
+   * @returns {Object|Object[]}
+   */
+  make(overrides = {}) {
+    if (this._count === 1) {
+      return this._buildOne(0, overrides);
+    }
+    return Array.from({ length: this._count }, (_, i) => this._buildOne(i, overrides));
+  }
+
+  /**
+   * Generate and persist record(s) to the database using repository
+   * @param {Object} options
+   * @param {import('./types').DatabaseInstance|import('./types').Repository} options.db - Database or repository
+   * @param {Object} [options.merge={}] - Additional field overrides
+   * @returns {Promise<Object|Object[]>}
+   */
+  async create(options = {}) {
+    const target = options.db || options;
+    let repo;
+
+    if (target && typeof target.getRepository === 'function') {
+      repo = target.getRepository(this._modelName);
+    } else if (target && typeof target.create === 'function') {
+      repo = target;
+    } else {
+      throw new Error(
+        `Factory.create() requires a database instance: .create({ db }) for model "${this._modelName}"`
+      );
+    }
+
+    const mergeData = options.merge || {};
+
+    if (this._count === 1) {
+      const attributes = this._buildOne(0, mergeData);
+      return await repo.create(attributes);
+    }
+
+    const items = Array.from({ length: this._count }, (_, i) => this._buildOne(i, mergeData));
+    const results = [];
+    for (const item of items) {
+      results.push(await repo.create(item));
+    }
+    return results;
+  }
+
+  /**
+   * Clone builder preserving definition and state
+   * @protected
+   */
+  _clone() {
+    const clone = new FactoryBuilder(this._modelName, this._definitionFn, this._states);
+    clone._appliedStates = [...this._appliedStates];
+    clone._count = this._count;
+    clone._overrides = { ...this._overrides };
+    return clone;
+  }
+}
+
+/**
+ * Define a model factory (AdonisJS Lucid-inspired)
+ * @param {string} modelName - Model identifier in registry (e.g. 'User')
+ * @param {Function} definitionFn - Factory blueprint `({ faker, index }) => ({ ... })`
+ * @returns {FactoryBuilder & { state: (name: string, handler: Function|Object) => any }}
+ */
+function defineFactory(modelName, definitionFn) {
+  if (typeof modelName !== 'string' || !modelName.trim()) {
+    throw new Error('defineFactory expects a model name string as first argument');
+  }
+  if (typeof definitionFn !== 'function') {
+    throw new Error(`defineFactory expects a definition function for model "${modelName}"`);
+  }
+
+  const states = new Map();
+  const rootBuilder = new FactoryBuilder(modelName, definitionFn, states);
+
+  // Extend root builder with fluent state registration
+  rootBuilder.registerState = function (name, handler) {
+    states.set(name, handler);
+    return rootBuilder;
+  };
+
+  // Allow .state('admin', fn) as registration when called with 2 args,
+  // or as apply when called with 1 arg.
+  const originalState = rootBuilder.state.bind(rootBuilder);
+  rootBuilder.state = function (nameOrFirst, maybeHandler, ...rest) {
+    if (typeof maybeHandler === 'function' || (maybeHandler && typeof maybeHandler === 'object')) {
+      states.set(nameOrFirst, maybeHandler);
+      return rootBuilder;
+    }
+    return originalState(nameOrFirst, ...rest);
+  };
+
+  return rootBuilder;
+}
+
+module.exports = {
+  defineFactory,
+  FactoryBuilder,
+  resolveFaker,
+};

package/core/orm/index.js

@@ -386,4 +386,10 @@ module.exports = {
   buildSearchClause: require('./search').buildSearchClause,
   tokenizeSearchTerm: require('./search').tokenizeSearchTerm,
   detectDialect: require('./search').detectDialect,
+  // Model Factory & Seeding (AdonisJS Lucid-inspired)
+  defineFactory: require('./factory').defineFactory,
+  FactoryBuilder: require('./factory').FactoryBuilder,
+  // Schema Diff & Makemigrations (Django-inspired)
+  diffSchema: require('./migrations/diff').diffSchema,
+  makeMigrations: require('./migrations/diff').makeMigrations,
 };

package/core/orm/migrations/diff.js

@@ -0,0 +1,185 @@
+/**
+ * Webspresso ORM - Schema Diff & Auto-Migration Generator (Django-inspired makemigrations)
+ * Compares ORM models with live database schema and generates migrations
+ * @module core/orm/migrations/diff
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { getAllModels } = require('../model');
+const {
+  scaffoldMigration,
+  scaffoldAlterMigration,
+  generateMigrationName,
+} = require('./scaffold');
+const {
+  migrationTimestamp,
+  sortModelsByDependencies,
+  loadModelsFromDirectory,
+} = require('../../../bin/utils/model-migrations');
+
+/**
+ * Compare models with existing database schema to find diffs
+ * @param {Object} options
+ * @param {import('knex').Knex} options.knex - Active Knex instance
+ * @param {import('../types').ModelDefinition[]} [options.models] - List of models to diff
+ * @param {boolean} [options.includeDrops=false] - Whether to generate dropColumn for removed fields
+ * @returns {Promise<{ hasChanges: boolean, changes: Array<Object> }>}
+ */
+async function diffSchema(options = {}) {
+  const {
+    knex,
+    models = [...getAllModels().values()],
+    includeDrops = false,
+  } = options;
+
+  if (!knex) {
+    throw new Error('diffSchema requires an active knex instance');
+  }
+
+  const sortedModels = sortModelsByDependencies(models);
+  const changes = [];
+
+  for (const model of sortedModels) {
+    const tableExists = await knex.schema.hasTable(model.table);
+
+    if (!tableExists) {
+      // Table doesn't exist at all -> generate createTable
+      const migrationName = generateMigrationName(model, 'create');
+      const content = scaffoldMigration(model);
+      changes.push({
+        model: model.name,
+        table: model.table,
+        type: 'create_table',
+        addedColumns: Array.from(model.columns.keys()),
+        removedColumns: [],
+        migrationName,
+        content,
+      });
+      continue;
+    }
+
+    // Table exists -> inspect columns
+    const columnInfo = await knex(model.table).columnInfo();
+    const existingColNames = new Set(Object.keys(columnInfo));
+
+    const addedColumns = new Map();
+    for (const [colName, colMeta] of model.columns.entries()) {
+      if (!existingColNames.has(colName)) {
+        addedColumns.set(colName, colMeta);
+      }
+    }
+
+    const removedColumnNames = [];
+    if (includeDrops) {
+      for (const existingCol of existingColNames) {
+        // Skip knex internal migrations or common internal columns if needed
+        if (!model.columns.has(existingCol)) {
+          removedColumnNames.push(existingCol);
+        }
+      }
+    }
+
+    if (addedColumns.size > 0) {
+      const addedKeys = Array.from(addedColumns.keys());
+      const prefix = addedKeys.slice(0, 3).join('_');
+      const migrationName = `add_${prefix}${addedKeys.length > 3 ? '_etc' : ''}_to_${model.table}_table`;
+      const content = scaffoldAlterMigration(model.table, addedColumns);
+
+      changes.push({
+        model: model.name,
+        table: model.table,
+        type: 'alter_table',
+        addedColumns: addedKeys,
+        removedColumns: removedColumnNames,
+        migrationName,
+        content,
+      });
+    }
+  }
+
+  return {
+    hasChanges: changes.length > 0,
+    changes,
+  };
+}
+
+/**
+ * High-level makemigrations execution: diffs schema and writes migration files
+ * @param {Object} options
+ * @param {import('knex').Knex} options.knex - Knex instance
+ * @param {string} [options.modelsDir='./models'] - Models directory
+ * @param {string} [options.migrationDir='./migrations'] - Target migrations directory
+ * @param {boolean} [options.dryRun=false] - Preview without writing files
+ * @param {boolean} [options.includeDrops=false] - Include dropColumn operations
+ * @param {string} [options.name] - Custom migration name override
+ * @returns {Promise<{ hasChanges: boolean, created: Array<Object>, skipped: Array<Object> }>}
+ */
+async function makeMigrations(options = {}) {
+  const {
+    knex,
+    modelsDir = './models',
+    migrationDir = './migrations',
+    dryRun = false,
+    includeDrops = false,
+    name = null,
+  } = options;
+
+  let models;
+  if (fs.existsSync(path.resolve(process.cwd(), modelsDir))) {
+    models = loadModelsFromDirectory(modelsDir);
+  } else {
+    models = [...getAllModels().values()];
+  }
+
+  const { hasChanges, changes } = await diffSchema({
+    knex,
+    models,
+    includeDrops,
+  });
+
+  const created = [];
+  const skipped = [];
+
+  if (!hasChanges) {
+    return { hasChanges: false, created, skipped };
+  }
+
+  const absoluteMigrationDir = path.resolve(process.cwd(), migrationDir);
+  if (!dryRun && !fs.existsSync(absoluteMigrationDir)) {
+    fs.mkdirSync(absoluteMigrationDir, { recursive: true });
+  }
+
+  changes.forEach((change, index) => {
+    const customName = name && changes.length === 1 ? name : change.migrationName;
+    const stamp = migrationTimestamp(new Date(Date.now() + index * 1000));
+    const filename = `${stamp}_${customName}.js`;
+    const filepath = path.join(absoluteMigrationDir, filename);
+
+    if (!dryRun) {
+      fs.writeFileSync(filepath, change.content, 'utf8');
+    }
+
+    created.push({
+      model: change.model,
+      table: change.table,
+      type: change.type,
+      addedColumns: change.addedColumns,
+      removedColumns: change.removedColumns,
+      file: filename,
+      path: filepath,
+      content: change.content,
+    });
+  });
+
+  return {
+    hasChanges: true,
+    created,
+    skipped,
+  };
+}
+
+module.exports = {
+  diffSchema,
+  makeMigrations,
+};

package/core/orm/migrations/index.js

@@ -167,11 +167,27 @@ function createMigrationManager(knex, config = {}) {
     },
 
     /**
-     * Unlock stuck migrations
-     * @returns {Promise<void>}
+     * Compare models with live database schema
+     * @param {Object} [options={}]
+     * @returns {Promise<{ hasChanges: boolean, changes: Array<Object> }>}
+     */
+    async diff(options = {}) {
+      const { diffSchema } = require('./diff');
+      return diffSchema({ knex, ...options });
+    },
+
+    /**
+     * Auto-generate migrations from schema diffs (Django-inspired makemigrations)
+     * @param {Object} [options={}]
+     * @returns {Promise<{ hasChanges: boolean, created: Array<Object>, skipped: Array<Object> }>}
      */
-    async unlock() {
-      await knex.migrate.forceFreeMigrationsLock(migrationConfig);
+    async makeMigrations(options = {}) {
+      const { makeMigrations } = require('./diff');
+      return makeMigrations({
+        knex,
+        migrationDir: directory,
+        ...options,
+      });
     },
   };
 }
@@ -201,5 +217,7 @@ exports.down = function(knex) {
 module.exports = {
   createMigrationManager,
   getDefaultMigrationTemplate,
+  diffSchema: require('./diff').diffSchema,
+  makeMigrations: require('./diff').makeMigrations,
 };
 

package/core/orm/model.js

@@ -138,6 +138,10 @@ function defineModel(options) {
       bulkActions: Array.isArray(admin.bulkActions) ? admin.bulkActions : null,
       hooks: typeof admin.hooks === 'object' && admin.hooks !== null ? admin.hooks : null,
       relations: typeof admin.relations === 'object' && admin.relations !== null ? admin.relations : null,
+      inlines: Array.isArray(admin.inlines) ? admin.inlines : null,
+      listEditable: Array.isArray(admin.listEditable) ? admin.listEditable : null,
+      dateHierarchy: typeof admin.dateHierarchy === 'string' ? admin.dateHierarchy : null,
+      listFilter: Array.isArray(admin.listFilter) ? admin.listFilter : (Array.isArray(admin.filterable) ? admin.filterable : null),
     },
     rest: {
       enabled: rest.enabled === true,