webspresso 0.0.102 → 0.0.104

package/core/orm/query-filters.js

@@ -0,0 +1,393 @@
+/**
+ * Webspresso ORM - Universal Query Filter Engine
+ *
+ * Unified column filtering engine powering both REST Resources and Admin Panel.
+ * Supports comparison operators, pattern matching, sets, ranges, nullability,
+ * and column type coercion.
+ *
+ * @module core/orm/query-filters
+ */
+
+'use strict';
+
+const RESERVED_QUERY_KEYS = new Set([
+  'page',
+  'perPage',
+  'per_page',
+  'limit',
+  'offset',
+  'sort',
+  'order',
+  'include',
+  'trashed',
+  'fields',
+  'select',
+  'search',
+  'q',
+]);
+
+/**
+ * Normalizes an operator name to canonical form
+ * @param {string} op
+ * @returns {string}
+ */
+function normalizeOperator(op) {
+  const s = String(op || 'contains').toLowerCase().trim();
+  switch (s) {
+    case 'equals':
+    case '=':
+    case 'eq':
+      return 'eq';
+
+    case 'ne':
+    case '!=':
+    case '<>':
+    case 'not_equals':
+    case 'notequals':
+      return 'ne';
+
+    case 'gt':
+    case '>':
+      return 'gt';
+
+    case 'gte':
+    case '>=':
+      return 'gte';
+
+    case 'lt':
+    case '<':
+      return 'lt';
+
+    case 'lte':
+    case '<=':
+      return 'lte';
+
+    case 'in':
+      return 'in';
+
+    case 'nin':
+    case 'notin':
+    case 'not_in':
+      return 'notin';
+
+    case 'like':
+      return 'like';
+
+    case 'ilike':
+      return 'ilike';
+
+    case 'contains':
+      return 'contains';
+
+    case 'starts_with':
+    case 'startswith':
+      return 'startswith';
+
+    case 'ends_with':
+    case 'endswith':
+      return 'endswith';
+
+    case 'is_null':
+    case 'isnull':
+    case 'null':
+      return 'is_null';
+
+    case 'is_not_null':
+    case 'isnotnull':
+    case 'not_null':
+    case 'notnull':
+      return 'is_not_null';
+
+    case 'between':
+      return 'between';
+
+    default:
+      return s;
+  }
+}
+
+/**
+ * Applies a single filter condition to one or more query builder instances
+ *
+ * @param {Array<Object>} targets - Query builder instances to mutate
+ * @param {string} column - Target column name
+ * @param {string} rawOp - Operator name
+ * @param {unknown} rawVal - Value or object containing from/to
+ * @param {Object} [meta] - Optional column metadata from model definition
+ */
+function applyFilterCondition(targets, column, rawOp, rawVal, meta = null) {
+  if (!targets || targets.length === 0) return;
+
+  const colType = meta?.type;
+  const operator = normalizeOperator(rawOp);
+  let val = rawVal;
+
+  // Handle boolean column type coercion
+  if (colType === 'boolean' && typeof val === 'string') {
+    if (val === 'true' || val === '1') {
+      val = true;
+    } else if (val === 'false' || val === '0') {
+      val = false;
+    }
+  }
+
+  // Handle nullability operators
+  if (operator === 'is_null') {
+    const isTrue = val === undefined || val === null || val === true || val === 'true' || val === '1' || val === 1 || val === '';
+    if (isTrue) {
+      for (const t of targets) t.whereNull(column);
+    }
+    return;
+  }
+
+  if (operator === 'is_not_null') {
+    const isTrue = val === undefined || val === null || val === true || val === 'true' || val === '1' || val === 1 || val === '';
+    if (isTrue) {
+      for (const t of targets) t.whereNotNull(column);
+    }
+    return;
+  }
+
+  // Handle between operator
+  if (operator === 'between') {
+    let from = undefined;
+    let to = undefined;
+
+    if (Array.isArray(val)) {
+      from = val[0];
+      to = val[1];
+    } else if (typeof val === 'string') {
+      const parts = val.split(',').map((s) => s.trim());
+      from = parts[0];
+      to = parts[1];
+    } else if (val && typeof val === 'object') {
+      from = val.from;
+      to = val.to;
+    }
+
+    const hasFrom = from !== undefined && from !== null && from !== '';
+    const hasTo = to !== undefined && to !== null && to !== '';
+
+    if (hasFrom && hasTo) {
+      for (const t of targets) {
+        t.where(column, '>=', from);
+        t.where(column, '<=', to);
+      }
+    } else if (hasFrom) {
+      for (const t of targets) t.where(column, '>=', from);
+    } else if (hasTo) {
+      for (const t of targets) t.where(column, '<=', to);
+    }
+    return;
+  }
+
+  // Handle in & notin
+  if (operator === 'in') {
+    const arr = Array.isArray(val)
+      ? val
+      : (typeof val === 'string' ? val.split(',').map((s) => s.trim()).filter(Boolean) : (val !== undefined && val !== '' ? [val] : []));
+    if (arr.length > 0) {
+      for (const t of targets) t.whereIn(column, arr);
+    }
+    return;
+  }
+
+  if (operator === 'notin') {
+    const arr = Array.isArray(val)
+      ? val
+      : (typeof val === 'string' ? val.split(',').map((s) => s.trim()).filter(Boolean) : (val !== undefined && val !== '' ? [val] : []));
+    if (arr.length > 0) {
+      for (const t of targets) t.whereNotIn(column, arr);
+    }
+    return;
+  }
+
+  // Ignore inactive empty values for standard scalar operators
+  if (val === undefined || val === null || val === '') {
+    return;
+  }
+
+  switch (operator) {
+    case 'contains':
+      for (const t of targets) t.where(column, 'like', `%${val}%`);
+      break;
+
+    case 'startswith':
+      for (const t of targets) t.where(column, 'like', `${val}%`);
+      break;
+
+    case 'endswith':
+      for (const t of targets) t.where(column, 'like', `%${val}`);
+      break;
+
+    case 'like':
+      for (const t of targets) t.where(column, 'like', String(val));
+      break;
+
+    case 'ilike':
+      for (const t of targets) t.where(column, 'ilike', String(val));
+      break;
+
+    case 'gt':
+      for (const t of targets) t.where(column, '>', val);
+      break;
+
+    case 'gte':
+      for (const t of targets) t.where(column, '>=', val);
+      break;
+
+    case 'lt':
+      for (const t of targets) t.where(column, '<', val);
+      break;
+
+    case 'lte':
+      for (const t of targets) t.where(column, '<=', val);
+      break;
+
+    case 'ne':
+      for (const t of targets) t.where(column, '!=', val);
+      break;
+
+    case 'eq':
+    default:
+      for (const t of targets) t.where(column, '=', val);
+      break;
+  }
+}
+
+/**
+ * Builds a query with filters applied (used by Admin Panel and Repositories)
+ *
+ * @param {Object} repoOrQuery - Repository instance or Knex QueryBuilder
+ * @param {Object} filters - Filter object: { column: { op, value, from, to } } or { column: value }
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.onlyTrashed] - For soft delete: only trashed records
+ * @param {Object} [options.model] - Optional ModelDefinition for column verification
+ * @returns {Object} Query builder with filters applied
+ */
+function buildFilteredQuery(repoOrQuery, filters, options = {}) {
+  let query = (repoOrQuery && typeof repoOrQuery.query === 'function')
+    ? repoOrQuery.query()
+    : repoOrQuery;
+
+  if (options.onlyTrashed && query && typeof query.onlyTrashed === 'function') {
+    query = query.onlyTrashed();
+  }
+
+  if (!filters || typeof filters !== 'object' || Object.keys(filters).length === 0) {
+    return query;
+  }
+
+  const model = options.model || (repoOrQuery && repoOrQuery.model);
+  const columns = model?.columns;
+
+  for (const [column, filter] of Object.entries(filters)) {
+    if (!filter) continue;
+    if (columns && typeof columns.has === 'function' && !columns.has(column)) {
+      continue;
+    }
+
+    const meta = columns && typeof columns.get === 'function' ? columns.get(column) : null;
+
+    if (typeof filter === 'object' && !Array.isArray(filter)) {
+      const rawOp = filter.op || filter.operator;
+      const normOp = rawOp ? normalizeOperator(rawOp) : null;
+      if (normOp === 'is_null' || normOp === 'is_not_null') {
+        applyFilterCondition([query], column, normOp, filter.value !== undefined ? filter.value : true, meta);
+      } else if (normOp === 'between') {
+        applyFilterCondition([query], column, rawOp, filter, meta);
+      } else if (filter.value !== undefined) {
+        applyFilterCondition([query], column, rawOp || 'contains', filter.value, meta);
+      } else {
+        for (const [nestedOp, nestedVal] of Object.entries(filter)) {
+          applyFilterCondition([query], column, nestedOp, nestedVal, meta);
+        }
+      }
+    } else {
+      applyFilterCondition([query], column, 'eq', filter, meta);
+    }
+  }
+
+  return query;
+}
+
+/**
+ * Extracts and applies column filters from an HTTP request or filter object to query builders
+ * (used by REST Resources and API routes)
+ *
+ * @param {Object} query - Main QueryBuilder
+ * @param {Object} [countQuery] - Optional Count QueryBuilder
+ * @param {import('./types').ModelDefinition} model - Model definition
+ * @param {import('express').Request|Object} reqOrQuery - Express request or query object
+ * @returns {{ query: Object, countQuery: Object }} Mutated query instances
+ */
+function applyColumnFilters(query, countQuery, model, reqOrQuery) {
+  const q = query;
+  const c = countQuery;
+  const targets = [q, c].filter(Boolean);
+
+  const rawQuery = (reqOrQuery && typeof reqOrQuery === 'object' && 'query' in reqOrQuery)
+    ? reqOrQuery.query
+    : (reqOrQuery || {});
+
+  if (!rawQuery || typeof rawQuery !== 'object') {
+    return { query: q, countQuery: c };
+  }
+
+  const hasColumns = model && model.columns && typeof model.columns.has === 'function';
+
+  // 1. Process dedicated filter object: ?filter[col]=... or ?filter[col][op]=... or ?filter={ col: { op, value } }
+  if (rawQuery.filter && typeof rawQuery.filter === 'object') {
+    for (const [col, colFilter] of Object.entries(rawQuery.filter)) {
+      if (hasColumns && !model.columns.has(col)) continue;
+      const meta = hasColumns ? model.columns.get(col) : null;
+
+      if (colFilter && typeof colFilter === 'object' && !Array.isArray(colFilter)) {
+        const rawColOp = colFilter.op || colFilter.operator;
+        const normColOp = rawColOp ? normalizeOperator(rawColOp) : null;
+        if (normColOp === 'is_null' || normColOp === 'is_not_null') {
+          applyFilterCondition(targets, col, normColOp, colFilter.value !== undefined ? colFilter.value : true, meta);
+        } else if (colFilter.op !== undefined && colFilter.value !== undefined) {
+          applyFilterCondition(targets, col, colFilter.op, colFilter.value, meta);
+        } else if (colFilter.from !== undefined || colFilter.to !== undefined) {
+          applyFilterCondition(targets, col, colFilter.op || 'between', colFilter, meta);
+        } else {
+          for (const [op, val] of Object.entries(colFilter)) {
+            applyFilterCondition(targets, col, op, val, meta);
+          }
+        }
+      } else if (colFilter !== undefined && colFilter !== '') {
+        applyFilterCondition(targets, col, 'eq', colFilter, meta);
+      }
+    }
+  }
+
+  // 2. Process top-level query parameters: ?price[gte]=100 or ?status=active
+  for (const [key, value] of Object.entries(rawQuery)) {
+    if (RESERVED_QUERY_KEYS.has(key) || key === 'filter') {
+      continue;
+    }
+    if (hasColumns && !model.columns.has(key)) {
+      continue;
+    }
+    const meta = hasColumns ? model.columns.get(key) : null;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      for (const [op, val] of Object.entries(value)) {
+        applyFilterCondition(targets, key, op, val, meta);
+      }
+    } else if (value !== undefined && value !== '') {
+      applyFilterCondition(targets, key, 'eq', value, meta);
+    }
+  }
+
+  return { query: q, countQuery: c };
+}
+
+module.exports = {
+  RESERVED_QUERY_KEYS,
+  normalizeOperator,
+  applyFilterCondition,
+  buildFilteredQuery,
+  applyColumnFilters,
+};

package/core/orm/repository.js

@@ -12,6 +12,7 @@ const {
   applyUpdateModifiers,
   getSoftDeleteData,
   getRestoreData,
+  getSoftDeleteColumn,
   createScopeContext,
   applyScopes,
 } = require('./scopes');
@@ -20,6 +21,24 @@ const { ModelEvents, createEventContext, Hooks, HookCancellationError } = requir
 const { getJsonColumns, serializeJsonFields, deserializeJsonFields } = require('./json-fields');
 const { getAmbientTransaction } = require('./transaction');
 
+/**
+ * Get or cache partial schema for model
+ * @param {import('./types').ModelDefinition} model
+ * @returns {import('zod').ZodTypeAny}
+ */
+function getPartialSchema(model) {
+  if (model && model._partialSchema) {
+    return model._partialSchema;
+  }
+  const partial = (model && model.schema && typeof model.schema.partial === 'function')
+    ? model.schema.partial()
+    : model?.schema;
+  if (model) {
+    model._partialSchema = partial;
+  }
+  return partial;
+}
+
 /**
  * Create a repository for a model
  * @param {import('./types').ModelDefinition} model - Model definition
@@ -29,7 +48,7 @@ const { getAmbientTransaction } = require('./transaction');
  * @returns {import('./types').Repository}
  */
 function createRepository(model, knex, initialContext, cacheLayer = null) {
-  const scopeContext = initialContext || createScopeContext();
+  const scopeContext = initialContext ? { ...initialContext } : createScopeContext();
   const jsonColumns = getJsonColumns(model);
   const hasJson = jsonColumns.size > 0;
 
@@ -302,7 +321,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     // Validate with Zod schema (partial for insert - allows auto fields to be missing)
-    const validated = model.schema.partial().parse(workingData);
+    const validated = getPartialSchema(model).parse(workingData);
 
     // Emit afterValidation
     ModelEvents.emit(model.name, Hooks.AFTER_VALIDATION, validated, ctx);
@@ -381,7 +400,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     // Validate with Zod schema (partial for update)
-    const validated = model.schema.partial().parse(workingData);
+    const validated = getPartialSchema(model).parse(workingData);
 
     // Emit afterValidation
     ModelEvents.emit(model.name, Hooks.AFTER_VALIDATION, validated, ctx);
@@ -438,7 +457,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    */
   async function updateWhere(conditions, data) {
     // Validate with Zod schema (partial for update)
-    const validated = model.schema.partial().parse(data);
+    const validated = getPartialSchema(model).parse(data);
 
     // Apply update modifiers (timestamps)
     let updateData = applyUpdateModifiers(validated, model);
@@ -493,9 +512,10 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       const parentVal = record[localKey];
       if (parentVal === undefined || parentVal === null) continue;
 
+      const deletedCol = getSoftDeleteColumn(relatedModel);
       let childQuery = activeKnex(relatedModel.table)
         .where(foreignKey, parentVal)
-        .whereNull('deleted_at');
+        .whereNull(deletedCol);
 
       if (scopeContext && scopeContext.tenantId !== undefined && relatedModel.scopes.tenant) {
         childQuery = childQuery.where(relatedModel.scopes.tenant, scopeContext.tenantId);
@@ -508,7 +528,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
 
       await activeKnex(relatedModel.table)
         .whereIn(relatedModel.primaryKey, childIds)
-        .update(getSoftDeleteData(deletedAt));
+        .update(getSoftDeleteData(deletedAt, relatedModel));
 
       if (cacheLayer) {
         cacheLayer.invalidateModelAll(relatedModel);
@@ -637,9 +657,10 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       const parentVal = trashedRecord[localKey];
       if (parentVal === undefined || parentVal === null) continue;
 
+      const deletedCol = getSoftDeleteColumn(relatedModel);
       let childQuery = activeKnex(relatedModel.table)
         .where(foreignKey, parentVal)
-        .whereNotNull('deleted_at');
+        .whereNotNull(deletedCol);
 
       if (scopeContext && scopeContext.tenantId !== undefined && relatedModel.scopes.tenant) {
         childQuery = childQuery.where(relatedModel.scopes.tenant, scopeContext.tenantId);
@@ -647,7 +668,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
 
       // Selective restore by matching deletion timestamp
       if (!options.allChildren && parentDeletedAt != null) {
-        childQuery = childQuery.where('deleted_at', parentDeletedAt);
+        childQuery = childQuery.where(deletedCol, parentDeletedAt);
       }
 
       const children = await childQuery.select('*');
@@ -658,14 +679,15 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       );
       if (hasDeeper) {
         for (const child of children) {
-          await cascadeRestore(relatedModel, child, child.deleted_at || parentDeletedAt, options, visited);
+          const childDeletedAt = child[deletedCol] || child.deleted_at || parentDeletedAt;
+          await cascadeRestore(relatedModel, child, childDeletedAt, options, visited);
         }
       }
 
       const childIds = children.map(c => c[relatedModel.primaryKey]);
       await activeKnex(relatedModel.table)
         .whereIn(relatedModel.primaryKey, childIds)
-        .update(getRestoreData());
+        .update(getRestoreData(relatedModel));
 
       if (cacheLayer) {
         cacheLayer.invalidateModelAll(relatedModel);
@@ -674,7 +696,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       if (ModelEvents.hasListeners(relatedModel.name, Hooks.AFTER_RESTORE)) {
         for (const child of children) {
           const childCtx = createEventContext(relatedModel.name, 'restore', getHookTrx());
-          ModelEvents.emit(relatedModel.name, Hooks.AFTER_RESTORE, { ...child, deleted_at: null }, childCtx);
+          ModelEvents.emit(relatedModel.name, Hooks.AFTER_RESTORE, { ...child, [deletedCol]: null, deleted_at: null }, childCtx);
         }
       }
     }
@@ -708,7 +730,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     if (model.scopes.softDelete) {
       const updated = await baseQuery()
         .where(model.primaryKey, id)
-        .update(getSoftDeleteData(deletedAt));
+        .update(getSoftDeleteData(deletedAt, model));
       success = updated > 0;
 
       if (success) {
@@ -791,10 +813,12 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
 
     const ctx = createEventContext(model.name, 'restore', getHookTrx());
 
+    const deletedCol = getSoftDeleteColumn(model);
+
     // Get the trashed record for hooks (bypass soft delete scope)
     const trashedRecord = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
-      .whereNotNull('deleted_at')
+      .whereNotNull(deletedCol)
       .first();
 
     if (!trashedRecord) {
@@ -810,8 +834,8 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     // Update directly without scopes (to find trashed record)
     const updated = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
-      .whereNotNull('deleted_at')
-      .update(getRestoreData());
+      .whereNotNull(deletedCol)
+      .update(getRestoreData(model));
 
     if (updated === 0) {
       return null;
@@ -822,7 +846,8 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     if (!options || options.cascade !== false) {
-      await cascadeRestore(model, trashedRecord, trashedRecord.deleted_at, options);
+      const parentDeletedAt = trashedRecord[deletedCol] || trashedRecord.deleted_at;
+      await cascadeRestore(model, trashedRecord, parentDeletedAt, options);
     }
 
     const record = await findById(id, {}, false);
@@ -838,7 +863,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {import('./query-builder').QueryBuilder}
    */
   function query() {
-    return createQueryBuilder(model, getActiveKnex(), scopeContext, cacheLayer);
+    return createQueryBuilder(model, getActiveKnex(), { ...scopeContext }, cacheLayer);
   }
 
   /**

package/core/orm/schema-helpers.js

@@ -778,6 +778,55 @@ function createSchemaHelpers(z) {
         ...rest,
       }, z);
     },
+
+    /**
+     * Timestamp pair columns (createdAt and updatedAt)
+     * @param {Object} [options={}]
+     * @param {boolean} [options.snakeCase=false] - Use snake_case (created_at, updated_at)
+     * @param {string} [options.createdAt] - Custom created column name
+     * @param {string} [options.updatedAt] - Custom updated column name
+     * @returns {{ [key: string]: SchemaBuilder }}
+     */
+    timestamps(options = {}) {
+      const isSnake = options.snakeCase || options.format === 'snake';
+      const createdKey = options.createdAt || (isSnake ? 'created_at' : 'createdAt');
+      const updatedKey = options.updatedAt || (isSnake ? 'updated_at' : 'updatedAt');
+
+      return {
+        [createdKey]: helpers.timestamp({ auto: 'create', ...options }),
+        [updatedKey]: helpers.timestamp({ auto: 'update', ...options }),
+      };
+    },
+
+    /**
+     * Soft delete column helper (returns a single SchemaBuilder for deletedAt/deleted_at)
+     * @param {Partial<import('./types').ColumnMeta>} [options={}]
+     * @returns {SchemaBuilder}
+     */
+    softDelete(options = {}) {
+      return helpers.timestamp({
+        nullable: true,
+        ...options,
+      });
+    },
+
+    /**
+     * Soft delete field object (returns { deletedAt: SchemaBuilder } or { deleted_at: SchemaBuilder })
+     * @param {Object} [options={}]
+     * @param {boolean} [options.snakeCase=false] - Use snake_case (deleted_at)
+     * @param {string} [options.deletedAt] - Custom deleted column name
+     * @returns {{ [key: string]: SchemaBuilder }}
+     */
+    softDeletes(options = {}) {
+      const isSnake = options.snakeCase || options.format === 'snake';
+      const deletedKey = options.deletedAt || (isSnake ? 'deleted_at' : 'deletedAt');
+      return {
+        [deletedKey]: helpers.timestamp({
+          nullable: true,
+          ...options,
+        }),
+      };
+    },
   };
 
   return helpers;