@eienjs/adonisjs-api-query 0.1.0

package/build/src/exceptions/invalid_filter_query.d.ts

@@ -0,0 +1,7 @@
+import { InvalidQuery } from './invalid_query.js';
+export declare class InvalidFilterQuery extends InvalidQuery {
+    readonly unknownFilters: string[];
+    readonly allowedFilters: string[];
+    constructor(unknownFilters: string[], allowedFilters: string[]);
+    static filtersNotAllowed(unknownFilters: string[], allowedFilters: string[]): InvalidFilterQuery;
+}

package/build/src/exceptions/invalid_filter_value.d.ts

@@ -0,0 +1,4 @@
+import { Exception } from '@adonisjs/core/exceptions';
+export declare class InvalidFilterValue extends Exception {
+    static make(value: unknown): InvalidFilterValue;
+}

package/build/src/exceptions/invalid_include_query.d.ts

@@ -0,0 +1,7 @@
+import { InvalidQuery } from './invalid_query.js';
+export declare class InvalidIncludeQuery extends InvalidQuery {
+    readonly unknownIncludes: string[];
+    readonly allowedIncludes: string[];
+    constructor(unknownIncludes: string[], allowedIncludes: string[]);
+    static includesNotAllowed(unknownIncludes: string[], allowedIncludes: string[]): InvalidIncludeQuery;
+}

package/build/src/exceptions/invalid_query.d.ts

@@ -0,0 +1,4 @@
+import { Exception } from '@adonisjs/core/exceptions';
+export declare abstract class InvalidQuery extends Exception {
+    static readonly code = "E_INVALID_QUERY_EXCEPTION";
+}

package/build/src/exceptions/invalid_sort_query.d.ts

@@ -0,0 +1,7 @@
+import { InvalidQuery } from './invalid_query.js';
+export declare class InvalidSortQuery extends InvalidQuery {
+    readonly unknownSorts: string[];
+    readonly allowedSorts: string[];
+    constructor(unknownSorts: string[], allowedSorts: string[]);
+    static sortsNotAllowed(unknownSorts: string[], allowedSorts: string[]): InvalidSortQuery;
+}

package/build/src/exceptions/unknown_included_fields_query.d.ts

@@ -0,0 +1,5 @@
+import { InvalidQuery } from './invalid_query.js';
+export declare class UnknownIncludedFieldsQuery extends InvalidQuery {
+    readonly unknownFields: string[];
+    constructor(unknownFields: string[]);
+}

package/build/src/filters/filters_begin_with_strict.d.ts

@@ -0,0 +1,8 @@
+import { type DialectContract } from '@adonisjs/lucid/types/database';
+import { type LucidModel } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { type Filter } from '../types.js';
+import { FiltersPartial } from './filters_partial.js';
+export declare class FiltersBeginWithStrict<Model extends LucidModel> extends FiltersPartial<Model> implements Filter<Model> {
+    protected getWhereRawParameters(value: StrictValuesWithoutRaw, property: string, dialect: DialectContract['name']): [string, string[]];
+}

package/build/src/filters/filters_callback.d.ts

@@ -0,0 +1,7 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type Filter } from '../types.js';
+export declare class FiltersCallback<Model extends LucidModel> implements Filter<Model> {
+    private callback;
+    constructor(callback: (query: ModelQueryBuilderContract<Model>, value: unknown, property: string) => void);
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: unknown, property: string): void;
+}

package/build/src/filters/filters_ends_with_strict.d.ts

@@ -0,0 +1,8 @@
+import { type DialectContract } from '@adonisjs/lucid/types/database';
+import { type LucidModel } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { type Filter } from '../types.js';
+import { FiltersPartial } from './filters_partial.js';
+export declare class FiltersEndsWithStrict<Model extends LucidModel> extends FiltersPartial<Model> implements Filter<Model> {
+    protected getWhereRawParameters(value: StrictValuesWithoutRaw, property: string, dialect: DialectContract['name']): [string, string[]];
+}

package/build/src/filters/filters_exact.d.ts

@@ -0,0 +1,12 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { type Filter } from '../types.js';
+export declare class FiltersExact<Model extends LucidModel> implements Filter<Model> {
+    protected addRelationConstraint: boolean;
+    protected relationConstraints: string[];
+    constructor(addRelationConstraint?: boolean);
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string): void;
+    protected qualifyColumn(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, column: string): string;
+    protected isRelationProperty(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, property: string): boolean;
+    protected withRelationConstraint(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string): void;
+}

package/build/src/filters/filters_operator.d.ts

@@ -0,0 +1,14 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { FilterOperator } from '../enums/filter_operator.js';
+import { type Filter } from '../types.js';
+import { FiltersExact } from './filters_exact.js';
+export declare class FiltersOperator<Model extends LucidModel> extends FiltersExact<Model> implements Filter<Model> {
+    protected $addRelationConstraint: boolean;
+    protected $filterOperator: FilterOperator;
+    protected $boolean: 'and' | 'or';
+    constructor($addRelationConstraint: boolean, $filterOperator: FilterOperator, $boolean: 'and' | 'or');
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw, property: string): void;
+    protected getDynamicFilterOperator(value: string): FilterOperator;
+    protected removeDynamicFilterOperatorFromValue(value: string, filterOperator: FilterOperator): string;
+}

package/build/src/filters/filters_partial.d.ts

@@ -0,0 +1,12 @@
+import { type DialectContract } from '@adonisjs/lucid/types/database';
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { type Filter } from '../types.js';
+import { FiltersExact } from './filters_exact.js';
+export declare class FiltersPartial<Model extends LucidModel> extends FiltersExact<Model> implements Filter<Model> {
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string): void;
+    protected getDatabaseDialect(query: ModelQueryBuilderContract<Model, InstanceType<Model>>): DialectContract['name'];
+    protected getWhereRawParameters(value: StrictValuesWithoutRaw | null, property: string, dialect: DialectContract['name']): [string, string[]];
+    protected static escapeLike(value: string): string;
+    protected static maybeSpecifyEscapeChar(dialect: DialectContract['name']): string;
+}

package/build/src/filters/filters_trashed.d.ts

@@ -0,0 +1,6 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+import { type Filter } from '../types.js';
+export declare class FiltersTrashed<Model extends LucidModel> implements Filter<Model> {
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw, _property: string): void;
+}

package/build/src/includes/included_callback.d.ts

@@ -0,0 +1,8 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type ModelRelations } from '@adonisjs/lucid/types/relations';
+import { type Include } from '../types.js';
+export declare class IncludedCallback<ParentModel extends LucidModel, RelatedModel extends LucidModel> implements Include<ParentModel> {
+    readonly callback: (query: ModelRelations<RelatedModel, ParentModel>['builder'] | ModelRelations<RelatedModel, ParentModel>['subQuery']) => void;
+    constructor(callback: (query: ModelRelations<RelatedModel, ParentModel>['builder'] | ModelRelations<RelatedModel, ParentModel>['subQuery']) => void);
+    handle(query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, include: string): void;
+}

package/build/src/includes/included_count.d.ts

@@ -0,0 +1,5 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type Include } from '../types.js';
+export declare class IncludedCount<ParentModel extends LucidModel> implements Include<ParentModel> {
+    handle(query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, count: string): void;
+}

package/build/src/includes/included_relationship.d.ts

@@ -0,0 +1,9 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { Collection } from 'collect.js';
+import { type Include } from '../types.js';
+export declare class IncludedRelationship<ParentModel extends LucidModel> implements Include<ParentModel> {
+    static getIndividualRelationshipPathsFromInclude(include: string): Collection<string>;
+    getRequestedFieldsForRelatedTable?: (relationship: string) => string[];
+    handle(query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, relationship: string): void;
+    private buildNestedQuery;
+}

package/build/src/sorts/sorts_callback.d.ts

@@ -0,0 +1,7 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type Sort } from '../types.js';
+export declare class SortsCallback<Model extends LucidModel> implements Sort<Model> {
+    private readonly _callback;
+    constructor(_callback: (query: ModelQueryBuilderContract<Model>, descending: boolean, property: string) => void);
+    handle(query: ModelQueryBuilderContract<Model>, descending: boolean, property: string): void;
+}

package/build/src/sorts/sorts_field.d.ts

@@ -0,0 +1,5 @@
+import { type LucidModel, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type Sort } from '../types.js';
+export declare class SortsField<Model extends LucidModel> implements Sort<Model> {
+    handle(query: ModelQueryBuilderContract<Model>, descending: boolean, property: string): void;
+}

package/build/src/types.d.ts

@@ -0,0 +1,90 @@
+import { type LucidModel, type ModelAttributes, type ModelQueryBuilderContract } from '@adonisjs/lucid/types/model';
+import { type StrictValuesWithoutRaw } from '@adonisjs/lucid/types/querybuilder';
+export interface ApiQueryConfigParameters {
+    include?: string;
+    filter?: string;
+    sort?: string;
+    fields?: string;
+    append?: string;
+}
+export interface ApiQueryConfig {
+    /**
+     * By default the package will use the `include`, `filter`, `sort`
+     * and `fields` query parameters as described in the readme.
+     *
+     * You can customize these query string parameters here.
+     */
+    parameters?: ApiQueryConfigParameters;
+    /**
+     * Related model counts are included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsCount
+     */
+    countSuffix?: string;
+    /**
+     * Related model exists are included using the relationship name suffixed with this string.
+     * For example: GET /users?include=postsExists
+     */
+    existsSuffix?: string;
+    /**
+     * By default the package will throw an `InvalidFilterQuery` exception when a filter in the
+     * URL is not allowed in the `allowedFilters()` method.
+     */
+    disableInvalidFilterQueryException?: boolean;
+    /**
+     * By default the package will throw an `InvalidSortQuery` exception when a sort in the
+     * URL is not allowed in the `allowedSorts()` method.
+     */
+    disableInvalidSortQueryException?: boolean;
+    /**
+     * By default the package will throw an `InvalidIncludeQuery` exception when an include in the
+     * URL is not allowed in the `allowedIncludes()` method.
+     */
+    disableInvalidIncludesQueryException?: boolean;
+    /**
+     * By default, the package expects relationship names to be camel case plural when using fields[relationship].
+     * For example, fetching the id and name for a userOwner relation would look like this:
+     * GET /users?fields[userOwner]=id,name
+     *
+     * Set this to `true` if you don't want that and keep the requested relationship names as-is and allows you to
+     * request the fields using a snake case relationship name:
+     * GET /users?fields[user_owner]=id,name
+     */
+    convertRelationNamesToSnakeCasePlural?: boolean;
+    /**
+     * By default, the package expects relationship names to be camel case plural when using fields[relationship].
+     * For example, fetching the id and name for a userOwner relation would look like this:
+     * GET /users?fields[userOwner]=id,name
+     *
+     * Set this to one of `snake_case`, `camelCase` or `none` if you want to enable table name resolution in addition to the relation name resolution
+     * GET /users?include=top_orders&fields[orders]=id,name
+     */
+    convertRelationTableNameStrategy?: 'snake_case' | 'camelCase' | 'none' | false;
+    /**
+     * By default, the package expects the field names to match the database names
+     * For example, fetching the field named firstName would look like this:
+     * GET /users?fields=firstName
+     *
+     * Set this to `true` if you want to convert the firstName into first_name for the underlying query
+     */
+    convertFieldNamesToSnakeCase?: boolean;
+}
+export type ResolvedApiQueryConfig = Required<ApiQueryConfig> & {
+    parameters: Required<ApiQueryConfigParameters>;
+};
+export interface Sort<Model extends LucidModel> {
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, descending: boolean, property: string): void;
+}
+export interface Filter<Model extends LucidModel> {
+    handle(query: ModelQueryBuilderContract<Model, InstanceType<Model>>, value: StrictValuesWithoutRaw | null, property: string): void;
+}
+export interface Include<ParentModel extends LucidModel> {
+    handle(query: ModelQueryBuilderContract<ParentModel, InstanceType<ParentModel>>, include: string): void;
+}
+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 HintedString<KnownValues> = KnownValues extends string ? (string & {}) | KnownValues : never;

package/build/src/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/build/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/build/src/utils/helpers.d.ts

@@ -0,0 +1,3 @@
+export declare const substrReplace: (str: string, replace: string, start: number, length?: number) => string;
+export declare const strBeforeLast: (subject: string, search: string) => string;
+export declare const strAfterLast: (subject: string, search: string) => string;

package/build/stubs/main.d.ts

@@ -0,0 +1 @@
+export declare const stubsRoot: string;

package/package.json

@@ -0,0 +1,143 @@
+{
+  "name": "@eienjs/adonisjs-api-query",
+  "description": "Easily build Lucid queries from API requests",
+  "version": "0.1.0",
+  "type": "module",
+  "module": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/src/types.js",
+    "./api_query_provider": "./build/providers/api_query_provider.js"
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^7.8.2",
+    "@adonisjs/core": "^6.17.2",
+    "@adonisjs/lucid": "^21.6.0",
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@japa/assert": "^4.0.1",
+    "@japa/file-system": "^2.3.2",
+    "@japa/runner": "^4.2.0",
+    "@nodecfdi/eslint-config": "^3.0.0",
+    "@nodecfdi/prettier-config": "^1.4.1",
+    "@nodecfdi/tsconfig": "^1.7.4",
+    "@poppinss/hooks": "^7.2.5",
+    "@swc/core": "^1.11.8",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.13.9",
+    "adonis-lucid-soft-deletes": "^2.1.0",
+    "auto-changelog": "^2.5.0",
+    "better-sqlite3": "^11.8.1",
+    "c8": "^10.1.3",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.22.0",
+    "husky": "^9.1.7",
+    "is-in-ci": "^1.0.0",
+    "luxon": "^3.5.0",
+    "native-copyfiles": "^0.3.2",
+    "np": "^10.2.0",
+    "prettier": "^3.5.3",
+    "ts-node-maintained": "^10.9.5",
+    "tsup": "^8.4.0",
+    "typescript": "~5.7.3"
+  },
+  "dependencies": {
+    "collect.js": "^4.36.1"
+  },
+  "peerDependencies": {
+    "@adonisjs/core": "^6.17.2",
+    "@adonisjs/lucid": "^21.6.0"
+  },
+  "author": "Fernando Isidro <luffynando@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/eienjs/adonisjs-api-query",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eienjs/adonisjs-api-query.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eienjs/adonisjs-api-query/issues"
+  },
+  "keywords": [
+    "adonisjs",
+    "lucid",
+    "api",
+    "query",
+    "builder",
+    "filters",
+    "filter",
+    "sort",
+    "includes"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "exclude": [
+      "bin/**",
+      "tests/**"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "prettier": "@nodecfdi/prettier-config/pkg",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "auto-changelog": {
+    "template": "keepachangelog",
+    "hideCredit": true
+  },
+  "np": {
+    "message": "chore(release): :tada: %s",
+    "tag": "latest",
+    "branch": "main",
+    "testScript": "test"
+  },
+  "tsup": {
+    "entry": [
+      "index.ts",
+      "src/types.ts",
+      "providers/api_query_provider.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "dts": false,
+    "sourcemap": true,
+    "target": "esnext"
+  },
+  "scripts": {
+    "clean": "del-cli build",
+    "copy:templates": "copyfiles \"stubs/**/*.stub\" build --up 1",
+    "changelog": "auto-changelog -p && git add CHANGELOG.md",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "node --import ts-node-maintained/register/esm --enable-source-maps bin/test.ts",
+    "test:coverage": "c8 pnpm run test",
+    "tool:code": "pnpm run lint:check && pnpm run format:check && pnpm run typecheck",
+    "tool:build": "pnpm run tool:code && pnpm run test",
+    "prebuild": "pnpm run tool:code && pnpm run clean",
+    "build": "tsup-node --metafile && tsc --emitDeclarationOnly --declaration",
+    "postbuild": "pnpm run copy:templates",
+    "release": "np",
+    "version": "pnpm run build && pnpm run changelog"
+  }
+}