outlet-orm 9.0.2 → 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/src/index.js

@@ -33,9 +33,9 @@ const MCPServer          = require('./AI/MCPServer');
 const AISafetyGuardrails = require('./AI/AISafetyGuardrails');
 const PromptGenerator    = require('./AI/PromptGenerator');
 
-// AI Bridge (v8.0.0) — Multi-provider LLM abstraction
-const AiBridgeManager       = require('./AI/AiBridgeManager');
-const AiBridgeFacade        = require('./AI/Facades/AiBridge');
+// AI (v8.0.0) — Multi-provider LLM abstraction
+const AIManager             = require('./AI/AIManager');
+const AIFacade              = require('./AI/Facades/AI');
 const TextBuilder           = require('./AI/Builders/TextBuilder');
 const ChatProviderContract  = require('./AI/Contracts/ChatProviderContract');
 const EmbeddingsProviderContract = require('./AI/Contracts/EmbeddingsProviderContract');
@@ -110,9 +110,9 @@ module.exports = {
   AISafetyGuardrails,
   PromptGenerator,
 
-  // AI Bridge (v8.0.0)
-  AiBridgeManager,
-  AiBridgeFacade,
+  // AI (v8.0.0)
+  AIManager,
+  AIFacade,
   TextBuilder,
   ChatProviderContract,
   EmbeddingsProviderContract,