outlet-orm 2.5.0

package/src/Relations/HasManyThroughRelation.js

@@ -0,0 +1,112 @@
+const Relation = require('./Relation');
+
+/**
+ * Has Many Through Relation
+ * parent -> through -> related (final)
+ */
+class HasManyThroughRelation 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 models
+   * @returns {Promise<Array>}
+   */
+  async get() {
+    const parentKeyValue = this.parent.getAttribute(this.localKey);
+    if (parentKeyValue === undefined || parentKeyValue === null) return [];
+
+    const throughRows = await this.through
+      .where(this.foreignKeyOnThrough, parentKeyValue)
+      .columns([this.throughLocalKey])
+      .get();
+
+    const throughIds = throughRows.map(r => r.getAttribute(this.throughLocalKey));
+    if (throughIds.length === 0) return [];
+
+    const results = await this.related
+      .whereIn(this.throughKeyOnFinal, throughIds)
+      .get();
+    return results;
+  }
+
+  /**
+   * Eager load hasManyThrough 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] = []; });
+      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] = []; });
+      return;
+    }
+
+    // Map parentKey -> array of throughIds
+    const parentToThroughIds = {};
+    for (const row of throughRows) {
+      const pKey = row.getAttribute(this.foreignKeyOnThrough);
+      const tId = row.getAttribute(this.throughLocalKey);
+      if (!parentToThroughIds[pKey]) parentToThroughIds[pKey] = [];
+      parentToThroughIds[pKey].push(tId);
+    }
+
+    const allThroughIds = [...new Set(throughRows.map(r => r.getAttribute(this.throughLocalKey)))];
+
+    // 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();
+
+    // Group finals by through id
+    const finalsByThrough = {};
+    for (const f of finals) {
+      const key = f.getAttribute(this.throughKeyOnFinal);
+      if (!finalsByThrough[key]) finalsByThrough[key] = [];
+      finalsByThrough[key].push(f);
+    }
+
+    // Assign to each parent
+    for (const m of models) {
+      const pKey = m.getAttribute(this.localKey);
+      const tIds = parentToThroughIds[pKey] || [];
+      const collected = [];
+      for (const tId of tIds) {
+        if (finalsByThrough[tId]) collected.push(...finalsByThrough[tId]);
+      }
+      m.relations[relationName] = collected;
+    }
+  }
+}
+
+module.exports = HasManyThroughRelation;

package/src/Relations/HasOneRelation.js

@@ -0,0 +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;

package/src/Relations/HasOneThroughRelation.js

@@ -0,0 +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;

package/src/Relations/MorphManyRelation.js

@@ -0,0 +1,69 @@
+const Relation = require('./Relation');
+
+/**
+ * Morph Many Relation
+ * Represents a polymorphic one-to-many relationship
+ */
+class MorphManyRelation extends Relation {
+  constructor(parent, related, morphType, foreignKey, localKey) {
+    super(parent, related, foreignKey, localKey);
+    this.parent = parent;
+    this.morphType = morphType;
+  }
+
+  /**
+   * Get the related models
+   * @returns {Promise<Array<Model>>}
+   */
+  async get() {
+    return this.related
+      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
+      .where(`${this.morphType}_type`, this.parent.constructor.table)
+      .get();
+  }
+
+  /**
+   * 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));
+
+    const qb = this.related
+      .whereIn(this.foreignKey, keys)
+      .where(`${this.morphType}_type`, models[0].constructor.table);
+
+    if (typeof constraint === 'function') constraint(qb);
+    const relatedModels = await qb.get();
+
+    const relatedMap = {};
+    for (const model of relatedModels) {
+      const fk = model.getAttribute(this.foreignKey);
+      if (!relatedMap[fk]) relatedMap[fk] = [];
+      relatedMap[fk].push(model);
+    }
+
+    for (const model of models) {
+      const key = model.getAttribute(this.localKey);
+      model.relations[relationName] = relatedMap[key] || [];
+    }
+  }
+
+  /**
+   * 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(`${this.morphType}_type`, this.parent.constructor.table)
+      .where(column, operator, value);
+  }
+}
+
+module.exports = MorphManyRelation;

package/src/Relations/MorphOneRelation.js

@@ -0,0 +1,68 @@
+const Relation = require('./Relation');
+
+/**
+ * Morph One Relation
+ * Represents a polymorphic one-to-one relationship
+ */
+class MorphOneRelation extends Relation {
+  constructor(parent, related, morphType, foreignKey, localKey) {
+    super(parent, related, foreignKey, localKey);
+    this.parent = parent;
+    this.morphType = morphType;
+  }
+
+  /**
+   * Get the related model
+   * @returns {Promise<Model|null>}
+   */
+  async get() {
+    return this.related
+      .where(this.foreignKey, this.parent.getAttribute(this.localKey))
+      .where(`${this.morphType}_type`, this.parent.constructor.table)
+      .first();
+  }
+
+  /**
+   * 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));
+
+    const qb = this.related
+      .whereIn(this.foreignKey, keys)
+      .where(`${this.morphType}_type`, models[0].constructor.table);
+
+    if (typeof constraint === 'function') constraint(qb);
+    const relatedModels = await qb.get();
+
+    const relatedMap = {};
+    for (const model of relatedModels) {
+      const fk = model.getAttribute(this.foreignKey);
+      relatedMap[fk] = model;
+    }
+
+    for (const model of models) {
+      const key = model.getAttribute(this.localKey);
+      model.relations[relationName] = relatedMap[key] || 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(`${this.morphType}_type`, this.parent.constructor.table)
+      .where(column, operator, value);
+  }
+}
+
+module.exports = MorphOneRelation;

package/src/Relations/MorphToRelation.js

@@ -0,0 +1,110 @@
+const Relation = require('./Relation');
+
+/**
+ * Morph To Relation
+ * Represents a polymorphic inverse relationship
+ */
+class MorphToRelation extends Relation {
+  constructor(child, name, typeColumn = null, idColumn = null) {
+    super(child, null, null, null); // related is dynamic
+    this.child = child;
+    this.name = name;
+    this.typeColumn = typeColumn || `${name}_type`;
+    this.idColumn = idColumn || `${name}_id`;
+  }
+
+  /**
+   * Get the related model
+   * @returns {Promise<Model|null>}
+   */
+  async get() {
+    const morphType = this.child.getAttribute(this.typeColumn);
+    const morphId = this.child.getAttribute(this.idColumn);
+
+    if (!morphType || !morphId) {
+      return null;
+    }
+
+    // Resolve the model class from type
+    const relatedClass = this.resolveMorphClass(morphType);
+    if (!relatedClass) {
+      return null;
+    }
+
+    return relatedClass.where(relatedClass.primaryKey, morphId).first();
+  }
+
+  /**
+   * Resolve the model class from morph type
+   * @param {string} morphType
+   * @returns {typeof Model|null}
+   */
+  resolveMorphClass(morphType) {
+    // Check morph map first
+    const morphMap = this.child.constructor.morphMap || {};
+    if (morphMap[morphType]) {
+      return morphMap[morphType];
+    }
+
+    // Fallback: assume morphType is the table name or class name
+    // For simplicity, return null if not mapped
+    return null;
+  }
+
+  /**
+   * Eager load the relationship for a collection of child models
+   * @param {Array<Model>} models
+   * @param {string} relationName
+   * @returns {Promise<void>}
+   */
+  async eagerLoad(models, relationName, constraint) {
+    // Group models by morph type
+    const grouped = {};
+    for (const model of models) {
+      const type = model.getAttribute(this.typeColumn);
+      const id = model.getAttribute(this.idColumn);
+      if (type && id) {
+        if (!grouped[type]) grouped[type] = { ids: [], models: [] };
+        grouped[type].ids.push(id);
+        grouped[type].models.push(model);
+      }
+    }
+
+    // Load each type separately
+    for (const [type, { ids, models: typeModels }] of Object.entries(grouped)) {
+      const relatedClass = this.resolveMorphClass(type);
+      if (!relatedClass) continue;
+
+      const qb = relatedClass.whereIn(relatedClass.primaryKey, ids);
+      if (typeof constraint === 'function') constraint(qb);
+      const relatedModels = await qb.get();
+
+      const relatedMap = {};
+      for (const model of relatedModels) {
+        const pk = model.getAttribute(relatedClass.primaryKey);
+        relatedMap[pk] = model;
+      }
+
+      for (const model of typeModels) {
+        const id = model.getAttribute(this.idColumn);
+        model.relations[relationName] = relatedMap[id] || null;
+      }
+    }
+  }
+
+  /**
+   * Add a where clause to the relation query
+   * Note: Since related is dynamic, this is limited
+   * @param {string} _column
+   * @param {string|any} _operator
+   * @param {any} _value
+   * @returns {QueryBuilder}
+   */
+  where(_column, _operator, _value) {
+    // This is tricky since related is dynamic
+    // For now, throw error or handle basic case
+    throw new Error('where() on morphTo relation is not fully supported yet');
+  }
+}
+
+module.exports = MorphToRelation;

package/src/Relations/Relation.js

@@ -0,0 +1,31 @@
+/**
+ * Base Relation class
+ */
+class Relation {
+  constructor(parent, related, foreignKey, localKey) {
+    this.parent = parent;
+    this.related = related;
+    this.foreignKey = foreignKey;
+    this.localKey = localKey;
+  }
+
+  /**
+   * Get the results of the relationship
+   * @returns {Promise<Model|Array<Model>|null>}
+   */
+  async get() {
+    throw new Error('Method get() must be implemented by subclass');
+  }
+
+  /**
+   * Eager load the relationship for a collection of parent models
+   * @param {Array<Model>} models
+   * @param {string} relationName
+   * @returns {Promise<void>}
+   */
+  async eagerLoad(_models, _relationName) {
+    throw new Error('Method eagerLoad() must be implemented by subclass');
+  }
+}
+
+module.exports = Relation;

package/src/index.js

@@ -0,0 +1,23 @@
+const Model = require('./Model');
+const QueryBuilder = require('./QueryBuilder');
+const DatabaseConnection = require('./DatabaseConnection');
+
+// Relations
+const Relation = require('./Relations/Relation');
+const HasOneRelation = require('./Relations/HasOneRelation');
+const HasManyRelation = require('./Relations/HasManyRelation');
+const BelongsToRelation = require('./Relations/BelongsToRelation');
+const BelongsToManyRelation = require('./Relations/BelongsToManyRelation');
+const HasManyThroughRelation = require('./Relations/HasManyThroughRelation');
+
+module.exports = {
+  Model,
+  QueryBuilder,
+  DatabaseConnection,
+  Relation,
+  HasOneRelation,
+  HasManyRelation,
+  BelongsToRelation,
+  BelongsToManyRelation,
+  HasManyThroughRelation
+};