@codenameryuu/adonis-lucid-auto-preload 1.0.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright 2022 Oussama Benhamed, contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,315 @@
+# @codenameryuuu/adonis-lucid-auto-preload
+
+Auto-preload multiple relationships when retrieving Lucid models on Adonis JS 7.
+
+## Requirement
+
+* Adonis Js 7
+
+## Installation
+
+```bash
+yarn add @codenameryuuu/adonis-lucid-auto-preload
+```
+
+## Configure
+
+```bash
+node ace configure @codenameryuuu/adonis-lucid-auto-preload
+```
+
+## Usage
+
+Extend from the AutoPreload mixin and add a new `static $with` attribute.
+
+Adding `as const` to `$with` array will let the compiler know about your relationship names and infer them so you will have better intellisense when using `without` and `withOnly` methods.
+
+Relationships will be auto-preloaded for `find` , `all` and `paginate` queries.
+
+### **Using relation name**
+
+```typescript
+// App/Models/User.ts
+
+import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import { compose } from '@adonisjs/core/helpers'
+
+import { AutoPreload } from '@codenameryuuu/adonis-lucid-auto-preload'
+
+import Post from '#models/post'
+
+class User extends compose(BaseModel, AutoPreload) {
+  public static $with = ['posts'] as const
+
+  @column({ isPrimary: true })
+  public id: number
+
+  @column()
+  public email: string
+
+  @hasMany(() => Post)
+  public posts: HasMany<typeof Post>
+}
+```
+
+```typescript
+// App/Controllers/Http/UsersController.ts
+
+import User from '#models/user'
+
+export default class UsersController {
+  public async show() {
+    return await User.find(1) // ⬅ Returns user with posts attached.
+  }
+}
+```
+
+### **Using function**
+
+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
+
+import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
+import { compose } from '@adonisjs/core/helpers'
+
+import { AutoPreload } from '@codenameryuuu/adonis-lucid-auto-preload'
+
+import Post from '#models/post'
+
+class User extends compose(BaseModel, AutoPreload) {
+  public static $with = [
+    (query: ModelQueryBuilderContract<typeof this>) => {
+      query.preload('posts')
+    }
+  ]
+
+  @column({ isPrimary: true })
+  public id: number
+
+  @column()
+  public email: string
+
+  @hasMany(() => Post)
+  public posts: HasMany<typeof Post>
+}
+```
+
+```typescript
+// App/Controllers/Http/UsersController.ts
+
+import User from '#models/user'
+
+export default class UsersController {
+  public async show() {
+    return await User.find(1) // ⬅ Returns user with posts 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` .
+
+```typescript
+// App/Models/Post.ts
+
+import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+
+class Post extends BaseModel {
+  @column({ isPrimary: true })
+  public id: number
+
+  @column()
+  public userId: number
+
+  @column()
+  public title: string
+
+  @column()
+  public content: string
+
+  @hasMany(() => Comment)
+  public comments: HasMany<typeof Comment>
+}
+```
+
+```typescript
+// App/Models/User.ts
+
+import { BaseModel, column, hasMany, HasMany } from '@adonisjs/lucid/orm'
+import { compose } from '@adonisjs/core/helpers'
+
+import { AutoPreload } from '@codenameryuuu/adonis-lucid-auto-preload'
+
+import Post from '#models/post'
+
+class User extends compose(BaseModel, AutoPreload) {
+  public static $with = ['posts.comments'] as const
+
+  @column({ isPrimary: true })
+  public id: number
+
+  @column()
+  public email: string
+
+  @hasMany(() => Post)
+  public posts: HasMany<typeof Post>
+}
+```
+
+When retrieving a user, it will preload both `posts` and `comments` ( `comments` will be attached to their `posts` 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')
+    })
+  }
+]
+```
+
+## **Mixin methods**
+
+The `AutoPreload` mixin will add 3 methods to your models. We will explain all of them below.
+
+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 '@codenameryuuu/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
+
+import User from '#models/user'
+
+export default class UsersController {
+  public async show() {
+    return await User.without(['posts']).find(1) // ⬅ Returns user with profile and without posts.
+  }
+}
+```
+
+### **withOnly**
+
+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
+
+import User from '#models/user'
+
+export default class UsersController {
+  public async show() {
+    return await User.withOnly(['profile']).find(1) // ⬅ Returns user with profile and without posts.
+  }
+}
+```
+
+### **withoutAny**
+
+Exclude all relationships from being auto-preloaded.
+
+```typescript
+// App/Controllers/Http/UsersController.ts
+
+import User from '#models/user'
+
+export default class UsersController {
+  public async show() {
+    return await User.withoutAny().find(1) // ⬅ Returns user without profile and posts.
+  }
+}
+```
+
+> **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 '@codenameryuuu/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/codenameryuuu/adonis-lucid-auto-preload/issues). You can also take a look at the [contributing guide](https://github.com/codenameryuuu/adonis-lucid-auto-preload/blob/master/CONTRIBUTING.md).
+
+## License
+
+This project is [MIT](https://github.com/codenameryuuu/adonis-lucid-auto-preload/blob/master/LICENSE.md) licensed.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@codenameryuu/adonis-lucid-auto-preload",
+  "version": "1.0.0",
+  "description": "Auto-preload multiple relationships when retrieving Lucid models on Adonis JS 7",
+  "author": "codenameryuu",
+  "license": "MIT",
+  "homepage": "https://github.com/codenameryuu/adonis-lucid-auto-preload#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codenameryuu/adonis-lucid-auto-preload.git"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "keywords": [
+    "adonis",
+    "adonisjs",
+    "auto-preload"
+  ],
+  "scripts": {
+    "dev": "node ace serve --watch",
+    "build": "npm run clean && tsc",
+    "start": "node server.js",
+    "lint": "eslint . --ext=.ts",
+    "format": "prettier --write .",
+    "pretest": "npm run lint",
+    "test": "node -r @adonisjs/require-ts/build/register bin",
+    "clean": "del-cli build",
+    "copyfiles": "copyfiles \"templates/**/*.txt\" \"instructions.md\" build",
+    "compile": "npm run lint && npm run clean && tsc && npm run copyfiles",
+    "commit": "git-cz",
+    "release": "np --message=\"chore(release): %s\""
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^7.7.0",
+    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/eslint-config": "^3.0.0",
+    "@adonisjs/lucid": "^22.0.0",
+    "@adonisjs/prettier-config": "^1.4.5",
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/expect": "^3.0.7",
+    "@japa/expect-type": "^2.0.4",
+    "@japa/file-system": "^3.0.0",
+    "@japa/run-failed-tests": "^1.1.1",
+    "@japa/runner": "^5.3.0",
+    "@japa/snapshot": "^2.0.5",
+    "@japa/spec-reporter": "^1.3.3",
+    "@poppinss/dev-utils": "^2.0.3",
+    "@types/node": "^25.5.0",
+    "copyfiles": "^2.4.1",
+    "del-cli": "^5.0.0",
+    "eslint": "^10.0.2",
+    "prettier": "^3.8.1",
+    "sqlite3": "^5.0.11",
+    "typescript": "^5.3.3",
+    "youch": "^4.1.0"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/lucid": "^22.0.0"
+  },
+  "eslintConfig": {
+    "extends": "@adonisjs/eslint-config/package"
+  },
+  "eslintIgnore": [
+    "build"
+  ],
+  "prettier": "@adonisjs/prettier-config",
+  "publishConfig": {
+    "tag": "latest",
+    "access": "public"
+  },
+  "main": "./build/providers/AutoPreloadProvider.js",
+  "types": "./build/adonis-typings/index.d.ts",
+  "files": [
+    "build/adonis-typings",
+    "build/providers",
+    "build/src",
+    "build/instructions.md"
+  ]
+}