feat(preloader): add preloadOnce to preload a relationship only once

src/orm/preloader/index.ts

@@ -128,6 +128,18 @@ export class Preloader implements PreloaderContract<LucidRow> {
     return this.load(name, callback)
   }
 
+  /**
+   * Define a relationship to preload, but only if they are not
+   * already preloaded
+   */
+  preloadOnce(name: any): this {
+    if (!this.preloads[name]) {
+      return this.load(name)
+    }
+
+    return this
+  }
+
   /**
    * Toggle query debugging
    */

src/orm/query_builder/index.ts

@@ -652,6 +652,15 @@ export class ModelQueryBuilder
     return this
   }
 
+  /**
+   * Define a relationship to preload, but only if they are not
+   * already preloaded
+   */
+  preloadOnce(relationName: any): this {
+    this.preloader.preloadOnce(relationName)
+    return this
+  }
+
   /**
    * Perform update by incrementing value for a given column. Increments
    * can be clubbed with `update` as well

src/types/model.ts

@@ -42,6 +42,7 @@ import {
   WithAggregate,
   WithCount,
   PreloadWithoutCallback,
+  PreloadOnce,
 } from './relations.js'
 
 /**
@@ -481,6 +482,7 @@ export interface ModelQueryBuilderContract<Model extends LucidModel, Result = In
    * Define relationships to be preloaded
    */
   preload: Preload<InstanceType<Model>, this>
+  preloadOnce: PreloadOnce<InstanceType<Model>, this>
 
   /**
    * Aggregates

src/types/relations.ts

@@ -1065,6 +1065,9 @@ export interface PreloadWithoutCallback<Model extends LucidRow, Builder> {
   <Name extends ExtractModelRelations<Model>>(relation: Name): Builder
 }
 
+export interface PreloadOnce<Model extends LucidRow, Builder>
+  extends PreloadWithoutCallback<Model, Builder> {}
+
 /**
  * Shape of the preloader to preload relationships
  */
@@ -1074,6 +1077,7 @@ export interface PreloaderContract<Model extends LucidRow> {
 
   load: Preload<Model, this>
   preload: Preload<Model, this>
+  preloadOnce: PreloadOnce<Model, this>
 
   debug(debug: boolean): this
   sideload(values: ModelObject): this