@kadirgun/lucid-bravo 0.0.1 → 0.0.2

package/README.md

@@ -49,19 +49,48 @@ export default class UserBravo extends LucidBravo<typeof User> {
 }
 ```
 
-Use the class in a controller or service with the query builder and request params:
+You can create a Bravo instance in a few different ways, depending on whether you already have a Lucid query builder or want Bravo to create one from the model declared in the subclass:
 
 ```ts
-const bravo = new UserBravo(User.query(), {
-  sort: { field: 'name', order: 'asc' },
-  include: ['posts'],
+const bravoA = new UserBravo({
   limit: 20,
-  page: 1,
-  name: 'Alice',
 })
 
-const users = await bravo.apply()
-const result = await bravo.paginate()
+const bravoB = new UserBravo(
+  {
+    limit: 20,
+  },
+  User.query()
+)
+
+const bravoC = UserBravo.build(
+  {
+    limit: 20,
+  },
+  User.query()
+)
+
+// default query and params
+const bravoD = UserBravo.build()
+const bravoE = new UserBravo()
+```
+
+Use the class in a controller with `bravoValidator` to validate the common query params before passing them to Bravo:
+
+```ts
+import type { HttpContext } from '@adonisjs/core/http'
+import User from '#models/user'
+import UserBravo from '#bravos/user_bravo'
+import { bravoValidator } from '@kadirgun/lucid-bravo/validators'
+
+export default class UsersController {
+  public async index({ request }: HttpContext) {
+    const params = await request.validateUsing(bravoValidator)
+    const bravo = new UserBravo(params, User.query())
+
+    return bravo.paginate()
+  }
+}
 ```
 
 ## Query params
@@ -80,7 +109,8 @@ For example, `first_name` maps to a `firstName()` method.
 
 - `LucidBravo` expects to run inside an active HTTP context.
 - Only relations returned by `getAllowedIncludes()` are preloaded.
-- If you want request validation, create a Vine schema in your app that matches the same query shape.
+- For the common query shape, you can reuse `bravoValidator` from `@kadirgun/lucid-bravo/validators`.
+- If you also need model-specific filters, add a separate Vine schema in your app and merge the validated values before creating the Bravo instance.
 
 ## Authorization
 

package/build/index.d.ts

@@ -1,2 +1,3 @@
 export { configure } from './configure.ts';
 export { stubsRoot } from './stubs/main.ts';
+export { LucidBravo } from './src/lucid_bravo.ts';

package/build/index.js

@@ -1,4 +1,6 @@
 import { configure } from "./configure.js";
+import stringHelpers from "@adonisjs/core/helpers/string";
+import { HttpContext } from "@adonisjs/core/http";
 //#region stubs/main.ts
 /**
 * Path to the root directory where the stubs are stored. We use
@@ -6,4 +8,126 @@ import { configure } from "./configure.js";
 */
 const stubsRoot = import.meta.dirname;
 //#endregion
-export { configure, stubsRoot };
+//#region src/lucid_bravo.ts
+var LucidBravo = class {
+	$model;
+	$query;
+	$params;
+	$http;
+	$countQuery;
+	defaultLimit = 20;
+	defaultSort = null;
+	constructor(params, query) {
+		this.$params = params || {};
+		this.$http = HttpContext.getOrFail();
+		if (query) {
+			this.$model = query.model;
+			this.$query = query;
+			this.$countQuery = this.$query.clone();
+		}
+	}
+	static build(params, query) {
+		return new this(params, query);
+	}
+	resolveQuery() {
+		if (this.$query) return this.$query;
+		if (this.$model) {
+			this.$query = this.$model.query();
+			this.$countQuery = this.$query.clone();
+			return this.$query;
+		}
+		throw new Error("Either a query must be provided or $model must be set in the subclass");
+	}
+	/**
+	* Return a whitelist of sortable columns
+	*/
+	getSortable() {
+		return [];
+	}
+	/**
+	* Return a whitelist of allowed relations for preload include
+	*/
+	getAllowedIncludes() {
+		return [];
+	}
+	/**
+	* Main entry point to apply all filters, includes, sorting and pagination
+	*/
+	async apply() {
+		this.resolveQuery();
+		await this.applyFilters();
+		await this.applyIncludes();
+		await this.applySorting();
+		await this.applyPagination();
+		return this.$query;
+	}
+	async count() {
+		this.resolveQuery();
+		const result = await this.$countQuery.count("* as total").firstOrFail();
+		return Number(result.$extras.total);
+	}
+	async paginate() {
+		return {
+			items: await this.apply(),
+			total: await this.count()
+		};
+	}
+	/**
+	* Automatically call methods that match camelCase version of snake_case params
+	*/
+	async applyFilters() {
+		this.resolveQuery();
+		for (const [key, value] of Object.entries(this.$params)) {
+			if ([
+				"page",
+				"limit",
+				"sort"
+			].includes(key)) continue;
+			if (value === void 0 || value === null || value === "") continue;
+			const methodName = stringHelpers.camelCase(key);
+			if (!(methodName in this)) continue;
+			const method = this[methodName];
+			if (typeof method !== "function") throw new Error(`Expected ${methodName} to be a method on ${this.constructor.name}`);
+			await method.call(this, value);
+		}
+	}
+	/**
+	* Apply preload include relations based on allowlist
+	*/
+	async applyIncludes() {
+		const query = this.resolveQuery();
+		const includes = this.$params.include;
+		if (!Array.isArray(includes) || includes.length === 0) return;
+		const allowed = this.getAllowedIncludes();
+		for (const relation of includes) {
+			if (!allowed.includes(relation)) continue;
+			query.preload(relation);
+		}
+	}
+	/**
+	* Apply sorting based on sort[field] and sort[order] params
+	*/
+	async applySorting() {
+		const query = this.resolveQuery();
+		const sort = this.$params.sort;
+		const sortable = this.getSortable();
+		let field = sort?.field;
+		let order = sort?.order || "asc";
+		if (!field && this.defaultSort) {
+			field = this.defaultSort.field;
+			order = this.defaultSort.order;
+		}
+		if (field && sortable.includes(field)) query.orderBy(field, order);
+	}
+	/**
+	* Apply simple limit and offset pagination
+	*/
+	async applyPagination() {
+		const query = this.resolveQuery();
+		const limit = Number(this.$params.limit) || this.defaultLimit;
+		const offset = ((Number(this.$params.page) || 1) - 1) * limit;
+		if (limit > 0) query.limit(limit).offset(offset);
+	}
+};
+//#endregion
+export { LucidBravo, configure, stubsRoot };

package/build/src/lucid_bravo.d.ts

@@ -1,17 +1,18 @@
 import type { LucidModel, ModelAttributes, ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
 import type { BravoParams, BravoSortOption } from './types.ts';
 import { HttpContext } from '@adonisjs/core/http';
+import type { Constructor } from '@adonisjs/core/types/common';
 export declare abstract class LucidBravo<T extends LucidModel> {
+    protected $model?: T;
     protected $query: ModelQueryBuilderContract<T>;
     protected $params: BravoParams;
     protected $http: HttpContext;
     protected $countQuery: ModelQueryBuilderContract<T>;
     protected defaultLimit: number;
     protected defaultSort: BravoSortOption | null;
-    constructor(query: ModelQueryBuilderContract<T>, params: BravoParams);
-    static build<T extends LucidModel, B extends LucidBravo<T>>(this: {
-        new (query: ModelQueryBuilderContract<T>, params: BravoParams): B;
-    }, query: ModelQueryBuilderContract<T>, params: BravoParams): B;
+    constructor(params?: BravoParams, query?: ModelQueryBuilderContract<T>);
+    static build<T extends LucidModel, B extends LucidBravo<T>>(this: Constructor<B>, params?: BravoParams, query?: ModelQueryBuilderContract<T>): B;
+    protected resolveQuery(): ModelQueryBuilderContract<T, InstanceType<T>>;
     /**
      * Return a whitelist of sortable columns
      */

package/build/stubs/make/bravos/main.stub

@@ -8,10 +8,12 @@
   })
 }}}
 import { LucidBravo } from '@kadirgun/lucid-bravo'
-import type {{ entity.name }} from '{{ modelImportPath }}'
+import {{ entity.name }} from '{{ modelImportPath }}'
 import type { ModelAttributes } from '@adonisjs/lucid/types/model'
 
 export default class {{ modelName }}Bravo extends LucidBravo<typeof {{ entity.name }}> {
+  protected $model = {{ entity.name }}
+
   public override getSortable(): string[] {
     return []
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kadirgun/lucid-bravo",
   "description": "A powerful, fluent query builder for AdonisJS Lucid to handle filtering, sorting and pagination in a single flow",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -14,7 +14,16 @@
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
-    "./types": "./build/src/types.js"
+    "./types": "./build/src/types.js",
+    "./validators": "./build/validators.js",
+    "./commands": {
+      "import": "./build/commands/main.js",
+      "types": "./build/commands/main.d.ts"
+    },
+    "./commands/*": {
+      "import": "./build/commands/*.js",
+      "types": "./build/commands/*.d.ts"
+    }
   },
   "scripts": {
     "copy:templates": "copyfiles \"stubs/**/*.stub\" build",