outlet-orm 10.0.0 → 11.1.0

package/src/Relations/HasOneRelation.js

@@ -1,114 +1,114 @@
-const Relation = require('./Relation');
-
-/**
- * Has One Relation
- * Represents a one-to-one relationship
- */
-class HasOneRelation extends Relation {
-  /**
-   * Get the related model
-   * @returns {Promise<Model|null>}
-   */
-  async get() {
-    const result = await this.related
-      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
-      .first();
-
-    return result;
-  }
-
-  /**
-   * Eager load the relationship for a collection of parent models
-   * @param {Array<Model>} models
-   * @param {string} relationName
-   * @returns {Promise<void>}
-   */
-  async eagerLoad(models, relationName, constraint) {
-    const keys = models
-      .map(model => model.getAttribute(this.localKey))
-      .filter(key => key !== null && key !== undefined);
-
-    if (keys.length === 0) return;
-
-    const qb = this.related.whereIn(this.foreignKey, keys);
-    if (typeof constraint === 'function') constraint(qb);
-    const relatedModels = await qb.get();
-
-    const relatedMap = {};
-    relatedModels.forEach(model => {
-      const foreignKeyValue = model.getAttribute(this.foreignKey);
-      relatedMap[foreignKeyValue] = model;
-    });
-
-    models.forEach(model => {
-      const localKeyValue = model.getAttribute(this.localKey);
-      model.relations[relationName] = relatedMap[localKeyValue] || null;
-    });
-  }
-
-  /**
-   * Add a where clause to the relation query
-   * @param {string} column
-   * @param {string|any} operator
-   * @param {any} value
-   * @returns {QueryBuilder}
-   */
-  where(column, operator, value) {
-    return this.related
-      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
-      .where(column, operator, value);
-  }
-
-  /**
-   * Create a new related model and associate it
-   * @param {Object} attributes
-   * @returns {Promise<Model>}
-   */
-  async create(attributes = {}) {
-    const model = new this.related.model(attributes);
-    model.setAttribute(this.foreignKey, this.parent.getAttribute(this.localKey));
-    await model.save();
-    return model;
-  }
-
-  /**
-   * Save an existing model and associate it
-   * @param {Model} model
-   * @returns {Promise<Model>}
-   */
-  async save(model) {
-    model.setAttribute(this.foreignKey, this.parent.getAttribute(this.localKey));
-    await model.save();
-    return model;
-  }
-
-  /**
-   * Create multiple related models and associate them
-   * @param {Array<Object>} attributesArray
-   * @returns {Promise<Array<Model>>}
-   */
-  async createMany(attributesArray) {
-    const models = [];
-    for (const attributes of attributesArray) {
-      const model = await this.create(attributes);
-      models.push(model);
-    }
-    return models;
-  }
-
-  /**
-   * Save multiple existing models and associate them
-   * @param {Array<Model>} models
-   * @returns {Promise<Array<Model>>}
-   */
-  async saveMany(models) {
-    const savedModels = [];
-    for (const model of models) {
-      const saved = await this.save(model);
-      savedModels.push(saved);
-    }
-    return savedModels;
-  }
-}
-
-module.exports = HasOneRelation;
+const Relation = require('./Relation');
+
+/**
+ * Has One Relation
+ * Represents a one-to-one relationship
+ */
+class HasOneRelation extends Relation {
+  /**
+   * Get the related model
+   * @returns {Promise<Model|null>}
+   */
+  async get() {
+    const result = await this.related
+      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
+      .first();
+
+    return result || this._buildDefault();
+  }
+
+  /**
+   * Eager load the relationship for a collection of parent models
+   * @param {Array<Model>} models
+   * @param {string} relationName
+   * @returns {Promise<void>}
+   */
+  async eagerLoad(models, relationName, constraint) {
+    const keys = models
+      .map(model => model.getAttribute(this.localKey))
+      .filter(key => key !== null && key !== undefined);
+
+    if (keys.length === 0) return;
+
+    const qb = this.related.whereIn(this.foreignKey, keys);
+    if (typeof constraint === 'function') constraint(qb);
+    const relatedModels = await qb.get();
+
+    const relatedMap = {};
+    relatedModels.forEach(model => {
+      const foreignKeyValue = model.getAttribute(this.foreignKey);
+      relatedMap[foreignKeyValue] = model;
+    });
+
+    models.forEach(model => {
+      const localKeyValue = model.getAttribute(this.localKey);
+      model.relations[relationName] = relatedMap[localKeyValue] || this._buildDefault();
+    });
+  }
+
+  /**
+   * Add a where clause to the relation query
+   * @param {string} column
+   * @param {string|any} operator
+   * @param {any} value
+   * @returns {QueryBuilder}
+   */
+  where(column, operator, value) {
+    return this.related
+      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
+      .where(column, operator, value);
+  }
+
+  /**
+   * Create a new related model and associate it
+   * @param {Object} attributes
+   * @returns {Promise<Model>}
+   */
+  async create(attributes = {}) {
+    const model = new this.related.model(attributes);
+    model.setAttribute(this.foreignKey, this.parent.getAttribute(this.localKey));
+    await model.save();
+    return model;
+  }
+
+  /**
+   * Save an existing model and associate it
+   * @param {Model} model
+   * @returns {Promise<Model>}
+   */
+  async save(model) {
+    model.setAttribute(this.foreignKey, this.parent.getAttribute(this.localKey));
+    await model.save();
+    return model;
+  }
+
+  /**
+   * Create multiple related models and associate them
+   * @param {Array<Object>} attributesArray
+   * @returns {Promise<Array<Model>>}
+   */
+  async createMany(attributesArray) {
+    const models = [];
+    for (const attributes of attributesArray) {
+      const model = await this.create(attributes);
+      models.push(model);
+    }
+    return models;
+  }
+
+  /**
+   * Save multiple existing models and associate them
+   * @param {Array<Model>} models
+   * @returns {Promise<Array<Model>>}
+   */
+  async saveMany(models) {
+    const savedModels = [];
+    for (const model of models) {
+      const saved = await this.save(model);
+      savedModels.push(saved);
+    }
+    return savedModels;
+  }
+}
+
+module.exports = HasOneRelation;

package/src/Relations/HasOneThroughRelation.js

@@ -1,105 +1,105 @@
-const Relation = require('./Relation');
-
-/**
- * Has One Through Relation
- * parent -> through -> related (final) - returns single model
- */
-class HasOneThroughRelation extends Relation {
-  /**
-   * @param {import('../Model')} parent
-   * @param {typeof import('../Model')} relatedFinal
-   * @param {typeof import('../Model')} through
-   * @param {string} [foreignKeyOnThrough] - FK on through referencing parent
-   * @param {string} [throughKeyOnFinal] - FK on final referencing through
-   * @param {string} [localKey] - PK on parent
-   * @param {string} [throughLocalKey] - PK on through
-   */
-  constructor(parent, relatedFinal, through, foreignKeyOnThrough, throughKeyOnFinal, localKey, throughLocalKey) {
-    super(parent, relatedFinal, foreignKeyOnThrough, localKey);
-    this.through = through;
-    // Defaults based on naming conventions
-    this.localKey = localKey || parent.constructor.primaryKey || 'id';
-    this.throughLocalKey = throughLocalKey || through.primaryKey || 'id';
-    this.foreignKeyOnThrough = foreignKeyOnThrough || `${parent.constructor.table.slice(0, -1)}_id`;
-    this.throughKeyOnFinal = throughKeyOnFinal || `${through.table.slice(0, -1)}_id`;
-  }
-
-  /**
-   * Get final related model (single)
-   * @returns {Promise<import('../Model')|null>}
-   */
-  async get() {
-    const parentKeyValue = this.parent.getAttribute(this.localKey);
-    if (parentKeyValue === undefined || parentKeyValue === null) return null;
-
-    const throughRow = await this.through
-      .where(this.foreignKeyOnThrough, parentKeyValue)
-      .first();
-
-    if (!throughRow) return null;
-
-    const throughId = throughRow.getAttribute(this.throughLocalKey);
-    const result = await this.related
-      .where(this.throughKeyOnFinal, throughId)
-      .first();
-    return result;
-  }
-
-  /**
-   * Eager load hasOneThrough for a batch of parents
-   * @param {Array} models
-   * @param {string} relationName
-   * @param {(qb: any) => void} [constraint]
-   */
-  async eagerLoad(models, relationName, constraint) {
-    const parentKeys = models
-      .map(m => m.getAttribute(this.localKey))
-      .filter(v => v !== undefined && v !== null);
-
-    if (parentKeys.length === 0) {
-      models.forEach(m => { m.relations[relationName] = null; });
-      return;
-    }
-
-    // Fetch through rows for all parent keys
-    const throughRows = await this.through
-      .whereIn(this.foreignKeyOnThrough, parentKeys)
-      .get();
-
-    if (throughRows.length === 0) {
-      models.forEach(m => { m.relations[relationName] = null; });
-      return;
-    }
-
-    // Map parentKey -> throughId (assuming one through per parent)
-    const parentToThroughId = {};
-    for (const row of throughRows) {
-      const pKey = row.getAttribute(this.foreignKeyOnThrough);
-      const tId = row.getAttribute(this.throughLocalKey);
-      parentToThroughId[pKey] = tId; // overwrite if multiple, take last
-    }
-
-    const allThroughIds = Object.values(parentToThroughId);
-
-    // Fetch finals in one query (with optional constraint)
-    const qb = this.related.whereIn(this.throughKeyOnFinal, allThroughIds);
-    if (typeof constraint === 'function') constraint(qb);
-    const finals = await qb.get();
-
-    // Map through id to final
-    const finalsByThrough = {};
-    for (const f of finals) {
-      const key = f.getAttribute(this.throughKeyOnFinal);
-      finalsByThrough[key] = f; // assume one per through
-    }
-
-    // Assign to each parent
-    for (const m of models) {
-      const pKey = m.getAttribute(this.localKey);
-      const tId = parentToThroughId[pKey];
-      m.relations[relationName] = tId ? finalsByThrough[tId] || null : null;
-    }
-  }
-}
-
-module.exports = HasOneThroughRelation;
+const Relation = require('./Relation');
+
+/**
+ * Has One Through Relation
+ * parent -> through -> related (final) - returns single model
+ */
+class HasOneThroughRelation extends Relation {
+  /**
+   * @param {import('../Model')} parent
+   * @param {typeof import('../Model')} relatedFinal
+   * @param {typeof import('../Model')} through
+   * @param {string} [foreignKeyOnThrough] - FK on through referencing parent
+   * @param {string} [throughKeyOnFinal] - FK on final referencing through
+   * @param {string} [localKey] - PK on parent
+   * @param {string} [throughLocalKey] - PK on through
+   */
+  constructor(parent, relatedFinal, through, foreignKeyOnThrough, throughKeyOnFinal, localKey, throughLocalKey) {
+    super(parent, relatedFinal, foreignKeyOnThrough, localKey);
+    this.through = through;
+    // Defaults based on naming conventions
+    this.localKey = localKey || parent.constructor.primaryKey || 'id';
+    this.throughLocalKey = throughLocalKey || through.primaryKey || 'id';
+    this.foreignKeyOnThrough = foreignKeyOnThrough || `${parent.constructor.table.slice(0, -1)}_id`;
+    this.throughKeyOnFinal = throughKeyOnFinal || `${through.table.slice(0, -1)}_id`;
+  }
+
+  /**
+   * Get final related model (single)
+   * @returns {Promise<import('../Model')|null>}
+   */
+  async get() {
+    const parentKeyValue = this.parent.getAttribute(this.localKey);
+    if (parentKeyValue === undefined || parentKeyValue === null) return this._buildDefault();
+
+    const throughRow = await this.through
+      .where(this.foreignKeyOnThrough, parentKeyValue)
+      .first();
+
+    if (!throughRow) return this._buildDefault();
+
+    const throughId = throughRow.getAttribute(this.throughLocalKey);
+    const result = await this.related
+      .where(this.throughKeyOnFinal, throughId)
+      .first();
+    return result || this._buildDefault();
+  }
+
+  /**
+   * Eager load hasOneThrough for a batch of parents
+   * @param {Array} models
+   * @param {string} relationName
+   * @param {(qb: any) => void} [constraint]
+   */
+  async eagerLoad(models, relationName, constraint) {
+    const parentKeys = models
+      .map(m => m.getAttribute(this.localKey))
+      .filter(v => v !== undefined && v !== null);
+
+    if (parentKeys.length === 0) {
+      models.forEach(m => { m.relations[relationName] = null; });
+      return;
+    }
+
+    // Fetch through rows for all parent keys
+    const throughRows = await this.through
+      .whereIn(this.foreignKeyOnThrough, parentKeys)
+      .get();
+
+    if (throughRows.length === 0) {
+      models.forEach(m => { m.relations[relationName] = null; });
+      return;
+    }
+
+    // Map parentKey -> throughId (assuming one through per parent)
+    const parentToThroughId = {};
+    for (const row of throughRows) {
+      const pKey = row.getAttribute(this.foreignKeyOnThrough);
+      const tId = row.getAttribute(this.throughLocalKey);
+      parentToThroughId[pKey] = tId; // overwrite if multiple, take last
+    }
+
+    const allThroughIds = Object.values(parentToThroughId);
+
+    // Fetch finals in one query (with optional constraint)
+    const qb = this.related.whereIn(this.throughKeyOnFinal, allThroughIds);
+    if (typeof constraint === 'function') constraint(qb);
+    const finals = await qb.get();
+
+    // Map through id to final
+    const finalsByThrough = {};
+    for (const f of finals) {
+      const key = f.getAttribute(this.throughKeyOnFinal);
+      finalsByThrough[key] = f; // assume one per through
+    }
+
+    // Assign to each parent
+    for (const m of models) {
+      const pKey = m.getAttribute(this.localKey);
+      const tId = parentToThroughId[pKey];
+      m.relations[relationName] = tId ? finalsByThrough[tId] || null : null;
+    }
+  }
+}
+
+module.exports = HasOneThroughRelation;

package/src/Relations/MorphOneRelation.js

@@ -16,10 +16,12 @@ class MorphOneRelation extends Relation {
    * @returns {Promise<Model|null>}
    */
   async get() {
-    return this.related
+    const result = await this.related
       .where(this.foreignKey, this.parent.getAttribute(this.localKey))
       .where(`${this.morphType}_type`, this.parent.constructor.table)
       .first();
+
+    return result || this._buildDefault();
   }
 
   /**
@@ -46,7 +48,7 @@ class MorphOneRelation extends Relation {
 
     for (const model of models) {
       const key = model.getAttribute(this.localKey);
-      model.relations[relationName] = relatedMap[key] || null;
+      model.relations[relationName] = relatedMap[key] || this._buildDefault();
     }
   }
 

package/src/Relations/Relation.js

@@ -7,6 +7,41 @@ class Relation {
     this.related = related;
     this.foreignKey = foreignKey;
     this.localKey = localKey;
+    this._defaultValue = undefined;
+  }
+
+  /**
+   * Set a default value/model to return when the relation is empty
+   * @param {Object|Function|boolean} [value=true] - Default attributes, factory fn, or true for empty model
+   * @returns {this}
+   */
+  withDefault(value = true) {
+    this._defaultValue = value;
+    return this;
+  }
+
+  /**
+   * Build the default model when the relation result is null
+   * @returns {Model|null}
+   * @protected
+   */
+  _buildDefault() {
+    if (this._defaultValue === undefined) return null;
+    if (typeof this._defaultValue === 'function') return this._defaultValue();
+    if (this._defaultValue === true) {
+      // Return an empty instance of the related model
+      const RelatedModel = typeof this.related === 'function' && this.related.prototype
+        ? this.related
+        : this.related.constructor;
+      return new RelatedModel();
+    }
+    if (typeof this._defaultValue === 'object' && this._defaultValue !== null) {
+      const RelatedModel = typeof this.related === 'function' && this.related.prototype
+        ? this.related
+        : this.related.constructor;
+      return new RelatedModel(this._defaultValue);
+    }
+    return null;
   }
 
   /**

package/types/index.d.ts

@@ -88,6 +88,8 @@ declare module 'outlet-orm' {
     update(table: string, data: Record<string, any>, query: QueryObject): Promise<UpdateResult>;
     delete(table: string, query: QueryObject): Promise<DeleteResult>;
     count(table: string, query: QueryObject): Promise<number>;
+    /** Execute an aggregate function (SUM, AVG, MIN, MAX) */
+    aggregate(table: string, fn: 'SUM' | 'AVG' | 'MIN' | 'MAX', column: string, query: QueryObject): Promise<number>;
     executeRawQuery(sql: string, params?: any[]): Promise<any[]>;
     /** Execute raw SQL and return driver-native results (used by migrations) */
     execute(sql: string, params?: any[]): Promise<any>;
@@ -237,6 +239,37 @@ declare module 'outlet-orm' {
     /** Lazily iterate over matching records using an async generator */
     cursor(chunkSize?: number): AsyncGenerator<T, void, unknown>;
 
+    // Convenience query methods
+    /** Get an array of values for a single column, optionally keyed by another column */
+    pluck(column: string): Promise<any[]>;
+    pluck(column: string, keyColumn: string): Promise<Record<string, any>>;
+    /** Get the value of a single column from the first matching row */
+    value(column: string): Promise<any>;
+
+    // Aggregate methods
+    /** Get the sum of a column */
+    sum(column: string): Promise<number>;
+    /** Get the average of a column */
+    avg(column: string): Promise<number>;
+    /** Get the minimum value of a column */
+    min(column: string): Promise<number>;
+    /** Get the maximum value of a column */
+    max(column: string): Promise<number>;
+
+    // Batch & conditional methods
+    /** Process results in chunks */
+    chunk(size: number, callback: (chunk: T[], page: number) => void | false | Promise<void | false>): Promise<void>;
+    /** Conditionally apply a callback to the query */
+    when(condition: any, callback: (qb: this, value: any) => void, fallback?: (qb: this, value: any) => void): this;
+    /** Pass the query builder to a callback without modifying the chain */
+    tap(callback: (qb: this) => void): this;
+
+    // Debugging
+    /** Get the SQL representation of the current query */
+    toSQL(): { table: string } & QueryObject;
+    /** Dump the SQL and throw */
+    dd(): never;
+
     clone(): QueryBuilder<T>;
   }
 
@@ -279,10 +312,15 @@ declare module 'outlet-orm' {
   export type EventCallback<T extends Model = Model> = (model: T) => boolean | void | Promise<boolean | void>;
 
   /**
-   * Base Model class with optional generic for typed attributes
+   * Base Model class with optional generic for typed attributes.
+   * Instances are wrapped in a Proxy so attributes can be accessed
+   * directly as properties: `user.name` / `user.name = 'Jean'`.
+   * Existing methods (getAttribute, setAttribute) remain available.
    * @template TAttributes - Type of model attributes (defaults to Record<string, any>)
    */
   export class Model<TAttributes extends Record<string, any> = Record<string, any>> {
+    /** Property-style attribute access via Proxy (read & write) */
+    [K: string]: any;
     static table: string;
     static primaryKey: string;
     static timestamps: boolean;
@@ -290,6 +328,8 @@ declare module 'outlet-orm' {
     static hidden: string[];
     static casts: Record<string, CastType>;
     static connection: DatabaseConnection | null;
+    /** Computed attributes to append in serialization */
+    static appends: string[];
 
     // Soft Deletes
     static softDeletes: boolean;
@@ -409,6 +449,30 @@ declare module 'outlet-orm' {
     /** Load relations on an existing instance. Supports dot-notation and arrays. */
     load(...relations: string[] | [string[]]): Promise<this>;
 
+    // Model instance utilities
+    /** Reload a fresh model instance from the database */
+    fresh(...relations: string[]): Promise<this | null>;
+    /** Reload attributes from DB into this instance */
+    refresh(): Promise<this>;
+    /** Clone the model without the primary key */
+    replicate(...except: string[]): this;
+    /** Check if two models have the same ID and table */
+    is(model: Model | null): boolean;
+    /** Check if two models are different */
+    isNot(model: Model | null): boolean;
+    /** Get a subset of attributes as a plain object */
+    only(...keys: (string | string[])[]): Partial<TAttributes>;
+    /** Get all attributes except specified keys */
+    except(...keys: (string | string[])[]): Partial<TAttributes>;
+    /** Make attributes visible on this instance */
+    makeVisible(...attrs: (string | string[])[]): this;
+    /** Make attributes hidden on this instance */
+    makeHidden(...attrs: (string | string[])[]): this;
+    /** Check if attribute was changed on last save */
+    wasChanged(attr?: string): boolean;
+    /** Get attributes changed on last save */
+    getChanges(): Partial<TAttributes>;
+
     // Soft delete instance methods
     trashed(): boolean;
     restore(): Promise<this>;
@@ -459,6 +523,8 @@ declare module 'outlet-orm' {
 
   export abstract class Relation<T extends Model> {
     constructor(parent: Model, related: new () => T, foreignKey: string, localKey: string);
+    /** Set a default value when the relation result is null */
+    withDefault(value?: Record<string, any> | (() => T) | boolean): this;
     abstract get(): Promise<T | T[] | null>;
     abstract eagerLoad(models: Model[], relationName: string, constraint?: (qb: QueryBuilder<T>) => void): Promise<void>;
   }