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

test/orm/model_belongs_to.spec.ts

@@ -864,6 +864,42 @@ test.group('Model | BelongsTo | preload', (group) => {
     assert.equal(profiles[0].user.id, profiles[0].userId)
   })
 
+  test('preload relationship once', async ({ assert, fs }) => {
+    const app = new AppFactory().create(fs.baseUrl, () => {})
+    await app.init()
+    const db = getDb()
+    const adapter = ormAdapter(db)
+    const BaseModel = getBaseModel(adapter)
+    class User extends BaseModel {
+      @column({ isPrimary: true })
+      declare id: number
+    }
+
+    class Profile extends BaseModel {
+      @column()
+      declare userId: number
+
+      @belongsTo(() => User)
+      declare user: BelongsTo<typeof User>
+    }
+
+    await db.insertQuery().table('users').insert({ username: 'virk' })
+    await db.insertQuery().table('profiles').insert({ display_name: 'Hvirk', user_id: 1 })
+
+    Profile.boot()
+
+    let callbackCalled = false
+
+    const profiles = await Profile.query()
+      .preload('user', () => {
+        callbackCalled = true
+      })
+      .preloadOnce('user')
+    assert.lengthOf(profiles, 1)
+    assert.equal(profiles[0].user.id, profiles[0].userId)
+    assert.isTrue(callbackCalled)
+  })
+
   test('set property value to null when no preload rows were found', async ({ assert, fs }) => {
     const app = new AppFactory().create(fs.baseUrl, () => {})
     await app.init()