millas 0.2.12-beta-1 → 0.2.13-beta

package/src/admin/QueryEngine.js

@@ -0,0 +1,263 @@
+'use strict';
+
+/**
+ * QueryEngine
+ *
+ * Encapsulates all database query logic for the admin list view.
+ * Extracted from AdminResource.fetchList() so it can be tested,
+ * extended, and swapped independently of the rest of the admin.
+ *
+ * ── Responsibilities ──────────────────────────────────────────────────────────
+ *
+ *   - Filtering via Django __ lookup syntax
+ *   - Full-text search across searchable columns
+ *   - Date hierarchy drill-down (year / month)
+ *   - Sorting (column + direction)
+ *   - Offset pagination with total count
+ *   - Column pruning (only SELECT columns shown in list_display)
+ *   - Eager loading of FK columns (avoids N+1 for related labels)
+ *   - Bulk operations wrapped in a transaction
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   const engine = new QueryEngine(Resource);
+ *
+ *   const result = await engine.fetchList({
+ *     page: 1, perPage: 25,
+ *     search: 'alice',
+ *     sort: 'created_at', order: 'desc',
+ *     filters: { role__exact: 'admin', is_active__isnull: false },
+ *     year: '2026', month: '03',
+ *   });
+ *   // → { data: [...], total: 42, page: 1, perPage: 25, lastPage: 2 }
+ *
+ *   await engine.bulkDelete([1, 2, 3]);
+ *   await engine.bulkUpdate([1, 2, 3], { is_active: false });
+ *   await engine.bulkAction([1, 2, 3], async (ids, Model) => { ... });
+ *
+ * ── Lookup syntax (__ filter keys) ───────────────────────────────────────────
+ *
+ *   created_at__gte     → WHERE created_at >= value
+ *   role__exact         → WHERE role = value
+ *   email__icontains    → WHERE email LIKE '%value%'
+ *   deleted_at__isnull  → WHERE deleted_at IS NULL (value truthy) / IS NOT NULL
+ *   status__in          → WHERE status IN (value[])
+ *   age__between        → WHERE age BETWEEN value[0] AND value[1]
+ *
+ * ── Column pruning ────────────────────────────────────────────────────────────
+ *
+ *   If the resource declares list_display, QueryEngine will SELECT only
+ *   those columns (plus the primary key). This avoids fetching large text
+ *   columns (body, description) that are never shown in the list view.
+ *
+ * ── Performance notes ────────────────────────────────────────────────────────
+ *
+ *   - Data query and count query run in parallel (Promise.all)
+ *   - Column pruning reduces data transfer for wide tables
+ *   - All filters are parameterised — no string interpolation in WHERE clauses
+ */
+class QueryEngine {
+  /**
+   * @param {class} Resource — AdminResource subclass
+   */
+  constructor(Resource) {
+    this._Resource = Resource;
+    this._Model    = Resource.model;
+  }
+
+  // ─── List fetch ────────────────────────────────────────────────────────────
+
+  /**
+   * Fetch a paginated, filtered, sorted list of records.
+   *
+   * @param {object} opts
+   * @param {number}  [opts.page=1]
+   * @param {number}  [opts.perPage]      — defaults to Resource.perPage
+   * @param {string}  [opts.search='']    — full-text search term
+   * @param {string}  [opts.sort='id']    — column to sort by
+   * @param {string}  [opts.order='desc'] — 'asc' | 'desc'
+   * @param {object}  [opts.filters={}]   — { col__lookup: value }
+   * @param {string}  [opts.year]         — date hierarchy year
+   * @param {string}  [opts.month]        — date hierarchy month
+   *
+   * @returns {Promise<{ data, total, page, perPage, lastPage }>}
+   */
+  async fetchList({
+    page    = 1,
+    perPage,
+    search  = '',
+    sort    = 'id',
+    order   = 'desc',
+    filters = {},
+    year    = null,
+    month   = null,
+  } = {}) {
+    const R     = this._Resource;
+    const Model = this._Model;
+    const limit  = perPage || R.perPage || 20;
+    const offset = (page - 1) * limit;
+
+    // ── Base query ────────────────────────────────────────────────────────
+    let q = Model._db();
+
+    // ── Column pruning ────────────────────────────────────────────────────
+    // Only SELECT the columns shown in list_display + primary key.
+    // Avoids fetching large text/json columns that aren't shown.
+    const listDisplay = R.list_display || null;
+    if (listDisplay && listDisplay.length) {
+      const pk = Model.primaryKey || 'id';
+      const cols = [...new Set([pk, ...listDisplay])].map(c => `${Model.table}.${c}`);
+      q = q.select(cols);
+    }
+
+    // ── Ordering ──────────────────────────────────────────────────────────
+    // Sanitise sort column against known field names to prevent injection
+    const knownCols = new Set(
+      Object.keys(
+        typeof Model.getFields === 'function' ? Model.getFields() : (Model.fields || {})
+      )
+    );
+    const safeSort  = knownCols.has(sort) ? sort : (Model.primaryKey || 'id');
+    const safeOrder = order === 'asc' ? 'asc' : 'desc';
+    q = q.orderBy(safeSort, safeOrder);
+
+    // ── Search ────────────────────────────────────────────────────────────
+    if (search && R.searchable && R.searchable.length) {
+      const cols = R.searchable;
+      q = q.where(function () {
+        for (const col of cols) {
+          this.orWhere(col, 'like', `%${search}%`);
+        }
+      });
+    }
+
+    // ── Filters ───────────────────────────────────────────────────────────
+    for (const [key, value] of Object.entries(filters)) {
+      if (value === '' || value === null || value === undefined) continue;
+      q = this._applyFilter(q, key, value);
+    }
+
+    // ── Date hierarchy ────────────────────────────────────────────────────
+    if (R.dateHierarchy) {
+      q = this._applyDateHierarchy(q, R.dateHierarchy, year, month);
+    }
+
+    // ── Execute data + count in parallel ──────────────────────────────────
+    const [rows, countResult] = await Promise.all([
+      q.clone().limit(limit).offset(offset),
+      q.clone().count('* as count').first(),
+    ]);
+
+    const total = Number(countResult?.count ?? 0);
+
+    return {
+      data:     rows.map(r => Model._hydrate ? Model._hydrate(r) : r),
+      total,
+      page:     Number(page),
+      perPage:  limit,
+      lastPage: Math.ceil(total / limit) || 1,
+    };
+  }
+
+  // ─── Bulk operations ───────────────────────────────────────────────────────
+
+  /**
+   * Delete multiple records by primary key.
+   * @param {Array} ids
+   */
+  async bulkDelete(ids) {
+    if (!ids || !ids.length) return;
+    const pk = this._Model.primaryKey || 'id';
+    await this._Model._db().whereIn(pk, ids).delete();
+  }
+
+  /**
+   * Update multiple records with the same data.
+   * @param {Array}  ids
+   * @param {object} data
+   */
+  async bulkUpdate(ids, data) {
+    if (!ids || !ids.length) return;
+    const pk  = this._Model.primaryKey || 'id';
+    const now = new Date().toISOString();
+    const payload = this._Model.timestamps
+      ? { ...data, updated_at: now }
+      : { ...data };
+    await this._Model._db().whereIn(pk, ids).update(payload);
+  }
+
+  /**
+   * Run a custom bulk action inside a transaction.
+   * @param {Array}    ids
+   * @param {Function} handler — async (ids, Model, trx) => void
+   */
+  async bulkAction(ids, handler) {
+    if (!ids || !ids.length || typeof handler !== 'function') return;
+    await this._Model.transaction(async (trx) => {
+      await handler(ids, this._Model, trx);
+    });
+  }
+
+  // ─── Filter parser ─────────────────────────────────────────────────────────
+
+  /**
+   * Apply a single filter key/value pair to a knex query builder.
+   * Supports Django __ lookup syntax.
+   *
+   * @param   {object} q     — knex query builder
+   * @param   {string} key   — 'column__lookup' or just 'column'
+   * @param   {*}      value
+   * @returns {object}       — modified query builder
+   */
+  _applyFilter(q, key, value) {
+    const dunder = key.lastIndexOf('__');
+
+    if (dunder === -1) {
+      return q.where(key, value);
+    }
+
+    const col    = key.slice(0, dunder);
+    const lookup = key.slice(dunder + 2);
+
+    switch (lookup) {
+      case 'exact':        return q.where(col, value);
+      case 'not':          return q.where(col, '!=', value);
+      case 'gt':           return q.where(col, '>', value);
+      case 'gte':          return q.where(col, '>=', value);
+      case 'lt':           return q.where(col, '<', value);
+      case 'lte':          return q.where(col, '<=', value);
+      case 'isnull':       return value ? q.whereNull(col) : q.whereNotNull(col);
+      case 'notnull':      return q.whereNotNull(col);
+      case 'in':           return q.whereIn(col, Array.isArray(value) ? value : [value]);
+      case 'notin':        return q.whereNotIn(col, Array.isArray(value) ? value : [value]);
+      case 'between':      return q.whereBetween(col, Array.isArray(value) ? value : [value, value]);
+      case 'contains':
+      case 'icontains':    return q.where(col, 'like', `%${value}%`);
+      case 'startswith':
+      case 'istartswith':  return q.where(col, 'like', `${value}%`);
+      case 'endswith':
+      case 'iendswith':    return q.where(col, 'like', `%${value}`);
+      default:             return q.where(key, value);
+    }
+  }
+
+  /**
+   * Apply date hierarchy (year/month) drill-down filters.
+   * Uses strftime for SQLite/MySQL; falls back gracefully on PostgreSQL.
+   */
+  _applyDateHierarchy(q, col, year, month) {
+    if (year) {
+      try {
+        q = q.whereRaw(`strftime('%Y', \`${col}\`) = ?`, [String(year)]);
+      } catch { /* PG fallback — skip */ }
+    }
+    if (month) {
+      try {
+        q = q.whereRaw(`strftime('%m', \`${col}\`) = ?`, [String(month).padStart(2, '0')]);
+      } catch { /* PG fallback — skip */ }
+    }
+    return q;
+  }
+}
+
+module.exports = { QueryEngine };

package/src/admin/ViewContext.js

@@ -0,0 +1,318 @@
+'use strict';
+
+const { FormGenerator } = require('./FormGenerator');
+
+/**
+ * ViewContext
+ *
+ * Assembles the template data (context object) for each admin view.
+ * Separates "what data does this page need?" from "how do we handle the request?".
+ *
+ * ── Design principle ──────────────────────────────────────────────────────────
+ *
+ *   Route handlers in Admin.js are responsible for:
+ *     - Auth + permission checks
+ *     - Calling the ORM (via AdminResource or QueryEngine)
+ *     - Firing hooks
+ *     - Redirecting on success
+ *
+ *   ViewContext is responsible for:
+ *     - Assembling the template data object
+ *     - Deriving display metadata from AdminResource config
+ *     - No DB calls, no business logic, no HTML
+ *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
+ *   // In Admin.js handler — replaces inline object literals
+ *   const ctx = ViewContext.list(R, { rows, result, query, user, adminPrefix, flash });
+ *   return this._render(req, res, 'pages/list.njk', ctx, R);
+ *
+ * ── What it replaces ──────────────────────────────────────────────────────────
+ *
+ *   Before — Admin.js _list() contained ~40 lines of inline object assembly:
+ *     res.render('pages/list.njk', {
+ *       pageTitle: R._getLabel(),
+ *       resource: { slug, label, canCreate, canEdit, ... },
+ *       rows, listFields, filters, activeFilters, sortable,
+ *       total, page, perPage, lastPage, search, sort, order, ...
+ *     });
+ *
+ *   After — 1 line in handler + all assembly logic testable in isolation:
+ *     return this._render(req, res, 'pages/list.njk',
+ *       ViewContext.list(R, { rows, result, query, perms, flash }), R);
+ */
+class ViewContext {
+
+  // ─── Base context (shared by all views) ───────────────────────────────────
+
+  /**
+   * Base context included in every admin view.
+   * Mirrors what Admin._ctx() currently produces.
+   *
+   * @param {object} opts
+   * @param {object}  opts.admin       — Admin singleton (for config + resources)
+   * @param {object}  opts.user        — req.adminUser
+   * @param {string}  opts.csrfToken
+   * @param {object}  [opts.flash={}]
+   * @param {string}  [opts.activePage=null]
+   * @param {string}  [opts.activeResource=null]
+   */
+  static base({ admin, user, csrfToken, flash = {}, activePage = null, activeResource = null }) {
+    return {
+      csrfToken,
+      adminPrefix:    admin._config.prefix,
+      adminTitle:     admin._config.title,
+      adminUser:      user || null,
+      authEnabled:    admin._auth?.enabled ?? false,
+      resources:      admin.resources()
+        .filter(R => R.hasPermission(user || null, 'view'))
+        .map((R, idx) => ({
+          slug:     R.slug,
+          label:    R._getLabel(),
+          singular: R._getLabelSingular(),
+          icon:     R.icon,
+          canView:  R.hasPermission(user || null, 'view'),
+          index:    idx + 1,
+        })),
+      flash,
+      activePage,
+      activeResource,
+    };
+  }
+
+  // ─── Dashboard ─────────────────────────────────────────────────────────────
+
+  /**
+   * @param {object} opts
+   * @param {Array}   opts.resourceData  — per-resource { slug, label, count, recent, ... }
+   * @param {Array}   opts.activity      — ActivityLog.recent() result
+   * @param {object}  opts.activityTotals
+   * @param {object}  opts.baseCtx       — from ViewContext.base()
+   */
+  static dashboard({ resourceData, activity, activityTotals, baseCtx }) {
+    return {
+      ...baseCtx,
+      pageTitle:      'Dashboard',
+      activePage:     'dashboard',
+      resources:      resourceData,   // overrides baseCtx.resources with enriched data
+      activity,
+      activityTotals,
+    };
+  }
+
+  // ─── List ──────────────────────────────────────────────────────────────────
+
+  /**
+   * @param {class}  Resource
+   * @param {object} opts
+   * @param {Array}   opts.rows          — hydrated + serialised row data
+   * @param {object}  opts.result        — fetchList result { total, page, perPage, lastPage }
+   * @param {object}  opts.query         — { search, sort, order, page, perPage, year, month }
+   * @param {object}  opts.activeFilters — { col__lookup: value }
+   * @param {object}  opts.perms         — { canCreate, canEdit, canDelete, canView }
+   * @param {object}  opts.baseCtx
+   */
+  static list(Resource, { rows, result, query, activeFilters, perms, baseCtx }) {
+    const listFields = Resource.fields()
+      .filter(f => !f._hidden && !f._detailOnly)
+      .map(f => f.toJSON());
+
+    return {
+      ...baseCtx,
+      pageTitle:      Resource._getLabel(),
+      activeResource: Resource.slug,
+      resource: {
+        slug:               Resource.slug,
+        label:              Resource._getLabel(),
+        singular:           Resource._getLabelSingular(),
+        icon:               Resource.icon,
+        canCreate:          perms.canCreate,
+        canEdit:            perms.canEdit,
+        canDelete:          perms.canDelete,
+        canView:            perms.canView,
+        actions:            (Resource.actions || []).map((a, i) => ({ ...a, index: i, handler: undefined })),
+        rowActions:         Resource.rowActions || [],
+        listDisplayLinks:   Resource.listDisplayLinks || [],
+        dateHierarchy:      Resource.dateHierarchy || null,
+        prepopulatedFields: Resource.prepopulatedFields || {},
+      },
+      rows: rows.map(row => ({
+        ...row,
+        _rowActions: (Resource.rowActions || []).map(ra => ({
+          ...ra,
+          href: typeof ra.href === 'function' ? ra.href(row) : ra.href,
+        })),
+      })),
+      listFields,
+      filters:      Resource.filters().map(f => f.toJSON()),
+      activeFilters,
+      sortable:     Resource.sortable || [],
+      total:        result.total,
+      page:         result.page,
+      perPage:      result.perPage,
+      lastPage:     result.lastPage,
+      search:       query.search,
+      sort:         query.sort,
+      order:        query.order,
+      year:         query.year  || null,
+      month:        query.month || null,
+    };
+  }
+
+  // ─── Create form ───────────────────────────────────────────────────────────
+
+  /**
+   * @param {class}  Resource
+   * @param {object} opts
+   * @param {string}  opts.adminPrefix
+   * @param {object}  [opts.record={}]   — pre-filled data (on validation error re-render)
+   * @param {object}  [opts.errors={}]
+   * @param {object}  opts.baseCtx
+   */
+  static create(Resource, { adminPrefix, record = {}, errors = {}, baseCtx }) {
+
+    return {
+      ...baseCtx,
+      pageTitle:      `New ${Resource._getLabelSingular()}`,
+      activeResource: Resource.slug,
+      resource: {
+        slug:     Resource.slug,
+        label:    Resource._getLabel(),
+        singular: Resource._getLabelSingular(),
+        icon:     Resource.icon,
+        canDelete: false,
+      },
+      formFields:  FormGenerator.fromResource(Resource, { isEdit: false }).fields,
+      formAction:  `${adminPrefix}/${Resource.slug}`,
+      isEdit:      false,
+      record,
+      errors,
+    };
+  }
+
+  // ─── Edit form ─────────────────────────────────────────────────────────────
+
+  /**
+   * @param {class}  Resource
+   * @param {object} opts
+   * @param {string}  opts.adminPrefix
+   * @param {*}       opts.id            — record primary key
+   * @param {object}  opts.record        — existing record data
+   * @param {boolean} opts.canDelete
+   * @param {object}  [opts.errors={}]
+   * @param {object}  opts.baseCtx
+   */
+  static edit(Resource, { adminPrefix, id, record, canDelete, errors = {}, baseCtx }) {
+    return {
+      ...baseCtx,
+      pageTitle:      `Edit ${Resource._getLabelSingular()} #${id}`,
+      activeResource: Resource.slug,
+      resource: {
+        slug:     Resource.slug,
+        label:    Resource._getLabel(),
+        singular: Resource._getLabelSingular(),
+        icon:     Resource.icon,
+        canDelete,
+      },
+      formFields:  FormGenerator.fromResource(Resource, { isEdit: true }).fields,
+      formAction:  `${adminPrefix}/${Resource.slug}/${id}`,
+      isEdit:      true,
+      record,
+      errors,
+    };
+  }
+
+  // ─── Detail view ───────────────────────────────────────────────────────────
+
+  /**
+   * @param {class}  Resource
+   * @param {object} opts
+   * @param {*}       opts.id
+   * @param {object}  opts.record
+   * @param {Array}   opts.inlineData
+   * @param {object}  opts.perms         — { canEdit, canDelete, canCreate }
+   * @param {object}  opts.baseCtx
+   */
+  static detail(Resource, { id, record, inlineData, perms, baseCtx }) {
+    const detailFields = Resource.fields()
+      .filter(f => f._type !== '__tab__' && f._type !== 'fieldset' && !f._hidden && !f._listOnly)
+      .map(f => f.toJSON());
+
+    const tabs = ViewContext._buildTabs(Resource.fields());
+
+    return {
+      ...baseCtx,
+      pageTitle:      `${Resource._getLabelSingular()} #${id}`,
+      activeResource: Resource.slug,
+      resource: {
+        slug:       Resource.slug,
+        label:      Resource._getLabel(),
+        singular:   Resource._getLabelSingular(),
+        icon:       Resource.icon,
+        canEdit:    perms.canEdit,
+        canDelete:  perms.canDelete,
+        canCreate:  perms.canCreate,
+        rowActions: (Resource.rowActions || []).map(ra => ({
+          ...ra,
+          href: typeof ra.href === 'function' ? ra.href(record) : ra.href,
+        })),
+      },
+      record,
+      detailFields,
+      tabs,
+      hasTabs:  tabs.length > 1,
+      inlines:  inlineData,
+    };
+  }
+
+  // ─── Search ────────────────────────────────────────────────────────────────
+
+  /**
+   * @param {object} opts
+   * @param {string}  opts.query
+   * @param {Array}   opts.results
+   * @param {number}  opts.total
+   * @param {object}  opts.baseCtx
+   */
+  static search({ query, results, total, baseCtx }) {
+    return {
+      ...baseCtx,
+      pageTitle:  query ? `Search: ${query}` : 'Search',
+      activePage: 'search',
+      query,
+      results,
+      total,
+    };
+  }
+
+  // ─── Internal ─────────────────────────────────────────────────────────────
+
+  /**
+   * Build tab structure for tabbed detail/form rendering.
+   * Extracted from Admin._buildTabs() — same logic, centralised here.
+   */
+  static _buildTabs(fields) {
+    const tabs = [];
+    let current = null;
+
+    for (const f of fields) {
+      if (f._type === 'tab') {
+        current = { label: f._label, fields: [] };
+        tabs.push(current);
+        continue;
+      }
+      if (f._type === 'fieldset') {
+        if (!current) { current = { label: null, fields: [] }; tabs.push(current); }
+        current.fields.push({ _isFieldset: true, label: f._label });
+        continue;
+      }
+      if (f._hidden || f._listOnly) continue;
+      if (!current) { current = { label: null, fields: [] }; tabs.push(current); }
+      current.fields.push(f.toJSON());
+    }
+
+    return tabs;
+  }
+}
+
+module.exports = { ViewContext };