@eienjs/adonisjs-api-query 2.0.0 → 3.0.0

package/build/src/validation/schema_builder.js

@@ -0,0 +1,38 @@
+import { resolveVine } from "./vine_resolver.js";
+import app from "@adonisjs/core/services/app";
+import { RuntimeException } from "@adonisjs/core/exceptions";
+// src/validation/schema_builder.ts
+const isVineValidator = (rules) => {
+	return typeof rules?.validate === "function";
+};
+const isVineObject = (rules) => {
+	return typeof rules.getProperties === "function";
+};
+/**
+* Filters are omitted from the URL most of the time, so every filter rule is made
+* optional while keeping its type and constraints when the value is present.
+*/
+const toOptional = (rule) => {
+	const schema = rule;
+	return typeof schema.optional === "function" ? schema.optional() : rule;
+};
+const buildQueryValidator = async (rules, filterRules = {}) => {
+	if (isVineValidator(rules)) return rules;
+	const vine = await resolveVine();
+	const filterKey = app.config.get("apiquery.parameters.filter", "filter");
+	const filterProperties = Object.fromEntries(Object.entries(filterRules).map(([name, rule]) => [name, toOptional(rule)]));
+	const hasFilterRules = Object.keys(filterProperties).length > 0;
+	if (rules && isVineObject(rules)) {
+		const properties = rules.getProperties();
+		if (!hasFilterRules || Object.hasOwn(properties, filterKey)) return vine.create(rules);
+		return vine.create({
+			...properties,
+			[filterKey]: vine.object(filterProperties).optional()
+		});
+	}
+	const properties = { ...rules };
+	if (hasFilterRules && !Object.hasOwn(properties, filterKey)) properties[filterKey] = vine.object(filterProperties).optional();
+	if (Object.keys(properties).length === 0) throw new RuntimeException("No validation rules defined for the API query request");
+	return vine.create(properties);
+};
+export { buildQueryValidator };

package/build/src/validation/vine_resolver.js

@@ -0,0 +1,13 @@
+import { VineNotInstalledException } from "../exceptions/vine_not_installed.js";
+// src/validation/vine_resolver.ts
+let cachedVine;
+const resolveVine = async () => {
+	if (cachedVine) return cachedVine;
+	try {
+		cachedVine = (await import("@vinejs/vine")).default;
+		return cachedVine;
+	} catch {
+		throw new VineNotInstalledException();
+	}
+};
+export { resolveVine };

package/build/stubs/main.d.ts

@@ -1,4 +1 @@
-//#region stubs/main.d.ts
-declare const stubsRoot: string;
-//#endregion
-export { stubsRoot };
+export declare const stubsRoot: string;

package/build/stubs/main.js

@@ -1,4 +1,3 @@
-//#region stubs/main.ts
+// stubs/main.ts
 const stubsRoot = import.meta.dirname;
-//#endregion
 export { stubsRoot };

package/build/types.d.ts

@@ -1,15 +1,28 @@
-import { LucidModel, ModelAttributes, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
+import { AllowedInclude } from "./src/allowed_include.js";
+import { AllowedSort } from "./src/allowed_sort.js";
+import { ApiQueryBuilderRequest } from "./src/api_query_builder_request.js";
+import { BaseFilterable } from "./src/base_filterable.js";
+import { AllowedFilter } from "./src/allowed_filter.js";
+import { HttpRequest } from "@adonisjs/core/http";
+import { ExtractScopes, LucidModel, ModelAttributes, ModelQueryBuilderContract } from "@adonisjs/lucid/types/model";
 import { StrictValuesWithoutRaw } from "@adonisjs/lucid/types/querybuilder";
-
-//#region src/types.d.ts
-interface ApiQueryConfigParameters {
+import { SchemaTypes } from "@vinejs/vine/types";
+import { ExtractModelRelations } from "@adonisjs/lucid/types/relations";
+import { Vine, VineObject } from "@vinejs/vine";
+export type QueryValidator = ReturnType<Vine['create']>;
+/**
+ * Validation rules accepted for an API query request: a compiled `vine.create(...)`,
+ * a `vine.object(...)` schema, or a literal object of Vine schemas.
+ */
+export type ValidationRules = QueryValidator | VineObject<Record<string, SchemaTypes>, unknown, unknown, unknown> | Record<string, SchemaTypes>;
+export interface ApiQueryConfigParameters {
   include?: string;
   filter?: string;
   sort?: string;
   fields?: string;
   append?: string;
 }
-interface ApiQueryConfig {
+export interface ApiQueryConfig {
   /**
    * By default the package will use the `include`, `filter`, `sort`
    * and `fields` query parameters as described in the readme.
@@ -69,23 +82,35 @@ interface ApiQueryConfig {
    * Set this to `true` if you want to convert the firstName into first_name for the underlying query
    */
   convertFieldNamesToSnakeCase?: boolean;
+  /**
+   * By default, the package will automatically validate the request before query execution
+   * when validation rules are configured.
+   *
+   * Set this to `false` if you prefer manual validation via `validate()`.
+   */
+  autoValidate?: boolean;
 }
-type ResolvedApiQueryConfig = Required<ApiQueryConfig> & {
+export type ResolvedApiQueryConfig = Required<ApiQueryConfig> & {
   parameters: Required<ApiQueryConfigParameters>;
 };
-type EnumType<T> = T[keyof T];
-interface Sort<Model extends LucidModel> {
-  handle: (query: ModelQueryBuilderContract<Model, InstanceType<Model>>, isDescending: boolean, property: string) => void;
+export type EnumType<T> = T[keyof T];
+export interface Sort<Model extends LucidModel> {
+  handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, isDescending: boolean, property: string): void;
 }
-interface Filter<Model extends LucidModel> {
-  handle: (query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string) => void;
+export interface Filter<Model extends LucidModel> {
+  handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string): void;
 }
-interface Include<ParentModel extends LucidModel> {
-  handle: (query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, include: string) => void;
+export interface Include<ParentModel extends LucidModel> {
+  handle(query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, include: string): void;
 }
-type ExtractKeys<T> = T extends object ? { [K in keyof T & string]: K }[keyof T & string] : never;
-type ExtractKeysWithSort<T> = T extends object ? { [K in keyof T & string]: `-${K}` }[keyof T & string] : never;
-type SortUnionKeyParams<Model extends LucidModel> = ExtractKeys<ModelAttributes<InstanceType<Model>>> | ExtractKeysWithSort<ModelAttributes<InstanceType<Model>>>;
-type HintedString<KnownValues> = KnownValues extends string ? (string & {}) | KnownValues : never;
-//#endregion
-export { ApiQueryConfig, ApiQueryConfigParameters, EnumType, ExtractKeys, ExtractKeysWithSort, Filter, HintedString, Include, ResolvedApiQueryConfig, Sort, SortUnionKeyParams };
+export type ExtractKeys<T> = T extends object ? { [K in keyof T & string]: K; }[keyof T & string] : never;
+export type ExtractKeysWithSort<T> = T extends object ? { [K in keyof T & string]: `-${K}`; }[keyof T & string] : never;
+export type SortUnionKeyParams<Model extends LucidModel> = ExtractKeys<ModelAttributes<InstanceType<Model>>> | ExtractKeysWithSort<ModelAttributes<InstanceType<Model>>>;
+export type ScopeUnionKeyParams<Model extends LucidModel> = [keyof ExtractScopes<Model>] extends [never] ? string : HintedString<keyof ExtractScopes<Model>>;
+export type HintedString<KnownValues> = KnownValues extends string ? (string & {}) | KnownValues : never;
+export type FilterableConstructor<Model extends LucidModel = LucidModel> = new (request?: HttpRequest | ApiQueryBuilderRequest) => BaseFilterable<Model>;
+export type FilterableThunk<Model extends LucidModel = LucidModel> = () => FilterableConstructor<Model>;
+export type FilterableTarget<Model extends LucidModel = LucidModel> = FilterableConstructor<Model> | FilterableThunk<Model>;
+export type FilterItem<Model extends LucidModel = LucidModel> = AllowedFilter<Model> | HintedString<ExtractKeys<ModelAttributes<InstanceType<Model>>>> | (string & {});
+export type SortItem<Model extends LucidModel = LucidModel> = AllowedSort<Model> | HintedString<SortUnionKeyParams<Model>> | (string & {});
+export type IncludeItem<Model extends LucidModel = LucidModel> = AllowedInclude<Model> | AllowedInclude<Model>[] | HintedString<ExtractModelRelations<InstanceType<Model>>> | (string & {});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eienjs/adonisjs-api-query",
   "type": "module",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Easily build Lucid queries from API requests",
   "author": "Fernando Isidro <luffynando@gmail.com>",
   "license": "MIT",
@@ -40,45 +40,47 @@
   "peerDependencies": {
     "@adonisjs/assembler": "^8.4.0",
     "@adonisjs/core": "^7.3.4",
-    "@adonisjs/lucid": "^22.4.2"
+    "@adonisjs/lucid": "^22.4.2",
+    "@vinejs/vine": ">=4.4.0"
   },
   "peerDependenciesMeta": {
     "@adonisjs/assembler": {
       "optional": true
+    },
+    "@vinejs/vine": {
+      "optional": true
     }
   },
-  "dependencies": {
-    "collect.js": "^4.36.1"
-  },
+  "dependencies": {},
   "devDependencies": {
-    "@adonisjs/assembler": "^8.4.0",
-    "@adonisjs/core": "^7.3.4",
+    "@adonisjs/assembler": "^8.6.0",
+    "@adonisjs/core": "^7.6.0",
     "@adonisjs/eslint-plugin": "^2.2.2",
     "@adonisjs/lucid": "^22.4.2",
     "@adonisjs/tsconfig": "^2.0.0",
-    "@codenameryuu/adonis-lucid-soft-deletes": "^2.0.3",
-    "@commitlint/cli": "^21.1.0",
-    "@commitlint/config-conventional": "^21.1.0",
-    "@eienjs/eslint-config": "^2.1.2",
+    "@commitlint/cli": "^21.2.4",
+    "@commitlint/config-conventional": "^21.2.4",
+    "@eienjs/adonisjs-soft-deletes": "^1.0.1",
+    "@eienjs/eslint-config": "^2.3.1",
     "@japa/assert": "^4.2.0",
     "@japa/file-system": "^3.0.0",
-    "@japa/runner": "^5.3.0",
-    "@poppinss/hooks": "^7.3.0",
-    "@poppinss/ts-exec": "^1.4.4",
-    "@types/luxon": "^3.7.2",
-    "@types/node": "^24.13.2",
-    "auto-changelog": "^2.6.0",
-    "better-sqlite3": "^12.11.1",
-    "c8": "^11.0.0",
+    "@japa/runner": "^5.4.0",
+    "@poppinss/hooks": "^7.3.1",
+    "@poppinss/ts-exec": "^1.5.1",
+    "@types/luxon": "^3.7.6",
+    "@types/node": "^26.6.6",
+    "@vinejs/vine": "^4.4.0",
+    "auto-changelog": "^2.7.0",
+    "better-sqlite3": "^13.0.3",
+    "c8": "^12.0.0",
     "enforce-unique": "^1.3.0",
-    "eslint": "^10.6.0",
-    "eslint-plugin-erasable-syntax-only": "^0.4.2",
+    "eslint": "^10.13.0",
+    "eslint-plugin-erasable-syntax-only": "^0.7.2",
     "husky": "^9.1.7",
     "is-in-ci": "^2.0.0",
     "luxon": "^3.7.2",
-    "release-it": "^20.2.1",
-    "tsdown": "^0.22.3",
-    "tsdown-stale-guard": "^0.1.2",
+    "release-it": "^21.1.1",
+    "tsdown": "^0.23.3",
     "typescript": "^6.0.3"
   },
   "c8": {