zero-http 0.2.5 → 0.3.1

package/lib/orm/adapters/sqlite.js

@@ -0,0 +1,311 @@
+/**
+ * @module orm/adapters/sqlite
+ * @description SQLite adapter using the optional `better-sqlite3` driver.
+ *              Requires: `npm install better-sqlite3`
+ *
+ * @example
+ *   const db = Database.connect('sqlite', { filename: './data.db' });
+ *   // or ':memory:' for in-memory database
+ */
+const path = require('path');
+const fs   = require('fs');
+const BaseSqlAdapter = require('./sql-base');
+
+class SqliteAdapter extends BaseSqlAdapter
+{
+    /**
+     * @param {object}  options
+     * @param {string}  [options.filename=':memory:']  - Path to SQLite file, or ':memory:'.
+     * @param {boolean} [options.readonly=false]        - Open database in read-only mode.
+     * @param {boolean} [options.fileMustExist=false]   - Throw if the database file does not exist.
+     * @param {boolean} [options.verbose]               - Log every SQL statement (debug).
+     * @param {boolean} [options.createDir=true]         - Automatically create parent directories for the file.
+     * @param {object}  [options.pragmas]               - PRAGMA settings to apply on open.
+     * @param {string}  [options.pragmas.journal_mode='WAL']       - Journal mode (WAL, DELETE, TRUNCATE, MEMORY, OFF).
+     * @param {string}  [options.pragmas.foreign_keys='ON']        - Enforce foreign-key constraints.
+     * @param {string}  [options.pragmas.busy_timeout='5000']      - Milliseconds to wait on a locked database.
+     * @param {string}  [options.pragmas.synchronous='NORMAL']     - Sync mode (OFF, NORMAL, FULL, EXTRA).
+     * @param {string}  [options.pragmas.cache_size='-64000']      - Page cache size (negative = KiB, e.g. -64000 = 64 MB).
+     * @param {string}  [options.pragmas.temp_store='MEMORY']      - Temp tables in memory for speed.
+     * @param {string}  [options.pragmas.mmap_size='268435456']    - Memory-mapped I/O size (256 MB).
+     * @param {string}  [options.pragmas.page_size]                - Page size in bytes (must be set before WAL).
+     * @param {string}  [options.pragmas.auto_vacuum]              - Auto-vacuum mode (NONE, FULL, INCREMENTAL).
+     * @param {string}  [options.pragmas.secure_delete]            - Overwrite deleted content with zeros.
+     * @param {string}  [options.pragmas.wal_autocheckpoint]       - Pages before auto-checkpoint (default 1000).
+     * @param {string}  [options.pragmas.locking_mode]             - NORMAL or EXCLUSIVE.
+     */
+    constructor(options = {})
+    {
+        super();
+        let Database;
+        try { Database = require('better-sqlite3'); }
+        catch (e)
+        {
+            throw new Error(
+                'SQLite adapter requires "better-sqlite3" package.\n' +
+                'Install it with: npm install better-sqlite3'
+            );
+        }
+
+        const filename = options.filename || ':memory:';
+
+        // Auto-create parent directories for file-based databases
+        if (filename !== ':memory:' && options.createDir !== false)
+        {
+            const dir = path.dirname(path.resolve(filename));
+            if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        }
+
+        // Build better-sqlite3 constructor options
+        const dbOpts = {};
+        if (options.readonly)     dbOpts.readonly = true;
+        if (options.fileMustExist) dbOpts.fileMustExist = true;
+        if (options.verbose)      dbOpts.verbose = console.log;
+
+        this._db = new Database(filename, dbOpts);
+        this._filename = filename;
+
+        // Apply pragmas (with production-ready defaults)
+        const pragmas = {
+            journal_mode: 'WAL',
+            foreign_keys: 'ON',
+            busy_timeout: '5000',
+            synchronous:  'NORMAL',
+            cache_size:   '-64000',
+            temp_store:   'MEMORY',
+            mmap_size:    '268435456',
+            ...options.pragmas,
+        };
+        for (const [key, val] of Object.entries(pragmas))
+            this._db.pragma(`${key} = ${val}`);
+    }
+
+    /** @override */
+    _typeMap(colDef)
+    {
+        const map = {
+            string: 'TEXT', text: 'TEXT', integer: 'INTEGER', float: 'REAL',
+            boolean: 'INTEGER', date: 'TEXT', datetime: 'TEXT',
+            json: 'TEXT', blob: 'BLOB', uuid: 'TEXT',
+        };
+        return map[colDef.type] || 'TEXT';
+    }
+
+    /** @override */
+    async createTable(table, schema)
+    {
+        const cols = [];
+        for (const [name, def] of Object.entries(schema))
+        {
+            let line = `"${name}" ${this._typeMap(def)}`;
+            if (def.primaryKey) line += ' PRIMARY KEY';
+            if (def.autoIncrement) line += ' AUTOINCREMENT';
+            if (def.required && !def.primaryKey) line += ' NOT NULL';
+            if (def.unique) line += ' UNIQUE';
+            if (def.default !== undefined && typeof def.default !== 'function')
+            {
+                line += ` DEFAULT ${this._sqlDefault(def.default)}`;
+            }
+            cols.push(line);
+        }
+        this._db.exec(`CREATE TABLE IF NOT EXISTS "${table}" (${cols.join(', ')})`);
+    }
+
+    /** @override */
+    async dropTable(table)
+    {
+        this._db.exec(`DROP TABLE IF EXISTS "${table}"`);
+    }
+
+    /** @override */
+    async insert(table, data)
+    {
+        const keys = Object.keys(data);
+        const placeholders = keys.map(() => '?').join(', ');
+        const values = keys.map(k => this._toSqlValue(data[k]));
+        const stmt = this._db.prepare(`INSERT INTO "${table}" (${keys.map(k => `"${k}"`).join(', ')}) VALUES (${placeholders})`);
+        const result = stmt.run(...values);
+        return { ...data, id: result.lastInsertRowid };
+    }
+
+    /** @override */
+    async update(table, pk, pkVal, data)
+    {
+        const sets = Object.keys(data).map(k => `"${k}" = ?`).join(', ');
+        const values = [...Object.values(data).map(v => this._toSqlValue(v)), pkVal];
+        this._db.prepare(`UPDATE "${table}" SET ${sets} WHERE "${pk}" = ?`).run(...values);
+    }
+
+    /** @override */
+    async updateWhere(table, conditions, data)
+    {
+        const { clause, values: whereVals } = this._buildWhere(conditions);
+        const sets = Object.keys(data).map(k => `"${k}" = ?`).join(', ');
+        const values = [...Object.values(data).map(v => this._toSqlValue(v)), ...whereVals];
+        const result = this._db.prepare(`UPDATE "${table}" SET ${sets}${clause}`).run(...values);
+        return result.changes;
+    }
+
+    /** @override */
+    async remove(table, pk, pkVal)
+    {
+        this._db.prepare(`DELETE FROM "${table}" WHERE "${pk}" = ?`).run(pkVal);
+    }
+
+    /** @override */
+    async deleteWhere(table, conditions)
+    {
+        const { clause, values } = this._buildWhere(conditions);
+        const result = this._db.prepare(`DELETE FROM "${table}"${clause}`).run(...values);
+        return result.changes;
+    }
+
+    /** @override */
+    async execute(descriptor)
+    {
+        const { action, table, fields, where, orderBy, limit, offset, distinct } = descriptor;
+
+        if (action === 'count')
+        {
+            const { clause, values } = this._buildWhereFromChain(where);
+            const row = this._db.prepare(`SELECT COUNT(*) as count FROM "${table}"${clause}`).get(...values);
+            return row.count;
+        }
+
+        const selectFields = fields && fields.length
+            ? fields.map(f => `"${f}"`).join(', ')
+            : '*';
+        const distinctStr = distinct ? 'DISTINCT ' : '';
+        let sql = `SELECT ${distinctStr}${selectFields} FROM "${table}"`;
+
+        const values = [];
+        if (where && where.length > 0)
+        {
+            const { clause, values: wv } = this._buildWhereFromChain(where);
+            sql += clause;
+            values.push(...wv);
+        }
+
+        if (orderBy && orderBy.length > 0)
+        {
+            sql += ' ORDER BY ' + orderBy.map(o => `"${o.field}" ${o.dir}`).join(', ');
+        }
+
+        if (limit !== null && limit !== undefined)
+        {
+            sql += ' LIMIT ?';
+            values.push(limit);
+        }
+
+        if (offset !== null && offset !== undefined)
+        {
+            sql += ' OFFSET ?';
+            values.push(offset);
+        }
+
+        return this._db.prepare(sql).all(...values);
+    }
+
+    // -- SQLite Utilities -----------------------------------------------
+
+    /**
+     * Read a single PRAGMA value.
+     * @param {string} key - PRAGMA name (e.g. 'journal_mode').
+     * @returns {*} Current value.
+     */
+    pragma(key)
+    {
+        const rows = this._db.pragma(key);
+        if (Array.isArray(rows) && rows.length === 1) return Object.values(rows[0])[0];
+        return rows;
+    }
+
+    /**
+     * Force a WAL checkpoint (only useful in WAL mode).
+     * @param {'PASSIVE'|'FULL'|'RESTART'|'TRUNCATE'} [mode='PASSIVE']
+     * @returns {{ busy: number, log: number, checkpointed: number }}
+     */
+    checkpoint(mode = 'PASSIVE')
+    {
+        const allowed = ['PASSIVE', 'FULL', 'RESTART', 'TRUNCATE'];
+        const m = String(mode).toUpperCase();
+        if (!allowed.includes(m)) throw new Error(`Invalid checkpoint mode: ${mode}`);
+        const row = this._db.pragma(`wal_checkpoint(${m})`);
+        return Array.isArray(row) ? row[0] : row;
+    }
+
+    /**
+     * Run `PRAGMA integrity_check`.
+     * @returns {string} 'ok' if healthy, or a description of the problem.
+     */
+    integrity()
+    {
+        const rows = this._db.pragma('integrity_check');
+        const val = Array.isArray(rows) ? rows[0] : rows;
+        return (val && typeof val === 'object') ? Object.values(val)[0] : val;
+    }
+
+    /**
+     * Rebuild the database file, reclaiming free pages.
+     */
+    vacuum()
+    {
+        this._db.exec('VACUUM');
+    }
+
+    /**
+     * Get the size of the database file in bytes.
+     * Returns 0 for in-memory databases.
+     * @returns {number}
+     */
+    fileSize()
+    {
+        if (this._filename === ':memory:') return 0;
+        try { return fs.statSync(path.resolve(this._filename)).size; }
+        catch { return 0; }
+    }
+
+    /**
+     * List all user-created tables.
+     * @returns {string[]}
+     */
+    tables()
+    {
+        const rows = this._db.prepare(
+            "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'"
+        ).all();
+        return rows.map(r => r.name);
+    }
+
+    /**
+     * Close the database connection.
+     */
+    close()
+    {
+        this._db.close();
+    }
+
+    /**
+     * Run a raw SQL query.
+     * @param {string} sql
+     * @param {...*}   params
+     * @returns {*}
+     */
+    raw(sql, ...params)
+    {
+        const stmt = this._db.prepare(sql);
+        return stmt.all(...params);
+    }
+
+    /**
+     * Begin a transaction.
+     * @param {Function} fn - Function to run inside the transaction.
+     * @returns {*} Return value of fn.
+     */
+    transaction(fn)
+    {
+        return this._db.transaction(fn)();
+    }
+}
+
+module.exports = SqliteAdapter;

package/lib/orm/index.js

@@ -0,0 +1,276 @@
+/**
+ * @module orm
+ * @description ORM entry point.  Provides the `Database` factory that creates
+ *              a connection to a backing store, the base `Model` class, the
+ *              `TYPES` enum, and schema helpers.
+ *
+ * Supported adapters (all optional "bring your own driver"):
+ *   - `memory`  — in-process (no driver needed)
+ *   - `json`    — JSON file persistence (no driver needed)
+ *   - `sqlite`  — requires `better-sqlite3`
+ *   - `mysql`   — requires `mysql2`
+ *   - `postgres` — requires `pg`
+ *   - `mongo`   — requires `mongodb`
+ *
+ * @example
+ *   const { Database, Model, TYPES } = require('zero-http');
+ *
+ *   const db = Database.connect('memory');
+ *
+ *   class User extends Model {
+ *       static table = 'users';
+ *       static schema = {
+ *           id:    { type: TYPES.INTEGER, primaryKey: true, autoIncrement: true },
+ *           name:  { type: TYPES.STRING, required: true },
+ *           email: { type: TYPES.STRING, required: true, unique: true },
+ *       };
+ *       static timestamps = true;
+ *   }
+ *
+ *   db.register(User);
+ *   await db.sync();
+ *
+ *   const user = await User.create({ name: 'Alice', email: 'a@b.com' });
+ */
+const Model = require('./model');
+const { TYPES, validate, validateValue } = require('./schema');
+const Query = require('./query');
+
+// -- Adapter loaders (lazy) ------------------------------
+
+const ADAPTERS = {
+    memory:   () => require('./adapters/memory'),
+    json:     () => require('./adapters/json'),
+    sqlite:   () => require('./adapters/sqlite'),
+    mysql:    () => require('./adapters/mysql'),
+    postgres: () => require('./adapters/postgres'),
+    mongo:    () => require('./adapters/mongo'),
+};
+
+// -- Database class --------------------------------------
+
+/**
+ * Validate adapter connection options and sanitize credentials.
+ * @param {string} type
+ * @param {object} options
+ * @returns {object} sanitised options
+ */
+function _validateOptions(type, options)
+{
+    const opts = { ...options };
+
+    // Adapters that take network credentials
+    if (type === 'mysql' || type === 'postgres')
+    {
+        if (opts.host !== undefined)
+        {
+            if (typeof opts.host !== 'string' || !opts.host.trim())
+                throw new Error(`${type}: "host" must be a non-empty string`);
+            opts.host = opts.host.trim();
+        }
+        if (opts.port !== undefined)
+        {
+            opts.port = Number(opts.port);
+            if (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)
+                throw new Error(`${type}: "port" must be an integer 1-65535`);
+        }
+        if (opts.user !== undefined)
+        {
+            if (typeof opts.user !== 'string')
+                throw new Error(`${type}: "user" must be a string`);
+        }
+        if (opts.password !== undefined)
+        {
+            if (typeof opts.password !== 'string')
+                throw new Error(`${type}: "password" must be a string`);
+        }
+        if (opts.database !== undefined)
+        {
+            if (typeof opts.database !== 'string' || !opts.database.trim())
+                throw new Error(`${type}: "database" must be a non-empty string`);
+            opts.database = opts.database.trim();
+        }
+    }
+
+    // Mongo connection string
+    if (type === 'mongo')
+    {
+        if (opts.url !== undefined)
+        {
+            if (typeof opts.url !== 'string' || !opts.url.trim())
+                throw new Error('mongo: "url" must be a non-empty string');
+            opts.url = opts.url.trim();
+        }
+        if (opts.database !== undefined)
+        {
+            if (typeof opts.database !== 'string' || !opts.database.trim())
+                throw new Error('mongo: "database" must be a non-empty string');
+            opts.database = opts.database.trim();
+        }
+    }
+
+    // SQLite validation
+    if (type === 'sqlite')
+    {
+        if (opts.filename !== undefined && typeof opts.filename !== 'string')
+            throw new Error('sqlite: "filename" must be a string');
+    }
+
+    return opts;
+}
+
+class Database
+{
+    /**
+     * @param {object} adapter - Instantiated adapter.
+     */
+    constructor(adapter)
+    {
+        /** @type {object} The underlying adapter instance. */
+        this.adapter = adapter;
+
+        /** @type {Map<string, typeof Model>} Registered model classes. */
+        this._models = new Map();
+    }
+
+    /**
+     * Create a Database connection.
+     *
+     * @param {string} type    - Adapter type: memory, json, sqlite, mysql, postgres, mongo.
+     * @param {object} [options] - Adapter-specific options.
+     * @returns {Database}
+     *
+     * @example
+     *   const db = Database.connect('sqlite', { filename: './app.db' });
+     *   const db = Database.connect('mysql', { host: '127.0.0.1', user: 'root', database: 'app' });
+     *   const db = Database.connect('postgres', { host: '127.0.0.1', user: 'postgres', database: 'app' });
+     *   const db = Database.connect('mongo', { url: 'mongodb://localhost:27017', database: 'app' });
+     *   const db = Database.connect('json', { directory: './data' });
+     *   const db = Database.connect('memory');
+     */
+    static connect(type, options = {})
+    {
+        const loader = ADAPTERS[type];
+        if (!loader) throw new Error(`Unknown adapter "${type}". Supported: ${Object.keys(ADAPTERS).join(', ')}`);
+
+        const opts = _validateOptions(type, options);
+        const AdapterClass = loader();
+        const adapter = new AdapterClass(opts);
+        return new Database(adapter);
+    }
+
+    /**
+     * Register a Model class with this database.
+     * Binds the adapter to the model so all CRUD operations go through it.
+     *
+     * @param {typeof Model} ModelClass
+     * @returns {Database} this (for chaining)
+     */
+    register(ModelClass)
+    {
+        ModelClass._adapter = this.adapter;
+        this._models.set(ModelClass.table || ModelClass.name, ModelClass);
+        return this;
+    }
+
+    /**
+     * Register multiple Model classes at once.
+     *
+     * @param {...typeof Model} models
+     * @returns {Database}
+     */
+    registerAll(...models)
+    {
+        for (const m of models) this.register(m);
+        return this;
+    }
+
+    /**
+     * Synchronise all registered models — create tables if they don't exist.
+     * @returns {Promise<void>}
+     */
+    async sync()
+    {
+        for (const ModelClass of this._models.values())
+        {
+            await ModelClass.sync();
+        }
+    }
+
+    /**
+     * Drop all registered model tables (in reverse order to respect FK deps).
+     * @returns {Promise<void>}
+     */
+    async drop()
+    {
+        const models = [...this._models.values()].reverse();
+        for (const ModelClass of models)
+        {
+            await ModelClass.drop();
+        }
+    }
+
+    /**
+     * Close the underlying connection / pool.
+     * @returns {Promise<void>|void}
+     */
+    async close()
+    {
+        if (typeof this.adapter.close === 'function')
+        {
+            await this.adapter.close();
+        }
+    }
+
+    /**
+     * Get a registered model by table name.
+     * @param {string} name
+     * @returns {typeof Model|undefined}
+     */
+    model(name)
+    {
+        return this._models.get(name);
+    }
+
+    /**
+     * Execute a callback within a database transaction.
+     * If the callback throws, the transaction is rolled back.
+     * If the callback returns normally, the transaction is committed.
+     *
+     * Note: Transaction support depends on the adapter.
+     * Memory and JSON adapters run the callback directly (no real transaction).
+     *
+     * @param {Function} fn - Async callback to execute within the transaction.
+     * @returns {Promise<*>} The return value of the callback.
+     *
+     * @example
+     *   await db.transaction(async () => {
+     *       await User.create({ name: 'Alice', email: 'a@b.com' });
+     *       await Account.create({ userId: 1, balance: 100 });
+     *   });
+     */
+    async transaction(fn)
+    {
+        if (typeof this.adapter.beginTransaction === 'function')
+        {
+            await this.adapter.beginTransaction();
+            try
+            {
+                const result = await fn();
+                await this.adapter.commit();
+                return result;
+            }
+            catch (err)
+            {
+                await this.adapter.rollback();
+                throw err;
+            }
+        }
+        // Adapters without transaction support run directly
+        return fn();
+    }
+}
+
+// -- Exports ---------------------------------------------
+
+module.exports = { Database, Model, TYPES, Query, validate, validateValue };