webspresso 0.0.97 → 0.0.99

package/core/orm/model.js

@@ -33,6 +33,7 @@ function defineModel(options) {
     hidden = [],
     queryLimits = {},
     cache: cacheOption,
+    searchable,
   } = options;
 
   // Validate required fields
@@ -107,6 +108,22 @@ function defineModel(options) {
       sortable: admin.sortable,
       sortableColumns: admin.sortableColumns,
       columns: admin.columns,
+      listColumns: Array.isArray(admin.listColumns) ? admin.listColumns : null,
+      searchFields: Array.isArray(admin.searchFields) ? admin.searchFields : null,
+      displayField: typeof admin.displayField === 'string' ? admin.displayField : null,
+      readOnly: admin.readOnly === true,
+      permissions: {
+        create: admin.permissions?.create !== false,
+        edit: admin.permissions?.edit !== false,
+        delete: admin.permissions?.delete !== false,
+      },
+      defaultSort: typeof admin.defaultSort === 'object' && admin.defaultSort !== null ? admin.defaultSort : null,
+      group: typeof admin.group === 'string' ? admin.group : (typeof admin.menuGroup === 'string' ? admin.menuGroup : null),
+      menuOrder: typeof admin.menuOrder === 'number' ? admin.menuOrder : 10,
+      actions: Array.isArray(admin.actions) ? admin.actions : null,
+      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,
     },
     rest: {
       enabled: rest.enabled === true,
@@ -115,6 +132,9 @@ function defineModel(options) {
       allowInclude: Array.isArray(rest.allowInclude) ? rest.allowInclude.filter((x) => typeof x === 'string') : null,
     },
     hidden: Array.isArray(hidden) ? hidden : [],
+    searchable: Array.isArray(searchable)
+      ? searchable
+      : (Array.isArray(admin.searchFields) ? admin.searchFields : null),
     queryLimits: typeof queryLimits === 'object' && queryLimits !== null ? queryLimits : {},
     hooks: {},
     cache: cacheOption,
@@ -152,13 +172,36 @@ function registerModelHooks(modelName, hooks) {
   }
 }
 
+/**
+ * Extract model name string from string, String object, or model definition/context
+ * @param {string|Object} nameOrModel - Model name or object
+ * @returns {string}
+ */
+function resolveModelName(nameOrModel) {
+  if (typeof nameOrModel === 'string') {
+    return nameOrModel;
+  }
+  if (nameOrModel && typeof nameOrModel === 'object') {
+    if (typeof nameOrModel.name === 'string') return nameOrModel.name;
+    if (typeof nameOrModel.modelName === 'string') return nameOrModel.modelName;
+    if (typeof nameOrModel.model === 'string') return nameOrModel.model;
+    if (typeof nameOrModel.valueOf === 'function') {
+      const val = nameOrModel.valueOf();
+      if (typeof val === 'string') return val;
+    }
+    return String(nameOrModel);
+  }
+  return nameOrModel != null ? String(nameOrModel) : '';
+}
+
 /**
  * Get a model by name
- * @param {string} name - Model name
+ * @param {string|Object} name - Model name
  * @returns {import('./types').ModelDefinition|undefined}
  */
 function getModel(name) {
-  return modelRegistry.get(name);
+  const modelName = resolveModelName(name);
+  return modelRegistry.get(modelName);
 }
 
 /**
@@ -171,11 +214,12 @@ function getAllModels() {
 
 /**
  * Check if a model exists
- * @param {string} name - Model name
+ * @param {string|Object} name - Model name
  * @returns {boolean}
  */
 function hasModel(name) {
-  return modelRegistry.has(name);
+  const modelName = resolveModelName(name);
+  return modelRegistry.has(modelName);
 }
 
 /**
@@ -187,11 +231,12 @@ function clearRegistry() {
 
 /**
  * Unregister a model by name
- * @param {string} name - Model name
+ * @param {string|Object} name - Model name
  * @returns {boolean} Whether the model was removed
  */
 function unregisterModel(name) {
-  return modelRegistry.delete(name);
+  const modelName = resolveModelName(name);
+  return modelRegistry.delete(modelName);
 }
 
 /**
@@ -201,7 +246,7 @@ function unregisterModel(name) {
  */
 function resolveRelationModel(relation) {
   let model = typeof relation.model === 'function' ? relation.model() : relation.model;
-  if (typeof model === 'string') {
+  if (typeof model === 'string' || (model && typeof model === 'object' && !model.table)) {
     model = getModel(model);
   }
   if (!model || !model.name) {
@@ -239,6 +284,7 @@ module.exports = {
   hasModel,
   clearRegistry,
   unregisterModel,
+  resolveModelName,
   resolveRelationModel,
   getRelationKeys,
   // Export registry for testing

package/core/orm/query-builder.js

@@ -15,6 +15,7 @@ const {
 } = require('./json-fields');
 const { getAmbientTransaction } = require('./transaction');
 const { validateQueryComplexity } = require('./complexity');
+const { buildSearchClause } = require('./search');
 
 /**
  * Create a new query builder
@@ -232,6 +233,70 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Add a raw ORDER BY clause
+   * @param {string} sql - Raw SQL expression
+   * @param {Array} [bindings=[]] - Parameter bindings
+   * @returns {this}
+   */
+  orderByRaw(sql, bindings = []) {
+    this.state.orderBys.push({ raw: true, sql, bindings });
+    return this;
+  }
+
+  /**
+   * Full-Text / Keyword Search across columns
+   * Supports SQLite, PostgreSQL, and MySQL with dialect-aware FTS and tokenized LIKE fallback
+   * @param {string} term - Search query string
+   * @param {string|string[]} [columns] - Columns to search (defaults to model.searchable)
+   * @param {Object} [options] - Search options
+   * @param {'auto'|'fts'|'like'} [options.mode='auto'] - Search mode
+   * @param {string} [options.language='english'] - PostgreSQL text search language
+   * @param {boolean} [options.matchAllWords=true] - Require all words to match (AND)
+   * @param {boolean} [options.exact=false] - Match exact phrase
+   * @param {boolean} [options.rank=false] - Order by relevance rank (Postgres)
+   * @param {string} [options.ftsTable] - Separate SQLite FTS virtual table name
+   * @returns {this}
+   */
+  search(term, columns, options = {}) {
+    const activeKnex = this.getActiveKnex();
+    const clause = buildSearchClause({
+      knex: activeKnex,
+      model: this.model,
+      term,
+      columns,
+      options,
+    });
+
+    if (!clause) {
+      return this;
+    }
+
+    this.state.wheres.push({
+      raw: true,
+      sql: clause.sql,
+      bindings: clause.bindings,
+      boolean: clause.boolean || 'and',
+    });
+
+    if (clause.rankClause) {
+      this.orderByRaw(clause.rankClause.sql, clause.rankClause.bindings);
+    }
+
+    return this;
+  }
+
+  /**
+   * Add an OR Full-Text / Keyword Search clause
+   * @param {string} term - Search query string
+   * @param {string|string[]} [columns] - Columns to search
+   * @param {Object} [options] - Search options
+   * @returns {this}
+   */
+  orSearch(term, columns, options = {}) {
+    return this.search(term, columns, { ...options, boolean: 'or' });
+  }
+
   /**
    * Set LIMIT
    * @param {number} limit - Limit value
@@ -265,6 +330,15 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Add relations to eager load (alias for with)
+   * @param {...string} relations - Relation names or nested paths (e.g. 'author.profile')
+   * @returns {this}
+   */
+  include(...relations) {
+    return this.with(...relations);
+  }
+
   /**
    * Include soft-deleted records
    * @returns {this}
@@ -376,7 +450,11 @@ class QueryBuilder {
 
     // Apply order by
     for (const orderBy of this.state.orderBys) {
-      qb = qb.orderBy(orderBy.column, orderBy.direction);
+      if (orderBy.raw) {
+        qb = qb.orderByRaw(orderBy.sql, orderBy.bindings);
+      } else {
+        qb = qb.orderBy(orderBy.column, orderBy.direction);
+      }
     }
 
     if (includeLimitOffset) {
@@ -416,7 +494,7 @@ class QueryBuilder {
 
       const withs = self.getWiths();
       if (withs.length > 0) {
-        await loadRelations([result], ensureArray(withs), self.model, self.knex, self.scopeContext);
+        await loadRelations([result], ensureArray(withs), self.model, self.getActiveKnex(), self.scopeContext);
       }
 
       ModelEvents.emit(self.model.name, Hooks.AFTER_FIND, result, ctx);
@@ -482,7 +560,7 @@ class QueryBuilder {
 
       const withs = self.getWiths();
       if (withs.length > 0 && results.length > 0) {
-        await loadRelations(results, ensureArray(withs), self.model, self.knex, self.scopeContext);
+        await loadRelations(results, ensureArray(withs), self.model, self.getActiveKnex(), self.scopeContext);
       }
 
       for (const record of results) {
@@ -527,6 +605,14 @@ class QueryBuilder {
     return this.list();
   }
 
+  /**
+   * Alias for list()
+   * @returns {Promise<Object[]>}
+   */
+  async find() {
+    return this.list();
+  }
+
   /**
    * Execute query and return count
    * @returns {Promise<number>}
@@ -613,7 +699,7 @@ class QueryBuilder {
 
       const withs = self.getWiths();
       if (withs.length > 0 && data.length > 0) {
-        await loadRelations(data, ensureArray(withs), self.model, self.knex, self.scopeContext);
+        await loadRelations(data, ensureArray(withs), self.model, self.getActiveKnex(), self.scopeContext);
       }
 
       for (const record of data) {

package/core/orm/repository.js

@@ -73,7 +73,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object|null>}
    */
   async function findById(id, options = {}, emitEvents = true) {
-    const { with: withs = [], select } = options;
+    const { with: withs = options.include || [], select } = options;
     const shouldEmit = emitEvents && (
       ModelEvents.hasListeners(model.name, Hooks.BEFORE_FIND) ||
       ModelEvents.hasListeners(model.name, Hooks.AFTER_FIND)
@@ -144,7 +144,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object|null>}
    */
   async function findOne(conditions, options = {}) {
-    const { with: withs = [], select } = options;
+    const { with: withs = options.include || [], select } = options;
     const shouldEmit = (
       ModelEvents.hasListeners(model.name, Hooks.BEFORE_FIND) ||
       ModelEvents.hasListeners(model.name, Hooks.AFTER_FIND)
@@ -230,7 +230,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object[]>}
    */
   async function findAll(options = {}) {
-    const { with: withs = [], select } = options;
+    const { with: withs = options.include || [], select } = options;
     const shouldEmit = (
       ModelEvents.hasListeners(model.name, Hooks.BEFORE_FIND) ||
       ModelEvents.hasListeners(model.name, Hooks.AFTER_FIND)
@@ -619,10 +619,49 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     return query().with(...relations);
   }
 
+  /**
+   * Find records matching conditions (with optional relations to eager load)
+   * @param {Object} [conditions={}] - WHERE conditions
+   * @param {import('./types').FindOptions} [options={}] - Find options
+   * @returns {Promise<Object[]>}
+   */
+  async function find(conditions = {}, options = {}) {
+    if (!conditions || Object.keys(conditions).length === 0) {
+      return findAll(options);
+    }
+    const withs = options.include || options.with || [];
+    let qb = query().where(conditions);
+    if (withs.length > 0) {
+      qb = qb.with(withs);
+    }
+    if (options.select && options.select.length > 0) {
+      qb = qb.select(options.select);
+    }
+    if (options.limit !== undefined) {
+      qb = qb.limit(options.limit);
+    }
+    if (options.offset !== undefined) {
+      qb = qb.offset(options.offset);
+    }
+    return qb.list();
+  }
+
+  /**
+   * Search records using Full-Text / Keyword Search
+   * @param {string} term - Search query
+   * @param {string|string[]} [columns] - Columns to search
+   * @param {Object} [options] - Search options
+   * @returns {import('./query-builder').QueryBuilder}
+   */
+  function search(term, columns, options) {
+    return query().search(term, columns, options);
+  }
+
   return {
     findById,
     findOne,
     findAll,
+    find,
     create,
     createMany,
     update,
@@ -631,10 +670,12 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     forceDelete,
     restore,
     query,
+    search,
     raw,
     count,
     exists,
     with: withRelations,
+    include: withRelations,
     // Expose model for introspection
     model,
   };

package/core/orm/search.js

@@ -0,0 +1,213 @@
+/**
+ * Webspresso ORM - Universal Full-Text Search (FTS)
+ * Database-agnostic full-text search abstraction for SQLite, PostgreSQL, and MySQL
+ * @module core/orm/search
+ */
+
+const { ensureArray } = require('./utils');
+
+/**
+ * Detect database dialect from Knex instance
+ * @param {import('knex').Knex} knex
+ * @returns {'sqlite'|'postgres'|'mysql'|'generic'}
+ */
+function detectDialect(knex) {
+  const client = knex?.client?.config?.client || knex?.client?.dialect || '';
+  const s = String(client).toLowerCase();
+  if (s.includes('sqlite')) return 'sqlite';
+  if (s.includes('pg') || s.includes('postgres')) return 'postgres';
+  if (s.includes('mysql') || s.includes('maria')) return 'mysql';
+  return 'generic';
+}
+
+/**
+ * Tokenize search term into clean tokens, supporting quoted exact phrases
+ * e.g. 'apple "macbook pro" laptop' -> ['apple', 'macbook pro', 'laptop']
+ * @param {string} term
+ * @returns {string[]}
+ */
+function tokenizeSearchTerm(term) {
+  if (!term || typeof term !== 'string') return [];
+  const matches = term.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+  return matches
+    .map((t) => t.replace(/^"|"$/g, '').trim())
+    .filter(Boolean);
+}
+
+/**
+ * Normalize and validate search columns for a model
+ * @param {Object} model
+ * @param {string|string[]} [columns]
+ * @returns {string[]}
+ */
+function normalizeSearchColumns(model, columns) {
+  if (columns != null && (Array.isArray(columns) ? columns.length > 0 : Boolean(columns))) {
+    return ensureArray(columns);
+  }
+
+  // Fallback to model searchable fields if configured
+  if (Array.isArray(model?.searchable) && model.searchable.length > 0) {
+    return model.searchable;
+  }
+  if (Array.isArray(model?.admin?.searchFields) && model.admin.searchFields.length > 0) {
+    return model.admin.searchFields;
+  }
+
+  throw new Error(
+    `No searchable columns specified for model "${model?.name || 'Unknown'}". Pass columns to .search(term, columns) or define searchable: [...] on the model.`
+  );
+}
+
+/**
+ * Build SQL search clause and parameter bindings
+ * @param {Object} params
+ * @param {import('knex').Knex} params.knex - Knex instance
+ * @param {Object} params.model - Model definition
+ * @param {string} params.term - Search query
+ * @param {string|string[]} [params.columns] - Columns to search
+ * @param {Object} [params.options] - Search options
+ * @param {'auto'|'fts'|'like'} [params.options.mode='auto'] - Search mode
+ * @param {string} [params.options.language='english'] - PostgreSQL text search configuration
+ * @param {boolean} [params.options.matchAllWords=true] - Require all words to match (AND vs OR)
+ * @param {boolean} [params.options.exact=false] - Treat entire term as exact substring
+ * @param {boolean} [params.options.rank=false] - Order by search relevance rank (Postgres)
+ * @param {string} [params.options.ftsTable] - Separate SQLite FTS virtual table name
+ * @param {'and'|'or'} [params.options.boolean='and'] - Where condition boolean operator
+ * @returns {{ raw: true, sql: string, bindings: any[], boolean: 'and'|'or', rankClause: Object|null }|null}
+ */
+function buildSearchClause({ knex, model, term, columns, options = {} }) {
+  if (!term || typeof term !== 'string' || !term.trim()) {
+    return null;
+  }
+
+  const cleanTerm = term.trim();
+  const searchColumns = normalizeSearchColumns(model, columns);
+  const dialect = detectDialect(knex);
+  const mode = options.mode || 'auto';
+  const language = options.language || 'english';
+  const matchAllWords = options.matchAllWords !== false;
+  const exact = options.exact === true;
+  const boolean = options.boolean === 'or' ? 'or' : 'and';
+  const rank = options.rank === true;
+
+  // 1. PostgreSQL Full-Text Search (when mode is 'fts' or 'auto' on postgres)
+  if (dialect === 'postgres' && (mode === 'fts' || mode === 'auto')) {
+    const colsSql = searchColumns
+      .map((c) => `COALESCE(${knex.ref(c)}::text, '')`)
+      .join(" || ' ' || ");
+
+    const queryFn = exact || cleanTerm.includes('"')
+      ? 'websearch_to_tsquery'
+      : 'plainto_tsquery';
+
+    const sql = `to_tsvector(?, ${colsSql}) @@ ${queryFn}(?, ?)`;
+    const bindings = [language, language, cleanTerm];
+
+    let rankClause = null;
+    if (rank) {
+      rankClause = {
+        sql: `ts_rank(to_tsvector(?, ${colsSql}), ${queryFn}(?, ?)) DESC`,
+        bindings: [language, language, cleanTerm],
+      };
+    }
+
+    return {
+      raw: true,
+      sql,
+      bindings,
+      boolean,
+      rankClause,
+    };
+  }
+
+  // 2. SQLite Native FTS5 (when mode is 'fts' on sqlite)
+  if (dialect === 'sqlite' && mode === 'fts') {
+    if (options.ftsTable) {
+      const ftsRef = knex.ref(options.ftsTable).toString();
+      const sql = `rowid IN (SELECT rowid FROM ${ftsRef} WHERE ${ftsRef} MATCH ?)`;
+      return {
+        raw: true,
+        sql,
+        bindings: [cleanTerm],
+        boolean,
+        rankClause: null,
+      };
+    }
+
+    const tableRef = knex.ref(model.table).toString();
+    const sql = `${tableRef} MATCH ?`;
+    return {
+      raw: true,
+      sql,
+      bindings: [cleanTerm],
+      boolean,
+      rankClause: null,
+    };
+  }
+
+  // 3. MySQL FullText (when mode is 'fts' on mysql)
+  if (dialect === 'mysql' && mode === 'fts') {
+    const colsList = searchColumns.map((c) => knex.ref(c).toString()).join(', ');
+    const sql = `MATCH(${colsList}) AGAINST(? IN BOOLEAN MODE)`;
+    return {
+      raw: true,
+      sql,
+      bindings: [cleanTerm],
+      boolean,
+      rankClause: null,
+    };
+  }
+
+  // 4. Universal Tokenized LIKE Search (default for SQLite, MySQL, and mode: 'like')
+  if (exact) {
+    const pattern = `%${cleanTerm}%`;
+    const bindings = [];
+    const colClauses = searchColumns.map((c) => {
+      bindings.push(pattern);
+      return `LOWER(${knex.ref(c)}) LIKE LOWER(?)`;
+    });
+
+    return {
+      raw: true,
+      sql: `(${colClauses.join(' OR ')})`,
+      bindings,
+      boolean,
+      rankClause: null,
+    };
+  }
+
+  const tokens = tokenizeSearchTerm(cleanTerm);
+  if (tokens.length === 0) {
+    return null;
+  }
+
+  const wordClauses = [];
+  const bindings = [];
+
+  for (const token of tokens) {
+    const pattern = `%${token}%`;
+    const colClauses = searchColumns.map((c) => {
+      bindings.push(pattern);
+      return `LOWER(${knex.ref(c)}) LIKE LOWER(?)`;
+    });
+    wordClauses.push(`(${colClauses.join(' OR ')})`);
+  }
+
+  const joinOp = matchAllWords ? ' AND ' : ' OR ';
+  const sql = `(${wordClauses.join(joinOp)})`;
+
+  return {
+    raw: true,
+    sql,
+    bindings,
+    boolean,
+    rankClause: null,
+  };
+}
+
+module.exports = {
+  detectDialect,
+  tokenizeSearchTerm,
+  normalizeSearchColumns,
+  buildSearchClause,
+};

package/core/queue/adapters/database.js

@@ -271,6 +271,100 @@ class DatabaseQueueAdapter {
     return stats;
   }
 
+  /**
+   * Delete completed or failed jobs older than a cutoff date
+   * @param {Object} [options={}]
+   * @param {string|string[]} [options.status=['completed']] - Job statuses to prune
+   * @param {Date|string|number} [options.olderThan] - Explicit cutoff date
+   * @param {number} [options.days=7] - Retention in days (used if olderThan not provided)
+   * @param {number} [options.retentionDays] - Alias for days
+   * @param {number} [options.limit] - Max number of records to delete
+   * @returns {Promise<number>} Number of deleted jobs
+   */
+  async clean(options = {}) {
+    await this.ensureTable();
+
+    let olderThan;
+    if (options.olderThan !== undefined) {
+      olderThan = options.olderThan instanceof Date
+        ? options.olderThan
+        : new Date(options.olderThan);
+
+      if (Number.isNaN(olderThan.getTime())) {
+        throw new Error('clean: invalid olderThan date');
+      }
+    } else {
+      const rawDays = options.days !== undefined
+        ? options.days
+        : (options.retentionDays !== undefined ? options.retentionDays : 7);
+      const days = typeof rawDays === 'number' ? rawDays : Number(rawDays);
+      if (Number.isNaN(days) || days < 0) {
+        throw new Error('clean: days must be a non-negative number');
+      }
+      olderThan = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+    }
+
+    let statuses = ['completed'];
+    if (options.status) {
+      if (Array.isArray(options.status)) {
+        statuses = options.status;
+      } else if (typeof options.status === 'string') {
+        if (options.status === '*' || options.status === 'all') {
+          statuses = ['completed', 'failed', 'pending'];
+        } else {
+          statuses = options.status.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+      }
+    }
+
+    const client = this.knex?.client?.config?.client;
+    const isSqlite = client === 'sqlite3' || client === 'better-sqlite3';
+
+    let query = this.knex(this.tableName);
+
+    if (statuses.length === 1) {
+      query = query.where('status', statuses[0]);
+    } else if (statuses.length > 1) {
+      query = query.whereIn('status', statuses);
+    }
+
+    if (isSqlite) {
+      const iso = olderThan.toISOString();
+      const cutoffMs = olderThan.getTime();
+      query = query.where((builder) => {
+        builder
+          .whereRaw(
+            "((typeof(updated_at) = 'integer' and updated_at < ?) or (typeof(updated_at) = 'text' and updated_at < ?))",
+            [cutoffMs, iso]
+          )
+          .orWhere((b2) => {
+            b2.whereNull('updated_at').andWhereRaw(
+              "((typeof(created_at) = 'integer' and created_at < ?) or (typeof(created_at) = 'text' and created_at < ?))",
+              [cutoffMs, iso]
+            );
+          });
+      });
+    } else {
+      query = query.where((builder) => {
+        builder.where('updated_at', '<', olderThan)
+          .orWhere((b2) => {
+            b2.whereNull('updated_at').andWhere('created_at', '<', olderThan);
+          });
+      });
+    }
+
+    if (typeof options.limit === 'number' && options.limit > 0) {
+      const rows = await query.clone().select('id').limit(options.limit);
+      if (rows.length === 0) return 0;
+      const ids = rows.map((r) => r.id);
+      const deleted = await this.knex(this.tableName).whereIn('id', ids).del();
+      return Number(deleted) || 0;
+    }
+
+    const deleted = await query.del();
+    return Number(deleted) || 0;
+  }
+
   /**
    * Clear all jobs from table
    * @returns {Promise<void>}