jsgui3-server 0.0.151 → 0.0.152

package/resources/adapters/array-adapter.js

@@ -0,0 +1,143 @@
+/**
+ * Array_Adapter — in-memory data adapter for Query_Resource.
+ *
+ * Applies sort, filter, and pagination to a plain JS array.
+ * Useful for prototyping, small datasets, and tests.
+ *
+ * @example
+ *   const adapter = new Array_Adapter({ data: my_array });
+ *   const result = await adapter.query({
+ *       page: 1,
+ *       page_size: 25,
+ *       sort: { key: 'name', dir: 'asc' },
+ *       filters: { name: { op: 'contains', value: 'alice' } }
+ *   });
+ *   // => { rows: [...], total_count: 142 }
+ */
+
+const FILTER_OPS = {
+    contains(cell, value) {
+        return String(cell).toLowerCase().includes(String(value).toLowerCase());
+    },
+    equals(cell, value) {
+        // eslint-disable-next-line eqeqeq
+        return cell == value;
+    },
+    strict_equals(cell, value) {
+        return cell === value;
+    },
+    gt(cell, value) {
+        return Number(cell) > Number(value);
+    },
+    gte(cell, value) {
+        return Number(cell) >= Number(value);
+    },
+    lt(cell, value) {
+        return Number(cell) < Number(value);
+    },
+    lte(cell, value) {
+        return Number(cell) <= Number(value);
+    },
+    not_equals(cell, value) {
+        // eslint-disable-next-line eqeqeq
+        return cell != value;
+    }
+};
+
+class Array_Adapter {
+    /**
+     * @param {Object} spec
+     * @param {Array}  spec.data - The source array (kept by reference).
+     */
+    constructor(spec = {}) {
+        this.data = spec.data || [];
+    }
+
+    /**
+     * Replace the underlying data.
+     * @param {Array} data
+     */
+    set_data(data) {
+        this.data = data || [];
+    }
+
+    /**
+     * Query the data with sort, filter, and pagination.
+     *
+     * @param {Object}       params
+     * @param {number}       [params.page=1]
+     * @param {number}       [params.page_size=25]
+     * @param {Object|null}  [params.sort]         - { key: string, dir: 'asc'|'desc' }
+     * @param {Object|null}  [params.filters]      - { column_key: { op: string, value: * }, ... }
+     * @returns {Promise<{rows: Array, total_count: number}>}
+     */
+    async query(params = {}) {
+        let rows = this.data.slice();
+
+        // ── Filter ──────────────────────────────────────────────
+        if (params.filters && typeof params.filters === 'object') {
+            const filter_entries = Object.entries(params.filters);
+            for (const [key, filter_spec] of filter_entries) {
+                if (!filter_spec) continue;
+
+                let op_name, filter_value;
+                if (typeof filter_spec === 'object' && filter_spec.op) {
+                    op_name = filter_spec.op;
+                    filter_value = filter_spec.value;
+                } else {
+                    // Shorthand: { name: 'alice' } implies contains
+                    op_name = 'contains';
+                    filter_value = filter_spec;
+                }
+
+                const op_fn = FILTER_OPS[op_name];
+                if (!op_fn) continue;
+
+                rows = rows.filter(row => {
+                    const cell = row[key];
+                    return op_fn(cell, filter_value);
+                });
+            }
+        }
+
+        const total_count = rows.length;
+
+        // ── Sort ────────────────────────────────────────────────
+        if (params.sort && params.sort.key) {
+            const sort_key = params.sort.key;
+            const dir = String(params.sort.dir || 'asc').toLowerCase() === 'desc' ? -1 : 1;
+
+            rows.sort((a, b) => {
+                const av = a[sort_key];
+                const bv = b[sort_key];
+
+                if (av === bv) return 0;
+                if (av === null || av === undefined) return 1;
+                if (bv === null || bv === undefined) return -1;
+
+                if (typeof av === 'number' && typeof bv === 'number') {
+                    return (av - bv) * dir;
+                }
+
+                return String(av).localeCompare(String(bv)) * dir;
+            });
+        }
+
+        // ── Paginate ────────────────────────────────────────────
+        const page_size = Math.max(1, Number(params.page_size) || 25);
+        const page = Math.max(1, Number(params.page) || 1);
+        const start = (page - 1) * page_size;
+        const paged_rows = rows.slice(start, start + page_size);
+
+        return {
+            rows: paged_rows,
+            total_count,
+            page,
+            page_size
+        };
+    }
+}
+
+Array_Adapter.FILTER_OPS = FILTER_OPS;
+
+module.exports = Array_Adapter;

package/resources/query-resource.js

@@ -0,0 +1,131 @@
+/**
+ * Query_Resource — a Resource subclass that holds a data adapter
+ * and exposes a standard query(params) method.
+ *
+ * Pluggable adapters let you swap the backing store (in-memory array,
+ * SQL database, REST API, etc.) while keeping a uniform interface.
+ *
+ * @example
+ *   const Query_Resource = require('jsgui3-server/resources/query-resource');
+ *   const Array_Adapter  = require('jsgui3-server/resources/adapters/array-adapter');
+ *
+ *   const resource = new Query_Resource({
+ *       name: 'products',
+ *       adapter: new Array_Adapter({ data: products }),
+ *       schema: {
+ *           columns: [
+ *               { key: 'name',  label: 'Name',  sortable: true, filterable: true },
+ *               { key: 'price', label: 'Price', sortable: true }
+ *           ],
+ *           default_page_size: 25
+ *       }
+ *   });
+ */
+
+const { Resource } = require('jsgui3-html');
+
+const DEFAULT_PAGE_SIZE = 25;
+const MAX_PAGE_SIZE = 1000;
+
+class Query_Resource extends Resource {
+    /**
+     * @param {Object}  spec
+     * @param {string}  spec.name              - Resource name (visible in admin-ui / resource pool).
+     * @param {Object}  spec.adapter           - Data adapter with a `query(params)` method.
+     * @param {Object}  [spec.schema]          - Column definitions, default_page_size, etc.
+     */
+    constructor(spec = {}) {
+        super(spec);
+        if (!spec.adapter || typeof spec.adapter.query !== 'function') {
+            throw new Error('Query_Resource requires an adapter with a query(params) method.');
+        }
+        this.adapter = spec.adapter;
+        this.schema = spec.schema || {};
+        this.default_page_size = (this.schema && this.schema.default_page_size) || DEFAULT_PAGE_SIZE;
+    }
+
+    /**
+     * Start the resource (and the adapter if it supports it).
+     */
+    start(callback) {
+        if (this.adapter && typeof this.adapter.start === 'function') {
+            const result = this.adapter.start();
+            if (result && typeof result.then === 'function') {
+                return result.then(
+                    () => { if (typeof callback === 'function') callback(null, true); },
+                    (err) => { if (typeof callback === 'function') callback(err); else throw err; }
+                );
+            }
+        }
+        if (typeof callback === 'function') callback(null, true);
+        return Promise.resolve(true);
+    }
+
+    /**
+     * Stop the resource (and the adapter if it supports it).
+     */
+    stop(callback) {
+        if (this.adapter && typeof this.adapter.stop === 'function') {
+            const result = this.adapter.stop();
+            if (result && typeof result.then === 'function') {
+                return result.then(
+                    () => { if (typeof callback === 'function') callback(null, true); },
+                    (err) => { if (typeof callback === 'function') callback(err); else throw err; }
+                );
+            }
+        }
+        if (typeof callback === 'function') callback(null, true);
+        return Promise.resolve(true);
+    }
+
+    /**
+     * Normalize and validate query params, then delegate to the adapter.
+     *
+     * @param {Object} params - Raw query params from the client.
+     * @returns {Promise<{rows: Array, total_count: number, page: number, page_size: number}>}
+     */
+    async query(params = {}) {
+        const normalized = this._normalize_params(params);
+        const result = await this.adapter.query(normalized);
+
+        // Ensure the response has the standard shape.
+        return {
+            rows: Array.isArray(result.rows) ? result.rows : [],
+            total_count: Number.isFinite(result.total_count) ? result.total_count : 0,
+            page: normalized.page,
+            page_size: normalized.page_size
+        };
+    }
+
+    /**
+     * Normalize raw params into a clean query spec.
+     * @private
+     */
+    _normalize_params(params = {}) {
+        const page = Math.max(1, Math.floor(Number(params.page) || 1));
+        const raw_page_size = Number(params.page_size);
+        const page_size = Number.isFinite(raw_page_size) && raw_page_size > 0
+            ? Math.min(Math.floor(raw_page_size), MAX_PAGE_SIZE)
+            : this.default_page_size;
+
+        let sort = null;
+        if (params.sort && typeof params.sort === 'object' && params.sort.key) {
+            sort = {
+                key: String(params.sort.key),
+                dir: String(params.sort.dir || 'asc').toLowerCase() === 'desc' ? 'desc' : 'asc'
+            };
+        }
+
+        let filters = null;
+        if (params.filters && typeof params.filters === 'object') {
+            filters = params.filters;
+        }
+
+        return { page, page_size, sort, filters };
+    }
+}
+
+Query_Resource.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
+Query_Resource.MAX_PAGE_SIZE = MAX_PAGE_SIZE;
+
+module.exports = Query_Resource;