arkormx 1.2.1 → 1.3.0

package/dist/index.cjs

@@ -3449,6 +3449,30 @@ var Relation = class {
 		if (results instanceof ArkormCollection) return results.all()[0] ?? null;
 		return results;
 	}
+	/**
+	* Count records that match the relationship query.
+	*
+	* @returns
+	*/
+	async count() {
+		return (await this.getQuery()).count();
+	}
+	/**
+	* Determine whether the relationship query has any matching records.
+	*
+	* @returns
+	*/
+	async exists() {
+		return (await this.getQuery()).exists();
+	}
+	/**
+	* Determine whether the relationship query has no matching records.
+	*
+	* @returns
+	*/
+	async doesntExist() {
+		return !await this.exists();
+	}
 };
 
 //#endregion
@@ -3471,15 +3495,55 @@ var BelongsToManyRelation = class extends Relation {
 		this.relatedKey = relatedKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const parentValue = this.parent.getAttribute(this.parentKey);
+		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.foreignPivotKey]: parentValue } })).map((row) => row[this.relatedPivotKey]);
+		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const parentValue = this.parent.getAttribute(this.parentKey);
-		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.foreignPivotKey]: parentValue } })).map((row) => row[this.relatedPivotKey]);
-		if (ids.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
+		return (await this.getQuery()).get();
+	}
+};
+
+//#endregion
+//#region src/relationship/SingleResultRelation.ts
+/**
+* Base class for relationships that resolve to a single related model.
+* 
+* @author Legacy (3m1n3nc3)
+* @since 1.3.0
+*/
+var SingleResultRelation = class extends Relation {
+	defaultValue;
+	constructor(parent, related) {
+		super();
+		this.parent = parent;
+		this.related = related;
+	}
+	/**
+	* Defines a default value to return when the relationship does not find a related model.
+	* 
+	* @param value     The default value or a callback that returns the default value.
+	* @returns         The current instance for method chaining.
+	*/
+	withDefault(value = {}) {
+		this.defaultValue = value;
+		return this;
+	}
+	resolveDefaultResult() {
+		if (typeof this.defaultValue === "undefined") return null;
+		const resolved = typeof this.defaultValue === "function" ? this.defaultValue(this.parent) : this.defaultValue;
+		if (resolved instanceof this.related) return resolved;
+		return this.related.hydrate(resolved);
 	}
 };
 
@@ -3491,22 +3555,28 @@ var BelongsToManyRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var BelongsToRelation = class extends Relation {
+var BelongsToRelation = class extends SingleResultRelation {
 	constructor(parent, related, foreignKey, ownerKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.foreignKey = foreignKey;
 		this.ownerKey = ownerKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const foreignValue = this.parent.getAttribute(this.foreignKey);
+		return this.applyConstraint(this.related.query().where({ [this.ownerKey]: foreignValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const foreignValue = this.parent.getAttribute(this.foreignKey);
-		return this.applyConstraint(this.related.query().where({ [this.ownerKey]: foreignValue })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3527,13 +3597,21 @@ var HasManyRelation = class extends Relation {
 		this.localKey = localKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue })).get();
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3558,15 +3636,22 @@ var HasManyThroughRelation = class extends Relation {
 		this.secondLocalKey = secondLocalKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		const keys = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.firstKey]: localValue } })).map((row) => row[this.secondLocalKey]);
+		return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: keys } }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		const keys = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.firstKey]: localValue } })).map((row) => row[this.secondLocalKey]);
-		if (keys.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: keys } })).get();
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3578,22 +3663,28 @@ var HasManyThroughRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var HasOneRelation = class extends Relation {
+var HasOneRelation = class extends SingleResultRelation {
 	constructor(parent, related, foreignKey, localKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.foreignKey = foreignKey;
 		this.localKey = localKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3606,11 +3697,9 @@ var HasOneRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var HasOneThroughRelation = class extends Relation {
+var HasOneThroughRelation = class extends SingleResultRelation {
 	constructor(parent, related, throughDelegate, firstKey, secondKey, localKey, secondLocalKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.throughDelegate = throughDelegate;
 		this.firstKey = firstKey;
 		this.secondKey = secondKey;
@@ -3618,15 +3707,23 @@ var HasOneThroughRelation = class extends Relation {
 		this.secondLocalKey = secondLocalKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		const intermediate = await this.related.getDelegate(this.throughDelegate).findFirst({ where: { [this.firstKey]: localValue } });
+		if (!intermediate) return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: [] } }));
+		return this.applyConstraint(this.related.query().where({ [this.secondKey]: intermediate[this.secondLocalKey] }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		const intermediate = await this.related.getDelegate(this.throughDelegate).findFirst({ where: { [this.firstKey]: localValue } });
-		if (!intermediate) return null;
-		return this.applyConstraint(this.related.query().where({ [this.secondKey]: intermediate[this.secondLocalKey] })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3647,17 +3744,25 @@ var MorphManyRelation = class extends Relation {
 		this.localKey = localKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const id = this.parent.getAttribute(this.localKey);
 		const type = this.parent.constructor.name;
 		return this.applyConstraint(this.related.query().where({
 			[`${this.morphName}Id`]: id,
 			[`${this.morphName}Type`]: type
-		})).get();
+		}));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3669,26 +3774,32 @@ var MorphManyRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var MorphOneRelation = class extends Relation {
+var MorphOneRelation = class extends SingleResultRelation {
 	constructor(parent, related, morphName, localKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.morphName = morphName;
 		this.localKey = localKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const id = this.parent.getAttribute(this.localKey);
 		const type = this.parent.constructor.name;
 		return this.applyConstraint(this.related.query().where({
 			[`${this.morphName}Id`]: id,
 			[`${this.morphName}Type`]: type
-		})).first();
+		}));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3712,19 +3823,26 @@ var MorphToManyRelation = class extends Relation {
 		this.relatedKey = relatedKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const parentValue = this.parent.getAttribute(this.parentKey);
 		const morphType = this.parent.constructor.name;
 		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: {
 			[`${this.morphName}Id`]: parentValue,
 			[`${this.morphName}Type`]: morphType
 		} })).map((row) => row[this.relatedPivotKey]);
-		if (ids.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
+		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } }));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return (await this.getQuery()).get();
 	}
 };
 

package/dist/index.d.cts

@@ -118,6 +118,7 @@ declare class ArkormCollection<T = any, X = T[]> extends Collection<T, X> {}
 //#endregion
 //#region src/types/relationship.d.ts
 type RelationConstraint<TModel> = (query: QueryBuilder<TModel>) => QueryBuilder<TModel> | void;
+type RelationDefaultValue<TParent, TRelated> = Partial<ModelAttributes<TRelated>> | TRelated | ((parent: TParent) => Partial<ModelAttributes<TRelated>> | TRelated);
 //#endregion
 //#region src/relationship/Relation.d.ts
 /**
@@ -234,6 +235,12 @@ declare abstract class Relation<TModel> {
    * @returns The query builder instance with the constraint applied, if any.
    */
   protected applyConstraint(query: QueryBuilder<TModel>): QueryBuilder<TModel>;
+  /**
+   * Build the underlying query for the relationship.
+   *
+   * @returns
+   */
+  abstract getQuery(): Promise<QueryBuilder<TModel>>;
   /**
    * Execute the relationship query and return relation results.
    *
@@ -246,6 +253,24 @@ declare abstract class Relation<TModel> {
    * @returns
    */
   first(): Promise<TModel | null>;
+  /**
+   * Count records that match the relationship query.
+   *
+   * @returns
+   */
+  count(): Promise<number>;
+  /**
+   * Determine whether the relationship query has any matching records.
+   *
+   * @returns
+   */
+  exists(): Promise<boolean>;
+  /**
+   * Determine whether the relationship query has no matching records.
+   *
+   * @returns
+   */
+  doesntExist(): Promise<boolean>;
   /**
    * Get the results of the relationship query.
    *
@@ -272,6 +297,12 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, foreignPivotKey: string, relatedPivotKey: string, parentKey: string, relatedKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -280,6 +311,28 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
   getResults(): Promise<ArkormCollection<TRelated>>;
 }
 //#endregion
+//#region src/relationship/SingleResultRelation.d.ts
+/**
+ * Base class for relationships that resolve to a single related model.
+ *
+ * @author Legacy (3m1n3nc3)
+ * @since 1.3.0
+ */
+declare abstract class SingleResultRelation<TParent, TRelated> extends Relation<TRelated> {
+  protected readonly parent: TParent;
+  protected readonly related: RelatedModelClass<TRelated>;
+  protected defaultValue: RelationDefaultValue<object, TRelated> | undefined;
+  protected constructor(parent: TParent, related: RelatedModelClass<TRelated>);
+  /**
+   * Defines a default value to return when the relationship does not find a related model.
+   *
+   * @param value     The default value or a callback that returns the default value.
+   * @returns         The current instance for method chaining.
+   */
+  withDefault(value?: RelationDefaultValue<TParent, TRelated>): this;
+  protected resolveDefaultResult(): TRelated | null;
+}
+//#endregion
 //#region src/relationship/BelongsToRelation.d.ts
 /**
  * Defines an inverse one-to-one or many relationship.
@@ -287,14 +340,20 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class BelongsToRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class BelongsToRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly foreignKey;
   private readonly ownerKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, foreignKey: string, ownerKey: string);
+  }, related: RelatedModelClass<TRelated>, foreignKey: string, ownerKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -318,6 +377,12 @@ declare class HasManyRelation<TParent, TRelated> extends Relation<TRelated> {
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, foreignKey: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -345,6 +410,12 @@ declare class HasManyThroughRelation<TParent, TRelated> extends Relation<TRelate
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -360,14 +431,20 @@ declare class HasManyThroughRelation<TParent, TRelated> extends Relation<TRelate
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class HasOneRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class HasOneRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly foreignKey;
   private readonly localKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, foreignKey: string, localKey: string);
+  }, related: RelatedModelClass<TRelated>, foreignKey: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -384,9 +461,9 @@ declare class HasOneRelation<TParent, TRelated> extends Relation<TRelated> {
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class HasOneThroughRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class HasOneThroughRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly throughDelegate;
   private readonly firstKey;
   private readonly secondKey;
@@ -394,7 +471,13 @@ declare class HasOneThroughRelation<TParent, TRelated> extends Relation<TRelated
   private readonly secondLocalKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  }, related: RelatedModelClass<TRelated>, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -418,6 +501,12 @@ declare class MorphManyRelation<TParent, TRelated> extends Relation<TRelated> {
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, morphName: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -433,14 +522,20 @@ declare class MorphManyRelation<TParent, TRelated> extends Relation<TRelated> {
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class MorphOneRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class MorphOneRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly morphName;
   private readonly localKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, morphName: string, localKey: string);
+  }, related: RelatedModelClass<TRelated>, morphName: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -467,6 +562,12 @@ declare class MorphToManyRelation<TParent, TRelated> extends Relation<TRelated>
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, morphName: string, relatedPivotKey: string, parentKey: string, relatedKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -2016,7 +2117,9 @@ interface ModelStatic<TModel, TDelegate extends PrismaDelegateLike = PrismaDeleg
   getSoftDeleteConfig: () => SoftDeleteConfig;
 }
 interface RelationshipModelStatic {
+  new (attributes?: Record<string, unknown>): any;
   query: () => QueryBuilder<any, any>;
+  hydrate: (attributes: Record<string, unknown>) => any;
   getDelegate: (delegate?: string) => PrismaDelegateLike;
 }
 //#endregion

package/dist/index.d.mts

@@ -118,6 +118,7 @@ declare class ArkormCollection<T = any, X = T[]> extends Collection<T, X> {}
 //#endregion
 //#region src/types/relationship.d.ts
 type RelationConstraint<TModel> = (query: QueryBuilder<TModel>) => QueryBuilder<TModel> | void;
+type RelationDefaultValue<TParent, TRelated> = Partial<ModelAttributes<TRelated>> | TRelated | ((parent: TParent) => Partial<ModelAttributes<TRelated>> | TRelated);
 //#endregion
 //#region src/relationship/Relation.d.ts
 /**
@@ -234,6 +235,12 @@ declare abstract class Relation<TModel> {
    * @returns The query builder instance with the constraint applied, if any.
    */
   protected applyConstraint(query: QueryBuilder<TModel>): QueryBuilder<TModel>;
+  /**
+   * Build the underlying query for the relationship.
+   *
+   * @returns
+   */
+  abstract getQuery(): Promise<QueryBuilder<TModel>>;
   /**
    * Execute the relationship query and return relation results.
    *
@@ -246,6 +253,24 @@ declare abstract class Relation<TModel> {
    * @returns
    */
   first(): Promise<TModel | null>;
+  /**
+   * Count records that match the relationship query.
+   *
+   * @returns
+   */
+  count(): Promise<number>;
+  /**
+   * Determine whether the relationship query has any matching records.
+   *
+   * @returns
+   */
+  exists(): Promise<boolean>;
+  /**
+   * Determine whether the relationship query has no matching records.
+   *
+   * @returns
+   */
+  doesntExist(): Promise<boolean>;
   /**
    * Get the results of the relationship query.
    *
@@ -272,6 +297,12 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, foreignPivotKey: string, relatedPivotKey: string, parentKey: string, relatedKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -280,6 +311,28 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
   getResults(): Promise<ArkormCollection<TRelated>>;
 }
 //#endregion
+//#region src/relationship/SingleResultRelation.d.ts
+/**
+ * Base class for relationships that resolve to a single related model.
+ *
+ * @author Legacy (3m1n3nc3)
+ * @since 1.3.0
+ */
+declare abstract class SingleResultRelation<TParent, TRelated> extends Relation<TRelated> {
+  protected readonly parent: TParent;
+  protected readonly related: RelatedModelClass<TRelated>;
+  protected defaultValue: RelationDefaultValue<object, TRelated> | undefined;
+  protected constructor(parent: TParent, related: RelatedModelClass<TRelated>);
+  /**
+   * Defines a default value to return when the relationship does not find a related model.
+   *
+   * @param value     The default value or a callback that returns the default value.
+   * @returns         The current instance for method chaining.
+   */
+  withDefault(value?: RelationDefaultValue<TParent, TRelated>): this;
+  protected resolveDefaultResult(): TRelated | null;
+}
+//#endregion
 //#region src/relationship/BelongsToRelation.d.ts
 /**
  * Defines an inverse one-to-one or many relationship.
@@ -287,14 +340,20 @@ declare class BelongsToManyRelation<TParent, TRelated> extends Relation<TRelated
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class BelongsToRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class BelongsToRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly foreignKey;
   private readonly ownerKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, foreignKey: string, ownerKey: string);
+  }, related: RelatedModelClass<TRelated>, foreignKey: string, ownerKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -318,6 +377,12 @@ declare class HasManyRelation<TParent, TRelated> extends Relation<TRelated> {
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, foreignKey: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -345,6 +410,12 @@ declare class HasManyThroughRelation<TParent, TRelated> extends Relation<TRelate
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -360,14 +431,20 @@ declare class HasManyThroughRelation<TParent, TRelated> extends Relation<TRelate
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class HasOneRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class HasOneRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly foreignKey;
   private readonly localKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, foreignKey: string, localKey: string);
+  }, related: RelatedModelClass<TRelated>, foreignKey: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -384,9 +461,9 @@ declare class HasOneRelation<TParent, TRelated> extends Relation<TRelated> {
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class HasOneThroughRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class HasOneThroughRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly throughDelegate;
   private readonly firstKey;
   private readonly secondKey;
@@ -394,7 +471,13 @@ declare class HasOneThroughRelation<TParent, TRelated> extends Relation<TRelated
   private readonly secondLocalKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  }, related: RelatedModelClass<TRelated>, throughDelegate: string, firstKey: string, secondKey: string, localKey: string, secondLocalKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -418,6 +501,12 @@ declare class MorphManyRelation<TParent, TRelated> extends Relation<TRelated> {
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, morphName: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -433,14 +522,20 @@ declare class MorphManyRelation<TParent, TRelated> extends Relation<TRelated> {
  * @author Legacy (3m1n3nc3)
  * @since 0.1.0
  */
-declare class MorphOneRelation<TParent, TRelated> extends Relation<TRelated> {
-  private readonly parent;
-  private readonly related;
+declare class MorphOneRelation<TParent, TRelated> extends SingleResultRelation<TParent & {
+  getAttribute: (key: string) => unknown;
+}, TRelated> {
   private readonly morphName;
   private readonly localKey;
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
-  }, related: RelationshipModelStatic, morphName: string, localKey: string);
+  }, related: RelatedModelClass<TRelated>, morphName: string, localKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -467,6 +562,12 @@ declare class MorphToManyRelation<TParent, TRelated> extends Relation<TRelated>
   constructor(parent: TParent & {
     getAttribute: (key: string) => unknown;
   }, related: RelationshipModelStatic, throughDelegate: string, morphName: string, relatedPivotKey: string, parentKey: string, relatedKey: string);
+  /**
+   * Build the relationship query.
+   *
+   * @returns
+   */
+  getQuery(): Promise<QueryBuilder<TRelated>>;
   /**
    * Fetches the related models for this relationship.
    *
@@ -2016,7 +2117,9 @@ interface ModelStatic<TModel, TDelegate extends PrismaDelegateLike = PrismaDeleg
   getSoftDeleteConfig: () => SoftDeleteConfig;
 }
 interface RelationshipModelStatic {
+  new (attributes?: Record<string, unknown>): any;
   query: () => QueryBuilder<any, any>;
+  hydrate: (attributes: Record<string, unknown>) => any;
   getDelegate: (delegate?: string) => PrismaDelegateLike;
 }
 //#endregion

package/dist/index.mjs

@@ -3420,6 +3420,30 @@ var Relation = class {
 		if (results instanceof ArkormCollection) return results.all()[0] ?? null;
 		return results;
 	}
+	/**
+	* Count records that match the relationship query.
+	*
+	* @returns
+	*/
+	async count() {
+		return (await this.getQuery()).count();
+	}
+	/**
+	* Determine whether the relationship query has any matching records.
+	*
+	* @returns
+	*/
+	async exists() {
+		return (await this.getQuery()).exists();
+	}
+	/**
+	* Determine whether the relationship query has no matching records.
+	*
+	* @returns
+	*/
+	async doesntExist() {
+		return !await this.exists();
+	}
 };
 
 //#endregion
@@ -3442,15 +3466,55 @@ var BelongsToManyRelation = class extends Relation {
 		this.relatedKey = relatedKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const parentValue = this.parent.getAttribute(this.parentKey);
+		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.foreignPivotKey]: parentValue } })).map((row) => row[this.relatedPivotKey]);
+		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const parentValue = this.parent.getAttribute(this.parentKey);
-		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.foreignPivotKey]: parentValue } })).map((row) => row[this.relatedPivotKey]);
-		if (ids.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
+		return (await this.getQuery()).get();
+	}
+};
+
+//#endregion
+//#region src/relationship/SingleResultRelation.ts
+/**
+* Base class for relationships that resolve to a single related model.
+* 
+* @author Legacy (3m1n3nc3)
+* @since 1.3.0
+*/
+var SingleResultRelation = class extends Relation {
+	defaultValue;
+	constructor(parent, related) {
+		super();
+		this.parent = parent;
+		this.related = related;
+	}
+	/**
+	* Defines a default value to return when the relationship does not find a related model.
+	* 
+	* @param value     The default value or a callback that returns the default value.
+	* @returns         The current instance for method chaining.
+	*/
+	withDefault(value = {}) {
+		this.defaultValue = value;
+		return this;
+	}
+	resolveDefaultResult() {
+		if (typeof this.defaultValue === "undefined") return null;
+		const resolved = typeof this.defaultValue === "function" ? this.defaultValue(this.parent) : this.defaultValue;
+		if (resolved instanceof this.related) return resolved;
+		return this.related.hydrate(resolved);
 	}
 };
 
@@ -3462,22 +3526,28 @@ var BelongsToManyRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var BelongsToRelation = class extends Relation {
+var BelongsToRelation = class extends SingleResultRelation {
 	constructor(parent, related, foreignKey, ownerKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.foreignKey = foreignKey;
 		this.ownerKey = ownerKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const foreignValue = this.parent.getAttribute(this.foreignKey);
+		return this.applyConstraint(this.related.query().where({ [this.ownerKey]: foreignValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const foreignValue = this.parent.getAttribute(this.foreignKey);
-		return this.applyConstraint(this.related.query().where({ [this.ownerKey]: foreignValue })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3498,13 +3568,21 @@ var HasManyRelation = class extends Relation {
 		this.localKey = localKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue })).get();
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3529,15 +3607,22 @@ var HasManyThroughRelation = class extends Relation {
 		this.secondLocalKey = secondLocalKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		const keys = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.firstKey]: localValue } })).map((row) => row[this.secondLocalKey]);
+		return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: keys } }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		const keys = (await this.related.getDelegate(this.throughDelegate).findMany({ where: { [this.firstKey]: localValue } })).map((row) => row[this.secondLocalKey]);
-		if (keys.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: keys } })).get();
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3549,22 +3634,28 @@ var HasManyThroughRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var HasOneRelation = class extends Relation {
+var HasOneRelation = class extends SingleResultRelation {
 	constructor(parent, related, foreignKey, localKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.foreignKey = foreignKey;
 		this.localKey = localKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		return this.applyConstraint(this.related.query().where({ [this.foreignKey]: localValue })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3577,11 +3668,9 @@ var HasOneRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var HasOneThroughRelation = class extends Relation {
+var HasOneThroughRelation = class extends SingleResultRelation {
 	constructor(parent, related, throughDelegate, firstKey, secondKey, localKey, secondLocalKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.throughDelegate = throughDelegate;
 		this.firstKey = firstKey;
 		this.secondKey = secondKey;
@@ -3589,15 +3678,23 @@ var HasOneThroughRelation = class extends Relation {
 		this.secondLocalKey = secondLocalKey;
 	}
 	/**
+	* Build the relationship query.
+	*
+	* @returns
+	*/
+	async getQuery() {
+		const localValue = this.parent.getAttribute(this.localKey);
+		const intermediate = await this.related.getDelegate(this.throughDelegate).findFirst({ where: { [this.firstKey]: localValue } });
+		if (!intermediate) return this.applyConstraint(this.related.query().where({ [this.secondKey]: { in: [] } }));
+		return this.applyConstraint(this.related.query().where({ [this.secondKey]: intermediate[this.secondLocalKey] }));
+	}
+	/**
 	* Fetches the related models for this relationship.
 	* 
 	* @returns 
 	*/
 	async getResults() {
-		const localValue = this.parent.getAttribute(this.localKey);
-		const intermediate = await this.related.getDelegate(this.throughDelegate).findFirst({ where: { [this.firstKey]: localValue } });
-		if (!intermediate) return null;
-		return this.applyConstraint(this.related.query().where({ [this.secondKey]: intermediate[this.secondLocalKey] })).first();
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3618,17 +3715,25 @@ var MorphManyRelation = class extends Relation {
 		this.localKey = localKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const id = this.parent.getAttribute(this.localKey);
 		const type = this.parent.constructor.name;
 		return this.applyConstraint(this.related.query().where({
 			[`${this.morphName}Id`]: id,
 			[`${this.morphName}Type`]: type
-		})).get();
+		}));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return (await this.getQuery()).get();
 	}
 };
 
@@ -3640,26 +3745,32 @@ var MorphManyRelation = class extends Relation {
 * @author Legacy (3m1n3nc3)
 * @since 0.1.0
 */
-var MorphOneRelation = class extends Relation {
+var MorphOneRelation = class extends SingleResultRelation {
 	constructor(parent, related, morphName, localKey) {
-		super();
-		this.parent = parent;
-		this.related = related;
+		super(parent, related);
 		this.morphName = morphName;
 		this.localKey = localKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const id = this.parent.getAttribute(this.localKey);
 		const type = this.parent.constructor.name;
 		return this.applyConstraint(this.related.query().where({
 			[`${this.morphName}Id`]: id,
 			[`${this.morphName}Type`]: type
-		})).first();
+		}));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return await (await this.getQuery()).first() ?? this.resolveDefaultResult();
 	}
 };
 
@@ -3683,19 +3794,26 @@ var MorphToManyRelation = class extends Relation {
 		this.relatedKey = relatedKey;
 	}
 	/**
-	* Fetches the related models for this relationship.
-	* 
-	* @returns 
+	* Build the relationship query.
+	*
+	* @returns
 	*/
-	async getResults() {
+	async getQuery() {
 		const parentValue = this.parent.getAttribute(this.parentKey);
 		const morphType = this.parent.constructor.name;
 		const ids = (await this.related.getDelegate(this.throughDelegate).findMany({ where: {
 			[`${this.morphName}Id`]: parentValue,
 			[`${this.morphName}Type`]: morphType
 		} })).map((row) => row[this.relatedPivotKey]);
-		if (ids.length === 0) return new ArkormCollection([]);
-		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } })).get();
+		return this.applyConstraint(this.related.query().where({ [this.relatedKey]: { in: ids } }));
+	}
+	/**
+	* Fetches the related models for this relationship.
+	* 
+	* @returns 
+	*/
+	async getResults() {
+		return (await this.getQuery()).get();
 	}
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkormx",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Modern TypeScript-first ORM for Node.js.",
   "keywords": [
     "orm",