outlet-orm 5.5.3 → 6.5.0

package/src/Backup/BackupSocketServer.js

@@ -0,0 +1,347 @@
+/**
+ * BackupSocketServer
+ *
+ * A long-running TCP daemon that manages backup jobs for outlet-orm.
+ * Clients connect, send JSON commands, and receive JSON responses.
+ *
+ * Protocol: newline-delimited JSON (NDJSON) over TCP.
+ *
+ * ─── Client → Server commands ─────────────────────────────────────────
+ *  { "action": "schedule", "type": "full|partial|journal",
+ *    "config": { "intervalMs": 3600000, "tables": [...], "name": "...",
+ *                "format": "sql|json", "flush": false,
+ *                "encrypt": true, "encryptionPassword": "...", "saltLength": 6 } }
+ *
+ *  { "action": "stop",    "name": "job_name" }
+ *  { "action": "stopAll" }
+ *  { "action": "jobs" }
+ *  { "action": "run",    "type": "full|partial|journal",
+ *    "tables": [...], "options": { "format": "sql", "filename": "..." } }
+ *  { "action": "restore", "filePath": "/abs/path/to/backup.sql",
+ *    "options": { "encryptionPassword": "..." } }
+ *  { "action": "status" }
+ *  { "action": "ping" }
+ *
+ * ─── Server → Client responses ────────────────────────────────────────
+ *  { "ok": true,  "result": <any> }
+ *  { "ok": false, "error":  "message" }
+ *
+ * ─── Server → All clients (push events) ──────────────────────────────
+ *  { "event": "jobStart", "name": "...", "type": "..." }
+ *  { "event": "jobDone",  "name": "...", "type": "...", "filePath": "..." }
+ *  { "event": "jobError", "name": "...", "type": "...", "error": "..." }
+ *
+ * Usage:
+ *   const server = new BackupSocketServer(db, { port: 9119, backupPath: './database/backups' });
+ *   await server.listen();   // starts the daemon
+ *   // ...
+ *   await server.close();    // graceful shutdown
+ */
+
+'use strict';
+
+const net    = require('net');
+const events = require('events');
+const BackupManager   = require('./BackupManager');
+const BackupScheduler = require('./BackupScheduler');
+
+const DEFAULT_PORT = 9119;
+const DEFAULT_HOST = '127.0.0.1';
+
+class BackupSocketServer extends events.EventEmitter {
+  /**
+   * @param {import('../DatabaseConnection')} connection
+   * @param {object}  [options]
+   * @param {number}  [options.port=9119]
+   * @param {string}  [options.host='127.0.0.1']
+   * @param {string}  [options.backupPath]         Forwarded to BackupManager
+   * @param {boolean} [options.encrypt]            Default encryption for all jobs
+   * @param {string}  [options.encryptionPassword] Default encryption password
+   * @param {number}  [options.saltLength]         Default grain de sable length
+   */
+  constructor(connection, options = {}) {
+    super();
+    this.connection = connection;
+    this.port    = options.port || DEFAULT_PORT;
+    this.host    = options.host || DEFAULT_HOST;
+
+    this._managerOptions = {
+      backupPath         : options.backupPath,
+      encrypt            : options.encrypt,
+      encryptionPassword : options.encryptionPassword,
+      saltLength         : options.saltLength,
+    };
+
+    this.manager   = new BackupManager(connection, this._managerOptions);
+    this.scheduler = new BackupScheduler(connection, this._managerOptions);
+
+    /** @type {Set<net.Socket>} */
+    this._clients = new Set();
+    this._server  = null;
+    this._startTime = null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Lifecycle
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Start the TCP server and begin accepting connections.
+   * @returns {Promise<void>}
+   */
+  listen() {
+    return new Promise((resolve, reject) => {
+      this._server = net.createServer((socket) => this._handleClient(socket));
+
+      this._server.on('error', (err) => {
+        this.emit('error', err);
+        reject(err);
+      });
+
+      this._server.listen(this.port, this.host, () => {
+        this._startTime = Date.now();
+        const addr = `${this.host}:${this.port}`;
+        console.log(`✓ BackupSocketServer listening on ${addr}`);
+        this.emit('listening', { host: this.host, port: this.port });
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Gracefully stop the server and all scheduled jobs.
+   * @returns {Promise<void>}
+   */
+  close() {
+    return new Promise((resolve) => {
+      this.scheduler.stopAll();
+
+      // Close all client connections
+      for (const sock of this._clients) {
+        try { sock.destroy(); } catch (_) { /* ignore */ }
+      }
+      this._clients.clear();
+
+      if (this._server) {
+        this._server.close(() => {
+          console.log('✓ BackupSocketServer closed');
+          this.emit('close');
+          resolve();
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  /**
+   * Return server address info.
+   * @returns {{ host: string, port: number } | null}
+   */
+  address() {
+    if (!this._server) return null;
+    const addr = this._server.address();
+    return addr ? { host: addr.address, port: addr.port } : null;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Client handling
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** @private */
+  _handleClient(socket) {
+    this._clients.add(socket);
+    let buffer = '';
+
+    socket.setEncoding('utf8');
+
+    socket.on('data', (chunk) => {
+      buffer += chunk;
+      // Messages are newline-delimited
+      const lines = buffer.split('\n');
+      buffer = lines.pop(); // keep incomplete last line
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        this._processMessage(socket, trimmed);
+      }
+    });
+
+    socket.on('close', () => {
+      this._clients.delete(socket);
+    });
+
+    socket.on('error', (err) => {
+      this._clients.delete(socket);
+      this.emit('clientError', err);
+    });
+  }
+
+  /** @private */
+  async _processMessage(socket, raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch (_) {
+      this._send(socket, { ok: false, error: 'Invalid JSON' });
+      return;
+    }
+
+    try {
+      const result = await this._dispatch(msg);
+      this._send(socket, { ok: true, result });
+    } catch (err) {
+      this._send(socket, { ok: false, error: err.message || String(err) });
+    }
+  }
+
+  /** @private */
+  async _dispatch(msg) {
+    switch (msg.action) {
+
+    case 'ping':
+      return 'pong';
+
+    case 'status':
+      return {
+        uptime : this._startTime ? Date.now() - this._startTime : 0,
+        jobs   : this.scheduler.activeJobs(),
+        clients: this._clients.size,
+      };
+
+    case 'jobs':
+      return this.scheduler.activeJobs();
+
+    case 'schedule': {
+      const type   = msg.type;
+      const config = Object.assign({}, msg.config || {});
+
+      // Merge per-job encryption options with server defaults
+      const jobManagerOpts = this._buildManagerOptions(config);
+
+      // Use a mutable ref so callbacks always carry the final job name
+      // (which may be auto-generated if config.name was not provided)
+      const nameRef = { value: config.name || type };
+
+      // Wrap success/error to emit events to all connected clients
+      const originalOnSuccess = config.onSuccess;
+      const originalOnError   = config.onError;
+
+      config.onSuccess = (filePath) => {
+        this._broadcast({ event: 'jobDone', name: nameRef.value, type, filePath });
+        if (typeof originalOnSuccess === 'function') originalOnSuccess(filePath);
+      };
+      config.onError = (err) => {
+        this._broadcast({ event: 'jobError', name: nameRef.value, type, error: err.message });
+        if (typeof originalOnError === 'function') originalOnError(err);
+      };
+
+      // Create a dedicated scheduler with the right per-job manager options
+      const jobScheduler = this._buildScheduler(jobManagerOpts);
+      const name = jobScheduler.schedule(type, config);
+
+      // Update ref with actual name (covers auto-generated names)
+      nameRef.value = name;
+
+      // Persist the interval handle in the main scheduler so status/stop work
+      this.scheduler._jobs.set(name, jobScheduler._jobs.get(name));
+
+      this._broadcast({ event: 'jobStart', name, type });
+      return name;
+    }
+
+    case 'stop':
+      this.scheduler.stop(msg.name);
+      return true;
+
+    case 'stopAll':
+      this.scheduler.stopAll();
+      return true;
+
+    case 'run': {
+      const type    = msg.type;
+      const options = msg.options || {};
+      const tables  = msg.tables;
+      const runManagerOpts = this._buildManagerOptions(options);
+      const runManager = new BackupManager(this.connection, runManagerOpts);
+
+      let filePath;
+      if (type === 'full') {
+        filePath = await runManager.full(options);
+      } else if (type === 'partial') {
+        if (!Array.isArray(tables) || tables.length === 0) {
+          throw new Error("'tables' array is required for partial backup");
+        }
+        filePath = await runManager.partial(tables, options);
+      } else if (type === 'journal') {
+        filePath = await runManager.journal(options);
+      } else {
+        throw new Error(`Unknown backup type "${type}"`);
+      }
+      return filePath;
+    }
+
+    case 'restore': {
+      if (!msg.filePath) {
+        throw new Error("'filePath' is required for restore");
+      }
+      // Build a restore-capable manager (needs encryptionPassword if file is encrypted)
+      const restoreOpts = Object.assign({}, this._managerOptions, {
+        encrypt           : false,   // manager doesn't need to encrypt on restore
+        encryptionPassword: (msg.options && msg.options.encryptionPassword)
+          || this._managerOptions.encryptionPassword,
+      });
+      const restoreManager = new BackupManager(this.connection, restoreOpts);
+      return restoreManager.restore(msg.filePath, msg.options || {});
+    }
+
+    default:
+      throw new Error(`Unknown action "${msg.action}"`);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Helpers
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  /** @private */
+  _send(socket, payload) {
+    if (socket.writable) {
+      socket.write(JSON.stringify(payload) + '\n');
+    }
+  }
+
+  /** @private */
+  _broadcast(payload) {
+    const line = JSON.stringify(payload) + '\n';
+    for (const sock of this._clients) {
+      if (sock.writable) sock.write(line);
+    }
+    this.emit('event', payload);
+  }
+
+  /**
+   * Build BackupManager options, merging server defaults with per-call overrides.
+   * @private
+   */
+  _buildManagerOptions(overrides = {}) {
+    return {
+      backupPath        : overrides.backupPath         || this._managerOptions.backupPath,
+      encrypt           : overrides.encrypt            != null ? overrides.encrypt            : this._managerOptions.encrypt,
+      encryptionPassword: overrides.encryptionPassword || this._managerOptions.encryptionPassword,
+      saltLength        : overrides.saltLength         != null ? overrides.saltLength         : this._managerOptions.saltLength,
+    };
+  }
+
+  /**
+   * Build a throw-away BackupScheduler with a given manager.
+   * @private
+   */
+  _buildScheduler(managerOptions) {
+    const s = new BackupScheduler(this.connection, managerOptions);
+    return s;
+  }
+}
+
+module.exports = BackupSocketServer;

package/src/Model.js

@@ -665,6 +665,147 @@ class Model {
     return this.query().with(...relations);
   }
 
+  // ==================== Convenience Query Methods ====================
+
+  /**
+   * Find the first record matching conditions or create a new one
+   * @param {Object} conditions - Where conditions to search
+   * @param {Object} [values={}] - Additional attributes for creation
+   * @returns {Promise<Model>}
+   */
+  static async firstOrCreate(conditions, values = {}) {
+    const query = this.query();
+    for (const [key, val] of Object.entries(conditions)) {
+      query.where(key, val);
+    }
+    const existing = await query.first();
+    if (existing) return existing;
+    return this.create({ ...conditions, ...values });
+  }
+
+  /**
+   * Find the first record matching conditions or return a new (unsaved) instance
+   * @param {Object} conditions - Where conditions to search
+   * @param {Object} [values={}] - Additional attributes for the new instance
+   * @returns {Promise<Model>}
+   */
+  static async firstOrNew(conditions, values = {}) {
+    const query = this.query();
+    for (const [key, val] of Object.entries(conditions)) {
+      query.where(key, val);
+    }
+    const existing = await query.first();
+    if (existing) return existing;
+    const instance = new this({ ...conditions, ...values });
+    return instance;
+  }
+
+  /**
+   * Find a record matching conditions and update it, or create a new one
+   * @param {Object} conditions - Where conditions to search
+   * @param {Object} values - Attributes to update or set on creation
+   * @returns {Promise<Model>}
+   */
+  static async updateOrCreate(conditions, values = {}) {
+    const query = this.query();
+    for (const [key, val] of Object.entries(conditions)) {
+      query.where(key, val);
+    }
+    const existing = await query.first();
+    if (existing) {
+      for (const [key, val] of Object.entries(values)) {
+        existing.setAttribute(key, val);
+      }
+      await existing.save();
+      return existing;
+    }
+    return this.create({ ...conditions, ...values });
+  }
+
+  /**
+   * Insert or update multiple records in bulk.
+   * @param {Array<Object>} rows - Array of records to upsert
+   * @param {string|string[]} uniqueBy - Column(s) that determine uniqueness
+   * @param {string[]} [update] - Columns to update on conflict (default: all non-unique columns)
+   * @returns {Promise<any>}
+   */
+  static async upsert(rows, uniqueBy, update) {
+    if (!rows || rows.length === 0) return;
+    this.ensureConnection();
+    const uniqueCols = Array.isArray(uniqueBy) ? uniqueBy : [uniqueBy];
+
+    // Determine columns to update on conflict
+    const allCols = Object.keys(rows[0]);
+    const updateCols = update || allCols.filter(c => !uniqueCols.includes(c));
+
+    // Build driver-specific upsert SQL
+    const table = this.table;
+    const columns = allCols;
+    const placeholders = rows.map(() => `(${columns.map(() => '?').join(', ')})`).join(', ');
+    const values = rows.flatMap(r => columns.map(c => r[c] !== undefined ? r[c] : null));
+
+    const conn = this.connection;
+    const driver = conn.config ? conn.config.driver : 'mysql';
+
+    let sql;
+    if (driver === 'sqlite') {
+      const updateSet = updateCols.map(c => `\`${c}\` = excluded.\`${c}\``).join(', ');
+      sql = `INSERT INTO \`${table}\` (${columns.map(c => `\`${c}\``).join(', ')}) VALUES ${placeholders} ON CONFLICT (${uniqueCols.map(c => `\`${c}\``).join(', ')}) DO UPDATE SET ${updateSet}`;
+    } else if (driver === 'postgres' || driver === 'postgresql') {
+      const updateSet = updateCols.map(c => `"${c}" = EXCLUDED."${c}"`).join(', ');
+      sql = `INSERT INTO "${table}" (${columns.map(c => `"${c}"`).join(', ')}) VALUES ${placeholders} ON CONFLICT (${uniqueCols.map(c => `"${c}"`).join(', ')}) DO UPDATE SET ${updateSet}`;
+    } else {
+      // MySQL: INSERT ... ON DUPLICATE KEY UPDATE
+      const updateSet = updateCols.map(c => `\`${c}\` = VALUES(\`${c}\`)`).join(', ');
+      sql = `INSERT INTO \`${table}\` (${columns.map(c => `\`${c}\``).join(', ')}) VALUES ${placeholders} ON DUPLICATE KEY UPDATE ${updateSet}`;
+    }
+
+    return conn.execute(sql, values);
+  }
+
+  // ==================== Observer ====================
+
+  /**
+   * Register an observer class that listens to model events.
+   * The observer may define methods: creating, created, updating, updated,
+   * saving, saved, deleting, deleted, restoring, restored.
+   * @param {Object|Function} observer - Observer instance or class
+   */
+  static observe(observer) {
+    const instance = typeof observer === 'function' ? new observer() : observer;
+    const events = [
+      'creating', 'created', 'updating', 'updated',
+      'saving', 'saved', 'deleting', 'deleted',
+      'restoring', 'restored'
+    ];
+    for (const event of events) {
+      if (typeof instance[event] === 'function') {
+        this.on(event, (model) => instance[event](model));
+      }
+    }
+  }
+
+  // ==================== Cursor / Stream ====================
+
+  /**
+   * Lazily iterate over all matching records using an async generator.
+   * Yields one model instance at a time, consuming minimal memory.
+   * @param {number} [chunkSize=100] - Number of records per internal query
+   * @returns {AsyncGenerator<Model>}
+   */
+  static async *cursor(chunkSize = 100) {
+    let offset = 0;
+    while (true) {
+      const results = await this.query().limit(chunkSize).offset(offset).get();
+      if (results.length === 0) break;
+      for (const model of results) {
+        yield model;
+      }
+      if (results.length < chunkSize) break;
+      offset += chunkSize;
+    }
+  }
+
   /**
    * Include hidden attributes in query results
    * @returns {QueryBuilder}
@@ -704,18 +845,24 @@ class Model {
   }
 
   /**
-   * Set an attribute
+   * Set an attribute (runs mutator if defined)
    * @param {string} key
    * @param {any} value
    * @returns {this}
    */
   setAttribute(key, value) {
+    // Check for mutator: set{Key}Attribute
+    const mutator = `set${key.charAt(0).toUpperCase()}${key.slice(1).replace(/_([a-z])/g, (_, c) => c.toUpperCase())}Attribute`;
+    if (typeof this[mutator] === 'function') {
+      this[mutator](value);
+      return this;
+    }
     this.attributes[key] = this.castAttribute(key, value);
     return this;
   }
 
   /**
-   * Get an attribute
+   * Get an attribute (runs accessor if defined)
    * @param {string} key
    * @returns {any}
    */
@@ -723,6 +870,11 @@ class Model {
     if (this.relations[key]) {
       return this.relations[key];
     }
+    // Check for accessor: get{Key}Attribute
+    const accessor = `get${key.charAt(0).toUpperCase()}${key.slice(1).replace(/_([a-z])/g, (_, c) => c.toUpperCase())}Attribute`;
+    if (typeof this[accessor] === 'function') {
+      return this[accessor](this.attributes[key]);
+    }
     return this.castAttribute(key, this.attributes[key]);
   }
 

package/src/QueryBuilder.js

@@ -623,6 +623,88 @@ class QueryBuilder {
     return result;
   }
 
+  /**
+   * Get the first record matching current wheres or create a new one
+   * @param {Object} [values={}] - Additional attributes to merge on creation
+   * @returns {Promise<Model>}
+   */
+  async firstOrCreate(values = {}) {
+    const existing = await this.first();
+    if (existing) return existing;
+    // Build conditions from current wheres
+    const conditions = {};
+    for (const w of this.wheres) {
+      if (w.type === 'basic' && w.operator === '=') {
+        conditions[w.column] = w.value;
+      }
+    }
+    const instance = new this.model({ ...conditions, ...values });
+    return instance.save();
+  }
+
+  /**
+   * Get the first record matching current wheres or return a new (unsaved) instance
+   * @param {Object} [values={}] - Additional attributes for the instance
+   * @returns {Promise<Model>}
+   */
+  async firstOrNew(values = {}) {
+    const existing = await this.first();
+    if (existing) return existing;
+    const conditions = {};
+    for (const w of this.wheres) {
+      if (w.type === 'basic' && w.operator === '=') {
+        conditions[w.column] = w.value;
+      }
+    }
+    return new this.model({ ...conditions, ...values });
+  }
+
+  /**
+   * Find a record matching current wheres and update it, or create a new one
+   * @param {Object} values - Attributes to update or set on creation
+   * @returns {Promise<Model>}
+   */
+  async updateOrCreate(values = {}) {
+    const existing = await this.first();
+    if (existing) {
+      for (const [key, val] of Object.entries(values)) {
+        existing.setAttribute(key, val);
+      }
+      await existing.save();
+      return existing;
+    }
+    const conditions = {};
+    for (const w of this.wheres) {
+      if (w.type === 'basic' && w.operator === '=') {
+        conditions[w.column] = w.value;
+      }
+    }
+    const instance = new this.model({ ...conditions, ...values });
+    return instance.save();
+  }
+
+  /**
+   * Lazily iterate over matching records using an async generator.
+   * Yields one model instance at a time, consuming minimal memory.
+   * @param {number} [chunkSize=100] - Number of records per internal query
+   * @returns {AsyncGenerator<Model>}
+   */
+  async *cursor(chunkSize = 100) {
+    let offset = 0;
+    while (true) {
+      const cloned = this.clone();
+      cloned.limitValue = chunkSize;
+      cloned.offsetValue = offset;
+      const results = await cloned.get();
+      if (results.length === 0) break;
+      for (const model of results) {
+        yield model;
+      }
+      if (results.length < chunkSize) break;
+      offset += chunkSize;
+    }
+  }
+
   /**
    * Paginate the results
    * @param {number} page

package/src/index.js

@@ -21,6 +21,13 @@ const MigrationManager = require('./Migrations/MigrationManager');
 const Seeder = require('./Seeders/Seeder');
 const SeederManager = require('./Seeders/SeederManager');
 
+// Backup
+const BackupManager      = require('./Backup/BackupManager');
+const BackupScheduler    = require('./Backup/BackupScheduler');
+const BackupEncryption   = require('./Backup/BackupEncryption');
+const BackupSocketServer = require('./Backup/BackupSocketServer');
+const BackupSocketClient = require('./Backup/BackupSocketClient');
+
 module.exports = {
   // Core
   Model,
@@ -51,5 +58,12 @@ module.exports = {
 
   // Seeders
   Seeder,
-  SeederManager
+  SeederManager,
+
+  // Backup
+  BackupManager,
+  BackupScheduler,
+  BackupEncryption,
+  BackupSocketServer,
+  BackupSocketClient
 };