outlet-orm 6.0.0 → 6.5.0

package/README.md

@@ -86,8 +86,9 @@ my-project/
 ├── database/
 │   ├── config.js                 # Config migrations (outlet-init)
 │   ├── migrations/               # Migration files
-│   └── seeds/                    # Test/demo data
-│       └── UserSeeder.js
+│   ├── seeds/                    # Test/demo data
+│   │   └── UserSeeder.js
+│   └── backups/                  # 🗄️ Backup files (full / partial / journal)
 │
 ├── public/                       # ✅ Public static files
 │   ├── images/
@@ -195,6 +196,7 @@ async store(req, res) {
 - **Ergonomic aliases**: `columns([...])`, `ordrer()` (typo alias for `orderBy`)
 - **Raw queries**: `executeRawQuery()` and `execute()` (native driver results)
 - **Complete Migrations** (create/alter/drop, index, foreign keys, batch tracking)
+- **Database Backup** (v6.0.0): full/partial/journal backups, recurring scheduler, AES-256-GCM encryption, TCP daemon + remote client, automatic restore
 - **Handy CLI tools**: `outlet-init`, `outlet-migrate`, `outlet-convert`
 - **`.env` configuration** (loaded automatically)
 - **Multi-database**: MySQL, PostgreSQL, and SQLite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlet-orm",
-  "version": "6.0.0",
+  "version": "6.5.0",
   "description": "A Laravel Eloquent-inspired ORM for Node.js with support for MySQL, PostgreSQL, and SQLite",
   "main": "src/index.js",
   "types": "types/index.d.ts",

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/types/index.d.ts

@@ -153,6 +153,20 @@ declare module 'outlet-orm' {
     to: number;
   }
 
+  /** Observer interface for model lifecycle events */
+  export interface ModelObserver<T extends Model = Model> {
+    creating?(model: T): boolean | void | Promise<boolean | void>;
+    created?(model: T): void | Promise<void>;
+    updating?(model: T): boolean | void | Promise<boolean | void>;
+    updated?(model: T): void | Promise<void>;
+    saving?(model: T): boolean | void | Promise<boolean | void>;
+    saved?(model: T): void | Promise<void>;
+    deleting?(model: T): boolean | void | Promise<boolean | void>;
+    deleted?(model: T): void | Promise<void>;
+    restoring?(model: T): boolean | void | Promise<boolean | void>;
+    restored?(model: T): void | Promise<void>;
+  }
+
   export class QueryBuilder<T extends Model> {
     constructor(model: typeof Model);
 
@@ -204,6 +218,12 @@ declare module 'outlet-orm' {
     get(): Promise<T[]>;
     first(): Promise<T | null>;
     firstOrFail(): Promise<T>;
+    /** Get the first record matching current wheres or create a new one */
+    firstOrCreate(values?: Record<string, any>): Promise<T>;
+    /** Get the first record matching current wheres or return a new unsaved instance */
+    firstOrNew(values?: Record<string, any>): Promise<T>;
+    /** Find a record matching current wheres and update it, or create a new one */
+    updateOrCreate(values?: Record<string, any>): Promise<T>;
     paginate(page?: number, perPage?: number): Promise<PaginationResult<T>>;
     count(): Promise<number>;
     exists(): Promise<boolean>;
@@ -214,6 +234,8 @@ declare module 'outlet-orm' {
     delete(): Promise<any>;
     increment(column: string, amount?: number): Promise<any>;
     decrement(column: string, amount?: number): Promise<any>;
+    /** Lazily iterate over matching records using an async generator */
+    cursor(chunkSize?: number): AsyncGenerator<T, void, unknown>;
 
     clone(): QueryBuilder<T>;
   }
@@ -344,6 +366,25 @@ declare module 'outlet-orm' {
     static whereNull<T extends Model>(this: new () => T, column: string): QueryBuilder<T>;
     static whereNotNull<T extends Model>(this: new () => T, column: string): QueryBuilder<T>;
     static count(): Promise<number>;
+
+    // Convenience query methods
+    /** Find the first record matching conditions or create a new one */
+    static firstOrCreate<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Find the first record matching conditions or return a new unsaved instance */
+    static firstOrNew<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Find a record matching conditions and update it, or create a new one */
+    static updateOrCreate<T extends Model>(this: new () => T, conditions: Record<string, any>, values?: Record<string, any>): Promise<T>;
+    /** Insert or update multiple records in bulk (ON CONFLICT / ON DUPLICATE KEY) */
+    static upsert(rows: Record<string, any>[], uniqueBy: string | string[], update?: string[]): Promise<any>;
+
+    // Observer
+    /** Register an observer class that listens to model lifecycle events */
+    static observe(observer: ModelObserver | (new () => ModelObserver)): void;
+
+    // Cursor / Stream
+    /** Lazily iterate over all matching records using an async generator */
+    static cursor<T extends Model>(this: new () => T, chunkSize?: number): AsyncGenerator<T, void, unknown>;
+
     static with<T extends Model>(this: new () => T, ...relations: string[] | [Record<string, (qb: QueryBuilder<any>) => void> | string[]]): QueryBuilder<T>;
     /** Include hidden attributes in query results */
     static withHidden<T extends Model>(this: new () => T): QueryBuilder<T>;