@codenameryuu/adonis-lucid-auto-preload 2.1.0 → 2.3.0

package/README.md

@@ -1,23 +1,35 @@
 # @codenameryuu/adonis-lucid-auto-preload
 
-Auto-preload multiple relationships when retrieving Lucid models on Adonis JS 7.
+Auto-preload (eager loading) multiple relationships when retrieving Lucid models on Adonis JS.
 
 ## Requirement
 
 * Adonis Js 7
+* Lucid 22 or higher
 
 ## Installation
 
+* Install the package
+
 ```bash
 yarn add @codenameryuu/adonis-lucid-auto-preload
 ```
 
-## Configure
+* Configure the package
 
 ```bash
 node ace configure @codenameryuu/adonis-lucid-auto-preload
 ```
 
+* Make sure to register the provider inside `adonisrc.ts` file.
+
+```typescript
+providers: [
+  // ...
+  () => import('@codenameryuu/adonis-lucid-auto-preload/provider'),
+],
+```
+
 ## Usage
 
 Extend from the AutoPreload mixin and add a new `static $with` attribute.
@@ -26,40 +38,50 @@ Adding `as const` to `$with` array will let the compiler know about your relatio
 
 Relationships will be auto-preloaded for `find` , `all` and `paginate` queries.
 
+**Note:** Relationships must be `belongsTo` , if you are using other relationship types, it may cause infinite loop.
+
 ### **Using relation name**
 
 ```typescript
-// App/Models/User.ts
+// App/Models/Product.ts
 
-import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
-import { compose } from '@adonisjs/core/helpers'
+import { BaseModel, column, belongsTo } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from "@adonisjs/lucid/types/relations";
+import { compose } from "@adonisjs/core/helpers";
 
-import { AutoPreload } from '@codenameryuu/adonis-lucid-auto-preload'
+import { AutoPreload } from "@codenameryuu/adonis-lucid-auto-preload";
 
-import Post from '#models/post'
+import ProductCategory from '#models/product-category'
 
-class User extends compose(BaseModel, AutoPreload) {
-  public static $with = ['posts'] as const
+class Product extends compose(BaseModel, AutoPreload) {
+  public static $with = ['productCategory'] as const
 
   @column({ isPrimary: true })
   public id: number
 
   @column()
-  public email: string
+  declare productCategoryId: number
 
-  @hasMany(() => Post)
-  public posts: HasMany<typeof Post>
+  @column()
+  declare name: string
+
+  @belongsTo(() => ProductCategory, {
+    localKey: "id",
+    foreignKey: "product_category_id",
+    serializeAs: "product_category",
+  })
+  declare productCategory: BelongsTo<typeof ProductCategory>;
 }
 ```
 
 ```typescript
-// App/Controllers/Http/UsersController.ts
+// App/Controllers/Http/ProductsController.ts
 
-import User from '#models/user'
+import Product from '#models/product'
 
-export default class UsersController {
+export default class ProductsController {
   public async show() {
-    return await User.find(1) // ⬅ Returns user with posts attached.
+    return await Product.find(1) // ⬅ Returns product with product category attached.
   }
 }
 ```
@@ -69,106 +91,131 @@ export default class UsersController {
 You can also use functions to auto-preload relationships. The function will receive the model query builder as the only argument.
 
 ```typescript
-// App/Models/User.ts
+// App/Models/Product.ts
 
-import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import { BaseModel, column, belongsTo } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from "@adonisjs/lucid/types/relations";
 import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
 import { compose } from '@adonisjs/core/helpers'
 
 import { AutoPreload } from '@codenameryuu/adonis-lucid-auto-preload'
 
-import Post from '#models/post'
+import ProductCategory from '#models/product-category'
 
-class User extends compose(BaseModel, AutoPreload) {
+class Product extends compose(BaseModel, AutoPreload) {
   public static $with = [
     (query: ModelQueryBuilderContract<typeof this>) => {
-      query.preload('posts')
+      query.preload('productCategory')
     }
   ]
 
   @column({ isPrimary: true })
-  public id: number
+  declare id: number
 
   @column()
-  public email: string
+  declare productCategoryId: number
 
-  @hasMany(() => Post)
-  public posts: HasMany<typeof Post>
+  @column()
+  declare name: string
+
+  @belongsTo(() => ProductCategory, {
+    localKey: "id",
+    foreignKey: "product_category_id",
+    serializeAs: "product_category",
+  })
+  declare productCategory: BelongsTo<typeof ProductCategory>;
 }
 ```
 
 ```typescript
-// App/Controllers/Http/UsersController.ts
+// App/Controllers/Http/ProductsController.ts
 
-import User from '#models/user'
+import Product from '#models/product'
 
-export default class UsersController {
+export default class ProductsController {
   public async show() {
-    return await User.find(1) // ⬅ Returns user with posts attached.
+    return await Product.find(1) // ⬅ Returns product with product category attached.
   }
 }
 ```
 
 ## Nested relationships
 
-You can auto-preload nested relationships using the dot "." between the parent model and the child model. In the following example, `User` -> hasMany -> `Post` -> hasMany -> `Comment` .
+You can auto-preload nested relationships using the dot "." between the parent model and the child model. In the following example, `Product` -> belongsTo -> `ProductCategory` -> belongsTo -> `User` .
 
 ```typescript
-// App/Models/Post.ts
+// App/Models/ProductCategory.ts
 
-import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import { BaseModel, column, belongsTo } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from "@adonisjs/lucid/types/relations";
+import { compose } from "@adonisjs/core/helpers";
 
-class Post extends BaseModel {
-  @column({ isPrimary: true })
-  public id: number
+import { AutoPreload } from "@codenameryuu/adonis-lucid-auto-preload";
 
-  @column()
-  public userId: number
+import User from '#models/user'
 
-  @column()
-  public title: string
+class ProductCategory extends compose(BaseModel, AutoPreload) {
+  public static $with = ['user'] as const
+
+  @column({ isPrimary: true })
+  declare id: number
 
   @column()
-  public content: string
+  declare userId: number
 
-  @hasMany(() => Comment)
-  public comments: HasMany<typeof Comment>
+  @column()
+  declare name: string
+
+  @belongsTo(() => User, {
+    localKey: "id",
+    foreignKey: "user_id",
+    serializeAs: "user",
+  })
+  declare user: BelongsTo<typeof User>;
 }
 ```
 
 ```typescript
-// App/Models/User.ts
+// App/Models/Product.ts
 
-import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import { BaseModel, column, belongsTo } from '@adonisjs/lucid/orm'
+import type { BelongsTo } from "@adonisjs/lucid/types/relations";
 import { compose } from '@adonisjs/core/helpers'
 
 import { AutoPreload } from '@codenameryuu/adonis-lucid-auto-preload'
 
-import Post from '#models/post'
+import ProductCategory from '#models/product-category'
 
-class User extends compose(BaseModel, AutoPreload) {
-  public static $with = ['posts.comments'] as const
+class Product extends compose(BaseModel, AutoPreload) {
+  public static $with = ['productCategory.user'] as const
 
   @column({ isPrimary: true })
-  public id: number
+  declare id: number
 
   @column()
-  public email: string
+  declare productCategoryId: number
 
-  @hasMany(() => Post)
-  public posts: HasMany<typeof Post>
+  @column()
+  declare name: string
+
+  @belongsTo(() => ProductCategory, {
+    localKey: "id",
+    foreignKey: "product_category_id",
+    serializeAs: "product_category",
+  })
+  declare productCategory: BelongsTo<typeof ProductCategory>;
 }
 ```
 
-When retrieving a user, it will preload both `posts` and `comments` ( `comments` will be attached to their `posts` parents objects).
+When retrieving a product, it will preload both `productCategory` and `user` ( `user` will be attached to their `productCategory` parents objects).
 
 You can also use functions to auto-preload nested relationships.
 
 ```typescript
 public static $with = [
   (query: ModelQueryBuilderContract<typeof this>) => {
-    query.preload('posts', (postsQuery) => {
-      postsQuery.preload('comments')
+    query.preload('productCategory', (productCategoryQuery) => {
+      productCategoryQuery.preload('user')
     })
   }
 ]
@@ -180,46 +227,18 @@ The `AutoPreload` mixin will add 3 methods to your models. We will explain all o
 
 We will use the following model for our methods examples.
 
-```typescript
-// App/Models/User.ts
-
-import { BaseModel, column, hasOne, HasOne, hasMany, HasMany } from '@adonisjs/lucid/orm'
-import { compose } from '@adonisjs/core/helpers'
-
-import { AutoPreload } from '@codenameryuu/adonis-lucid-auto-preload'
-
-import Profile from '#models/profile'
-import Post from '#models/post'
-
-class User extends compose(BaseModel, AutoPreload) {
-  public static $with = ['posts', 'profile'] as const
-
-  @column({ isPrimary: true })
-  public id: number
-
-  @column()
-  public email: string
-
-  @hasOne(() => Profile)
-  public profile: HasOne<typeof Profile>
-
-  @hasMany(() => Post)
-  public posts: HasMany<typeof Post>
-}
-```
-
 ### **without**
 
 This method takes an array of relationship names as the only argument. All specified relationships will not be auto-preloaded. You cannot specify relationships registered using functions.
 
 ```typescript
-// App/Controllers/Http/UsersController.ts
+// App/Controllers/Http/ProductsController.ts
 
-import User from '#models/user'
+import Product from '#models/product'
 
-export default class UsersController {
+export default class ProductsController {
   public async show() {
-    return await User.without(['posts']).find(1) // ⬅ Returns user with profile and without posts.
+    return await Product.without(['productCategory']).find(1) // ⬅ Returns product without product category.
   }
 }
 ```
@@ -229,13 +248,13 @@ export default class UsersController {
 This method takes an array of relationship names as the only argument. Only specified relationships will be auto-preloaded. You cannot specify relationships registered using functions.
 
 ```typescript
-// App/Controllers/Http/UsersController.ts
+// App/Controllers/Http/ProductsController.ts
 
-import User from '#models/user'
+import Product from '#models/product'
 
-export default class UsersController {
+export default class ProductsController {
   public async show() {
-    return await User.withOnly(['profile']).find(1) // ⬅ Returns user with profile and without posts.
+    return await Product.withOnly(['productCategory']).find(1) // ⬅ Returns product with product category.
   }
 }
 ```
@@ -245,70 +264,20 @@ export default class UsersController {
 Exclude all relationships from being auto-preloaded.
 
 ```typescript
-// App/Controllers/Http/UsersController.ts
+// App/Controllers/Http/ProductsController.ts
 
-import User from '#models/user'
+import Product from '#models/product'
 
-export default class UsersController {
+export default class ProductsController {
   public async show() {
-    return await User.withoutAny().find(1) // ⬅ Returns user without profile and posts.
+    return await Product.withoutAny().find(1) // ⬅ Returns product without product category.
   }
 }
 ```
 
 > **Note**
 >
-> You can chain other model methods with mixin methods. For example, `await User.withoutAny().query().paginate(1)`
-
-## **Limitations**
-
-* Consider the following scenario: `User` -> hasMany -> `Post` -> hasMany -> `Comments`. If you auto-preload `user` and `comments` from `Post` and you auto-preload `posts` from `User`, you will end-up in a infinite loop and your application will stop working.
-
-## **Route model binding**
-
-When using route model binding, you cannot use `without` , `withOnly` and `withoutAny` methods in your controller. But, you can make use of [findForRequest](https://github.com/adonisjs/route-model-binding#change-lookup-logic) method.
-
-```typescript
-// App/Models/User.ts
-
-import { BaseModel, column, hasOne, HasOne, hasMany, HasMany } from '@adonisjs/lucid/orm'
-import { compose } from '@adonisjs/core/helpers'
-
-import { AutoPreload } from '@codenameryuu/adonis-lucid-auto-preload'
-
-import Profile from '#models/profile'
-import Post from '#models/post'
-
-class User extends compose(BaseModel, AutoPreload) {
-  public static $with = ['posts', 'profile'] as const
-
-  @column({ isPrimary: true })
-  public id: number
-
-  @column()
-  public email: string
-
-  @hasOne(() => Profile)
-  public profile: HasOne<typeof Profile>
-
-  @hasMany(() => Post)
-  public posts: HasMany<typeof Post>
-
-  public static findForRequest(ctx, param, value) {
-    const lookupKey = param.lookupKey === '$primaryKey' ? 'id' : param.lookupKey
-
-    return this
-      .without(['posts']) // ⬅ Do not auto-preload posts when using route model binding.
-      .query()
-      .where(lookupKey, value)
-      .firstOrFail()
-  }
-}
-```
-
-## Contributing
-
-Contributions, issues and feature requests are welcome!<br />Feel free to check [issues page](https://github.com/codenameryuu/adonis-lucid-auto-preload/issues). You can also take a look at the [contributing guide](https://github.com/codenameryuu/adonis-lucid-auto-preload/blob/master/CONTRIBUTING.md).
+> You can chain other model methods with mixin methods. For example, `await Product.withoutAny().query().paginate(1)`
 
 ## License
 

package/build/src/mixins/auto_preload.d.ts

@@ -65,6 +65,7 @@ export declare function AutoPreload<T extends NormalizeConstructor<LucidModel>>(
      * List of relationships to auto-preload.
      */
     $with: ReadonlyArray<PreloadEntry>;
+    boot(): void;
     beforeFindHook(query: ModelQueryBuilderContract<any, any>): void;
     beforeFetchHook(query: ModelQueryBuilderContract<any, any>): void;
     beforePaginateHook(queries: any): void;
@@ -114,7 +115,6 @@ export declare function AutoPreload<T extends NormalizeConstructor<LucidModel>>(
         <Model extends LucidModel>(this: Model, name: string): import("@adonisjs/lucid/types/relations").RelationshipsContract;
     };
     $defineProperty: <Model extends LucidModel, Prop extends keyof Model>(this: Model, propertyName: Prop, defaultValue: Model[Prop], strategy: "inherit" | "define" | ((value: Model[Prop]) => Model[Prop])) => void;
-    boot: () => void;
     before: {
         <Model extends LucidModel, Event extends "find" | "fetch">(this: Model, event: Event, handler: import("@adonisjs/lucid/types/model").HooksHandler<ModelQueryBuilderContract<Model>, Event>): void;
         <Model extends LucidModel>(this: Model, event: "paginate", handler: import("@adonisjs/lucid/types/model").HooksHandler<[ModelQueryBuilderContract<Model>, ModelQueryBuilderContract<Model>], "paginate">): void;

package/build/src/mixins/auto_preload.js

@@ -1,10 +1,22 @@
-import { beforeFetch, beforeFind, beforePaginate } from '@adonisjs/lucid/orm';
 export function AutoPreload(superclass) {
     class AutoPreloadModel extends superclass {
         /**
          * List of relationships to auto-preload.
          */
         static $with = [];
+        static boot() {
+            super.boot();
+            // `compose()` introduces an intermediate class. Depending on how Lucid
+            // handles boot flags, we might see `booted` as inherited and skip hook
+            // registration. Track it per subclass instead.
+            if (this.$autoPreloadHooksRegistered)
+                return;
+            this.$autoPreloadHooksRegistered = true;
+            // Register hooks on the actual model subclass.
+            this.before('find', this.beforeFindHook.bind(this));
+            this.before('fetch', this.beforeFetchHook.bind(this));
+            this.before('paginate', this.beforePaginateHook.bind(this));
+        }
         static beforeFindHook(query) {
             this.applyAutoPreload(query);
         }
@@ -72,10 +84,5 @@ export function AutoPreload(superclass) {
             return query;
         }
     }
-    // Apply Lucid hooks decorators without using `@decorator` syntax
-    // (some package tsconfigs disable the decorator syntax).
-    beforeFind()(AutoPreloadModel, 'beforeFindHook');
-    beforeFetch()(AutoPreloadModel, 'beforeFetchHook');
-    beforePaginate()(AutoPreloadModel, 'beforePaginateHook');
     return AutoPreloadModel;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codenameryuu/adonis-lucid-auto-preload",
-  "version": "2.1.0",
-  "description": "Auto-preload multiple relationships when retrieving Lucid models on Adonis JS 7",
+  "version": "2.3.0",
+  "description": "Auto-preload (eager loading) multiple relationships when retrieving Lucid models on Adonis JS",
   "author": "codenameryuu",
   "license": "MIT",
   "homepage": "https://github.com/codenameryuu/adonis-lucid-auto-preload#readme",

package/build/commands/index.d.ts

@@ -1,2 +0,0 @@
-declare const _default: never[];
-export default _default;

package/build/commands/index.js

@@ -1,10 +0,0 @@
-/*
-|--------------------------------------------------------------------------
-| Exporting an array of commands
-|--------------------------------------------------------------------------
-|
-| This package currently ships without Ace commands. Keep the command
-| index in place and export an empty array to satisfy the expected API.
-|
-*/
-export default [];