zero-http 0.2.4 → 0.3.1

package/lib/orm/adapters/json.js

@@ -0,0 +1,215 @@
+/**
+ * @module orm/adapters/json
+ * @description JSON file-backed database adapter.
+ *              Persists data to JSON files on disk — one file per table.
+ *              Zero-dependency, suitable for prototyping, small apps, and
+ *              embedded scenarios. Uses atomic writes for safety.
+ */
+const fs = require('fs');
+const path = require('path');
+const MemoryAdapter = require('./memory');
+
+class JsonAdapter extends MemoryAdapter
+{
+    /**
+     * @param {object}  options
+     * @param {string}  options.dir                 - Directory to store JSON files. Created if needed.
+     * @param {boolean} [options.pretty=true]        - Pretty-print JSON files.
+     * @param {number}  [options.flushInterval=50]   - Debounce interval in ms for writes.
+     * @param {boolean} [options.autoFlush=true]     - Automatically flush writes (set false for manual flush()).
+     */
+    constructor(options = {})
+    {
+        super();
+        if (!options.dir) throw new Error('JsonAdapter requires a "dir" option');
+
+        /** @private */ this._dir = path.resolve(options.dir);
+        /** @private */ this._pretty = options.pretty !== false;
+        /** @private */ this._dirty = new Set();
+        /** @private */ this._flushTimer = null;
+        /** @private */ this._flushInterval = options.flushInterval || 50;
+        /** @private */ this._autoFlush = options.autoFlush !== false;
+
+        // Ensure directory exists
+        if (!fs.existsSync(this._dir))
+        {
+            fs.mkdirSync(this._dir, { recursive: true });
+        }
+
+        // Load any existing tables
+        try
+        {
+            const files = fs.readdirSync(this._dir).filter(f => f.endsWith('.json'));
+            for (const file of files)
+            {
+                const table = path.basename(file, '.json');
+                const content = fs.readFileSync(path.join(this._dir, file), 'utf8');
+                const parsed = JSON.parse(content);
+                this._tables.set(table, parsed.rows || []);
+                this._autoIncrements.set(table, parsed.autoIncrement || 1);
+            }
+        }
+        catch (e) { /* fresh start */ }
+    }
+
+    /** @override */
+    async createTable(table, schema)
+    {
+        await super.createTable(table, schema);
+        this._scheduleSave(table);
+    }
+
+    /** @override */
+    async dropTable(table)
+    {
+        await super.dropTable(table);
+        const filePath = path.join(this._dir, `${table}.json`);
+        try { fs.unlinkSync(filePath); } catch (e) { /* ignore */ }
+    }
+
+    /** @override */
+    async insert(table, data)
+    {
+        const result = await super.insert(table, data);
+        this._scheduleSave(table);
+        return result;
+    }
+
+    /** @override */
+    async update(table, pk, pkVal, data)
+    {
+        await super.update(table, pk, pkVal, data);
+        this._scheduleSave(table);
+    }
+
+    /** @override */
+    async updateWhere(table, conditions, data)
+    {
+        const count = await super.updateWhere(table, conditions, data);
+        if (count > 0) this._scheduleSave(table);
+        return count;
+    }
+
+    /** @override */
+    async remove(table, pk, pkVal)
+    {
+        await super.remove(table, pk, pkVal);
+        this._scheduleSave(table);
+    }
+
+    /** @override */
+    async deleteWhere(table, conditions)
+    {
+        const count = await super.deleteWhere(table, conditions);
+        if (count > 0) this._scheduleSave(table);
+        return count;
+    }
+
+    /** @override */
+    async clear()
+    {
+        await super.clear();
+        for (const table of this._tables.keys()) this._scheduleSave(table);
+    }
+
+    /**
+     * Immediately flush all pending writes.
+     */
+    async flush()
+    {
+        for (const table of this._dirty) this._saveTable(table);
+        this._dirty.clear();
+        if (this._flushTimer) { clearTimeout(this._flushTimer); this._flushTimer = null; }
+    }
+
+    /** @private Schedule a debounced save for the given table. */
+    _scheduleSave(table)
+    {
+        this._dirty.add(table);
+        if (this._autoFlush && !this._flushTimer)
+        {
+            this._flushTimer = setTimeout(() =>
+            {
+                this.flush();
+            }, this._flushInterval);
+        }
+    }
+
+    /** @private Write table data to JSON file. */
+    _saveTable(table)
+    {
+        const filePath = path.join(this._dir, `${table}.json`);
+        const data = {
+            autoIncrement: this._autoIncrements.get(table) || 1,
+            rows: this._tables.get(table) || [],
+        };
+        const json = this._pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+
+        // Atomic write: write to temp file then rename
+        const tmpPath = filePath + '.tmp';
+        fs.writeFileSync(tmpPath, json, 'utf8');
+        fs.renameSync(tmpPath, filePath);
+    }
+
+    // -- JSON Adapter Utilities --------------------------
+
+    /**
+     * Get the directory where JSON files are stored.
+     * @returns {string}
+     */
+    get directory() { return this._dir; }
+
+    /**
+     * Get the total size of all JSON files in bytes.
+     * @returns {number}
+     */
+    fileSize()
+    {
+        let total = 0;
+        try
+        {
+            const files = fs.readdirSync(this._dir).filter(f => f.endsWith('.json'));
+            for (const file of files)
+            {
+                total += fs.statSync(path.join(this._dir, file)).size;
+            }
+        }
+        catch { /* empty dir, no files */ }
+        return total;
+    }
+
+    /**
+     * Check if there are pending writes that haven't been flushed.
+     * @returns {boolean}
+     */
+    get hasPendingWrites() { return this._dirty.size > 0; }
+
+    /**
+     * Compact a specific table's JSON file (re-serialize, removes whitespace bloat).
+     * @param {string} table
+     */
+    compact(table)
+    {
+        if (this._tables.has(table)) this._saveTable(table);
+    }
+
+    /**
+     * Back up the entire data directory to a target path.
+     * @param {string} destDir - Destination directory (will be created).
+     */
+    backup(destDir)
+    {
+        const dest = path.resolve(destDir);
+        if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+        const files = fs.readdirSync(this._dir).filter(f => f.endsWith('.json'));
+        for (const file of files)
+        {
+            fs.copyFileSync(
+                path.join(this._dir, file),
+                path.join(dest, file)
+            );
+        }
+    }
+}
+
+module.exports = JsonAdapter;

package/lib/orm/adapters/memory.js

@@ -0,0 +1,383 @@
+/**
+ * @module orm/adapters/memory
+ * @description In-memory database adapter.
+ *              Zero-dependency, perfect for testing, prototyping, and
+ *              applications that don't need persistence beyond the process lifecycle.
+ *
+ *              All data is stored in plain JavaScript Maps and arrays.
+ *              Supports full CRUD, filtering, ordering, pagination, and counting.
+ */
+
+class MemoryAdapter
+{
+    constructor()
+    {
+        /** @private */ this._tables = new Map();
+        /** @private */ this._autoIncrements = new Map();
+    }
+
+    /**
+     * Create a table (register schema).
+     * @param {string} table   - Table name.
+     * @param {object} schema  - Column definitions.
+     */
+    async createTable(table, schema)
+    {
+        if (!this._tables.has(table))
+        {
+            this._tables.set(table, []);
+            this._autoIncrements.set(table, 1);
+        }
+    }
+
+    /**
+     * Drop a table.
+     * @param {string} table
+     */
+    async dropTable(table)
+    {
+        this._tables.delete(table);
+        this._autoIncrements.delete(table);
+    }
+
+    /**
+     * Insert a row.
+     * @param {string} table - Table name.
+     * @param {object} data  - Row data.
+     * @returns {Promise<object>} Inserted row (with auto-increment ID if applicable).
+     */
+    async insert(table, data)
+    {
+        const rows = this._getTable(table);
+        const row = { ...data };
+
+        // Auto-increment: find any key not provided
+        if (row.id === undefined || row.id === null)
+        {
+            row.id = this._autoIncrements.get(table) || 1;
+            this._autoIncrements.set(table, row.id + 1);
+        }
+
+        // Serialize Date objects
+        for (const [k, v] of Object.entries(row))
+        {
+            if (v instanceof Date) row[k] = v.toISOString();
+        }
+
+        rows.push(row);
+        return row;
+    }
+
+    /**
+     * Update a row by primary key.
+     * @param {string} table  - Table name.
+     * @param {string} pk     - Primary key column name.
+     * @param {*}      pkVal  - Primary key value.
+     * @param {object} data   - Fields to update.
+     */
+    async update(table, pk, pkVal, data)
+    {
+        const rows = this._getTable(table);
+        const row = rows.find(r => r[pk] === pkVal);
+        if (row)
+        {
+            for (const [k, v] of Object.entries(data))
+            {
+                row[k] = v instanceof Date ? v.toISOString() : v;
+            }
+        }
+    }
+
+    /**
+     * Update all rows matching conditions.
+     * @param {string} table      - Table name.
+     * @param {object} conditions - WHERE conditions.
+     * @param {object} data       - Fields to update.
+     * @returns {Promise<number>} Number of updated rows.
+     */
+    async updateWhere(table, conditions, data)
+    {
+        const rows = this._getTable(table);
+        let count = 0;
+        for (const row of rows)
+        {
+            if (this._matchConditions(row, conditions))
+            {
+                for (const [k, v] of Object.entries(data))
+                {
+                    row[k] = v instanceof Date ? v.toISOString() : v;
+                }
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Remove a row by primary key.
+     * @param {string} table
+     * @param {string} pk
+     * @param {*}      pkVal
+     */
+    async remove(table, pk, pkVal)
+    {
+        const rows = this._getTable(table);
+        const idx = rows.findIndex(r => r[pk] === pkVal);
+        if (idx !== -1) rows.splice(idx, 1);
+    }
+
+    /**
+     * Delete all rows matching conditions.
+     * @param {string} table
+     * @param {object} conditions
+     * @returns {Promise<number>}
+     */
+    async deleteWhere(table, conditions)
+    {
+        const rows = this._getTable(table);
+        let count = 0;
+        for (let i = rows.length - 1; i >= 0; i--)
+        {
+            if (this._matchConditions(rows[i], conditions))
+            {
+                rows.splice(i, 1);
+                count++;
+            }
+        }
+        return count;
+    }
+
+    /**
+     * Execute a query descriptor (from the Query builder).
+     * @param {object} descriptor - Abstract query descriptor.
+     * @returns {Promise<Array|number>}
+     */
+    async execute(descriptor)
+    {
+        const { action, table, fields, where, orderBy, limit, offset, distinct, includeDeleted } = descriptor;
+        let rows = [...this._getTable(table)];
+
+        // Apply WHERE filters
+        if (where && where.length > 0)
+        {
+            rows = rows.filter(row => this._applyWhereChain(row, where));
+        }
+
+        // Count action
+        if (action === 'count') return rows.length;
+
+        // ORDER BY
+        if (orderBy && orderBy.length > 0)
+        {
+            rows.sort((a, b) =>
+            {
+                for (const { field, dir } of orderBy)
+                {
+                    const av = a[field], bv = b[field];
+                    if (av < bv) return dir === 'ASC' ? -1 : 1;
+                    if (av > bv) return dir === 'ASC' ? 1 : -1;
+                }
+                return 0;
+            });
+        }
+
+        // OFFSET
+        if (offset) rows = rows.slice(offset);
+
+        // LIMIT
+        if (limit) rows = rows.slice(0, limit);
+
+        // SELECT specific fields
+        if (fields && fields.length > 0)
+        {
+            rows = rows.map(row =>
+            {
+                const filtered = {};
+                for (const f of fields) filtered[f] = row[f];
+                return filtered;
+            });
+        }
+
+        // DISTINCT
+        if (distinct)
+        {
+            const seen = new Set();
+            rows = rows.filter(row =>
+            {
+                const key = JSON.stringify(row);
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            });
+        }
+
+        return rows;
+    }
+
+    /**
+     * Clear all data (for testing).
+     */
+    async clear()
+    {
+        for (const key of this._tables.keys())
+        {
+            this._tables.set(key, []);
+            this._autoIncrements.set(key, 1);
+        }
+    }
+
+    // -- Internal Helpers -------------------------------
+
+    /** @private Get or create table array. */
+    _getTable(table)
+    {
+        if (!this._tables.has(table)) this._tables.set(table, []);
+        return this._tables.get(table);
+    }
+
+    /** @private Match simple object conditions { key: value }. */
+    _matchConditions(row, conditions)
+    {
+        if (!conditions || typeof conditions !== 'object') return true;
+        for (const [k, v] of Object.entries(conditions))
+        {
+            if (row[k] !== v) return false;
+        }
+        return true;
+    }
+
+    /** @private Apply the where chain from query builder. */
+    _applyWhereChain(row, where)
+    {
+        let result = true;
+        for (let i = 0; i < where.length; i++)
+        {
+            const clause = where[i];
+            // Skip raw SQL clauses — not supported in memory adapter
+            if (clause.raw) continue;
+            const matches = this._matchClause(row, clause);
+
+            if (i === 0 || clause.logic === 'AND')
+            {
+                result = i === 0 ? matches : (result && matches);
+            }
+            else if (clause.logic === 'OR')
+            {
+                result = result || matches;
+            }
+        }
+        return result;
+    }
+
+    /** @private Match a single WHERE clause. */
+    _matchClause(row, clause)
+    {
+        const val = row[clause.field];
+        const { op, value } = clause;
+
+        switch (op)
+        {
+            case '=':         return val === value;
+            case '!=':
+            case '<>':        return val !== value;
+            case '>':         return val > value;
+            case '<':         return val < value;
+            case '>=':        return val >= value;
+            case '<=':        return val <= value;
+            case 'LIKE':
+            {
+                // Simple LIKE: % = any, _ = single char
+                const pattern = String(value).replace(/%/g, '.*').replace(/_/g, '.');
+                return new RegExp('^' + pattern + '$', 'i').test(String(val));
+            }
+            case 'IN':        return Array.isArray(value) && value.includes(val);
+            case 'NOT IN':    return Array.isArray(value) && !value.includes(val);
+            case 'BETWEEN':       return Array.isArray(value) && val >= value[0] && val <= value[1];
+            case 'NOT BETWEEN':   return Array.isArray(value) && (val < value[0] || val > value[1]);
+            case 'IS NULL':   return val === null || val === undefined;
+            case 'IS NOT NULL': return val !== null && val !== undefined;
+            default:          return val === value;
+        }
+    }
+
+    // -- Memory Adapter Utilities ------------------------
+
+    /**
+     * List all registered table names.
+     * @returns {string[]}
+     */
+    tables()
+    {
+        return [...this._tables.keys()];
+    }
+
+    /**
+     * Get the total number of rows across all tables.
+     * @returns {number}
+     */
+    totalRows()
+    {
+        let total = 0;
+        for (const rows of this._tables.values()) total += rows.length;
+        return total;
+    }
+
+    /**
+     * Get memory usage stats.
+     * @returns {{ tables: number, totalRows: number, estimatedBytes: number }}
+     */
+    stats()
+    {
+        const tables = this._tables.size;
+        let totalRows = 0;
+        let estimatedBytes = 0;
+        for (const rows of this._tables.values())
+        {
+            totalRows += rows.length;
+            estimatedBytes += JSON.stringify(rows).length * 2; // rough UTF-16 estimate
+        }
+        return { tables, totalRows, estimatedBytes };
+    }
+
+    /**
+     * Export all data as a plain object.
+     * @returns {object} { tableName: rows[], ... }
+     */
+    toJSON()
+    {
+        const out = {};
+        for (const [table, rows] of this._tables) out[table] = [...rows];
+        return out;
+    }
+
+    /**
+     * Import data from a plain object, merging with existing data.
+     * @param {object} data - { tableName: rows[], ... }
+     */
+    fromJSON(data)
+    {
+        for (const [table, rows] of Object.entries(data))
+        {
+            if (!this._tables.has(table)) this._tables.set(table, []);
+            const existing = this._tables.get(table);
+            for (const row of rows) existing.push({ ...row });
+            // Update auto-increment
+            const maxId = rows.reduce((max, r) => Math.max(max, r.id || 0), 0);
+            const currentAi = this._autoIncrements.get(table) || 1;
+            if (maxId >= currentAi) this._autoIncrements.set(table, maxId + 1);
+        }
+    }
+
+    /**
+     * Clone the entire database state (deep copy).
+     * @returns {MemoryAdapter}
+     */
+    clone()
+    {
+        const copy = new MemoryAdapter();
+        copy.fromJSON(this.toJSON());
+        return copy;
+    }
+}
+
+module.exports = MemoryAdapter;