laravel-query-builder-js 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rana Usman / Engage Platform
+
+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,388 @@
+# laravel-query-builder-js
+
+[![npm version](https://img.shields.io/npm/v/laravel-query-builder-js.svg)](https://www.npmjs.com/package/laravel-query-builder-js)
+[![CI](https://github.com/RanaUsman3131/laravel-query-builder-js/actions/workflows/ci.yml/badge.svg)](https://github.com/RanaUsman3131/laravel-query-builder-js/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/laravel-query-builder-js.svg)](./LICENSE)
+[![types](https://img.shields.io/npm/types/laravel-query-builder-js.svg)](https://www.npmjs.com/package/laravel-query-builder-js)
+
+A fluent, **framework-agnostic**, Laravel-style query builder for JavaScript & TypeScript.
+
+Compose `select`, `filter`, `sort`, `include` (eager-loaded relations) and pagination on the
+client, then serialise it into query params (or a query string) for your API. It has **no
+framework dependencies**, so the exact same code works in **React**, **Vue**, **Angular**,
+and **Node.js**.
+
+```ts
+const query = new QueryBuilder()
+  .where("state", "=", "Open")
+  .whereIn("type", ["Buyer", "Tenant"])
+  .sort({ createdAt: "desc" })
+  .paginate(1, 25);
+
+fetch("/api/leads?" + query.toQueryParams());
+```
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Framework usage](#framework-usage)
+  - [React](#react)
+  - [Vue 3](#vue-3)
+  - [Angular](#angular)
+  - [Plain fetch / Node](#plain-fetch--node)
+- [API reference](#api-reference)
+  - [Filtering](#filtering)
+  - [Grouped & nested conditions](#grouped--nested-conditions)
+  - [Selecting fields](#selecting-fields)
+  - [Sorting](#sorting)
+  - [Relations (include / withRelation)](#relations-include--withrelation)
+  - [Pagination](#pagination)
+  - [Serialisation](#serialisation)
+  - [Utilities](#utilities)
+  - [Operators](#operators)
+- [Serialised output shape](#serialised-output-shape)
+- [TypeScript](#typescript)
+- [Contributing & development](#contributing--development)
+- [Releasing](#releasing)
+- [License](#license)
+
+---
+
+## Features
+
+- 🔗 **Fluent, chainable API** — reads like a sentence.
+- 🧩 **Nested relations** — eager-load related resources with their own filters/sorts.
+- 🪺 **Grouped conditions** — build `(a OR b) AND c` with callbacks.
+- 🐍 **Automatic snake_case** — select fields and sort keys are snake_cased for the backend.
+- 📦 **ESM + CJS + types** — first-class TypeScript, works everywhere.
+- 🪶 **Tiny footprint** — one runtime dependency (`lodash`).
+- 🧪 **Well tested** — full unit-test suite.
+
+## Installation
+
+```bash
+npm install laravel-query-builder-js
+# or
+yarn add laravel-query-builder-js
+# or
+pnpm add laravel-query-builder-js
+```
+
+## Quick start
+
+```ts
+import { QueryBuilder } from "laravel-query-builder-js";
+
+const query = new QueryBuilder()
+  .select(["id", "firstName", "email"])
+  .where("state", "=", "Open")
+  .whereIn("type", ["Buyer", "Tenant"])
+  .sort({ createdAt: "desc" })
+  .paginate(1, 25);
+
+// As a Record<string, string> (great for axios `params`)
+query.toParams();
+// { select: '["id","first_name","email"]',
+//   filter: '{"and":[{"field":"state","op":"=","value":"Open"},{"field":"type","op":"in","value":["Buyer","Tenant"]}]}',
+//   sort: '{"created_at":"desc"}', page: 1, limit: 25, ... }
+
+// As a URL-encoded query string
+query.toQueryParams();
+// select=%5B...%5D&filter=%7B...%7D&sort=%7B...%7D&page=1&limit=25
+```
+
+## Framework usage
+
+The builder is plain TypeScript with zero framework coupling — import it the same way anywhere.
+
+### React
+
+```tsx
+import { useMemo } from "react";
+import { QueryBuilder } from "laravel-query-builder-js";
+
+function useLeads(status: string, page: number) {
+  const params = useMemo(
+    () =>
+      new QueryBuilder()
+        .where("state", "=", status)
+        .sort({ createdAt: "desc" })
+        .paginate(page, 20)
+        .toParams(),
+    [status, page]
+  );
+
+  return useQuery(["leads", params], () =>
+    fetch("/api/leads?" + new URLSearchParams(params)).then((r) => r.json())
+  );
+}
+```
+
+### Vue 3
+
+```ts
+import { computed } from "vue";
+import { QueryBuilder } from "laravel-query-builder-js";
+
+const status = ref("Open");
+
+const queryString = computed(() =>
+  new QueryBuilder().where("state", "=", status.value).paginate(1, 20).toQueryParams()
+);
+
+watchEffect(() => fetch(`/api/leads?${queryString.value}`));
+```
+
+### Angular
+
+```ts
+import { HttpClient } from "@angular/common/http";
+import { QueryBuilder } from "laravel-query-builder-js";
+
+@Injectable({ providedIn: "root" })
+export class LeadService {
+  constructor(private http: HttpClient) {}
+
+  getLeads(status: string, page = 1) {
+    const query = new QueryBuilder().where("state", "=", status).paginate(page, 20);
+    return this.http.get("/api/leads", { params: query.toParams() });
+  }
+}
+```
+
+### Plain fetch / Node
+
+```ts
+import { QueryBuilder } from "laravel-query-builder-js";
+
+const query = new QueryBuilder().whereIn("id", [1, 2, 3]);
+const res = await fetch(`https://api.example.com/users?${query.toQueryParams()}`);
+```
+
+## API reference
+
+Create a builder with the constructor or a static factory:
+
+```ts
+new QueryBuilder();
+QueryBuilder.create("lead"); // optional resource name
+QueryBuilder.new("lead"); // alias of create
+```
+
+Every mutating method returns `this`, so calls chain.
+
+### Filtering
+
+```ts
+q.where("state", "=", "Open"); // and: field = value
+q.where("age", ">", 18);
+q.orWhere("state", "=", "Pending"); // or: field = value
+q.whereIn("type", ["Buyer", "Tenant"]); // and: field IN [...]
+q.whereNull("deleted_at"); // and: field IS NULL
+q.whereNotNull("email"); // and: field IS NOT NULL
+```
+
+Adding a `where` with the same `field` **and** operator replaces the previous one (so you can
+safely re-apply a filter as inputs change):
+
+```ts
+q.where("state", "=", "Open").where("state", "=", "Closed");
+// -> only { field: "state", op: "=", value: "Closed" }
+```
+
+Remove clauses again:
+
+```ts
+q.clearWhere("currency"); // remove and-clause(s) on a field
+q.clearWhere("state", "="); // remove only the "=" clause on a field
+q.clearOrWhere("state"); // remove or-clause(s) on a field
+q.resetFilter(); // drop all filters
+```
+
+### Grouped & nested conditions
+
+Pass a callback to build a parenthesised group. The nested builder exposes the same
+`where` / `orWhere` methods:
+
+```ts
+// WHERE (division_id = 5 OR division_id IS NULL)
+q.where((sub) => sub.orWhere("division_id", "=", 5).orWhere("division_id", "null"));
+```
+
+Produces:
+
+```jsonc
+{ "and": [ { "or": [
+  { "field": "division_id", "op": "=", "value": 5 },
+  { "field": "division_id", "op": "null" }
+] } ] }
+```
+
+### Selecting fields
+
+Field names are converted to `snake_case` automatically:
+
+```ts
+q.select("firstName,lastName"); // -> ["first_name", "last_name"]
+q.select(["id", "createdAt"]); // -> ["id", "created_at"]
+q.addSelect(["extra_field"]); // append (raw, not snake_cased)
+q.resetSelect(); // clear
+```
+
+### Sorting
+
+Sort keys are snake_cased when serialised:
+
+```ts
+q.sort({ createdAt: "desc" }); // set (replaces)
+q.addSort({ name: "asc" }); // merge into existing
+q.resetSort(); // clear
+```
+
+### Relations (include / withRelation)
+
+Eager-load related resources with their own nested select / filter / sort / include using
+`withRelation`. Use the static `QueryBuilder.withRelation(name)` or the instance
+`q.withRelation(name)`.
+
+```ts
+const q = new QueryBuilder();
+
+q.addInclude(
+  q.withRelation("owner").where("status", "=", "Active").select(["id", "name"])
+);
+
+// Deeply nested relations
+q.addInclude([
+  q
+    .withRelation("portal_profiles")
+    .addInclude(q.withRelation("portal"))
+    .addInclude(q.withRelation("plugin_config")),
+]);
+
+// Aggregates on a relation
+q.addInclude(q.withRelation("deals").aggregate("count"));
+```
+
+Methods:
+
+- `include(rel | rel[])` — set the includes (replaces).
+- `addInclude(rel | rel[])` — append includes.
+- `resetInclude()` — clear.
+- `withRelation(name)` — start a nested relation builder (chainable, same API).
+- `.aggregate(value)` — set an aggregate on a relation.
+
+### Pagination
+
+```ts
+q.paginate(2, 25); // page = 2, limit = 25 (limit defaults to 15)
+q.fromPage(3); // set only the page
+q.page = 4; // accessor
+q.limit = 50; // accessor
+q.nextPage(); // increment page
+q.previousPage(); // decrement page
+q.resetPage(); // back to page 1
+```
+
+### Serialisation
+
+```ts
+q.toParams(); // Record<string, string> — for axios `params` / URLSearchParams
+q.toQueryParams(); // URL-encoded query string "a=...&b=..."
+q.getQuery(); // the raw internal query object
+```
+
+### Utilities
+
+```ts
+q.clone(); // independent deep copy
+q.addQueryBuilder(other); // merge another builder's select/filter/sort/include
+q.resetQuery(); // reset everything (and re-apply default pagination)
+```
+
+### Operators
+
+The `op` argument accepts any of:
+
+```
+%   has   >   <   =   !=   <>   >=   <=   null   not_null
+LIKE  like  BETWEEN  IN  in  has|=  has|<  has|>
+any  any|like  ANY  doesntHave  _like_
+```
+
+## Serialised output shape
+
+`toParams()` returns a `Record<string, string>` where each part is JSON-encoded:
+
+| Key         | When present                    | Example value                                      |
+| ----------- | ------------------------------- | -------------------------------------------------- |
+| `select`    | any select fields set           | `["id","first_name"]`                              |
+| `filter`    | any filter set                  | `{"and":[{"field":"state","op":"=","value":"Open"}]}` |
+| `sort`      | any sort set                    | `{"created_at":"desc"}` (keys snake_cased)         |
+| `include`   | any relation added              | `[{"name":"owner","filter":{...}}]`                |
+| `page`      | page is truthy                  | `2`                                                |
+| `limit`     | limit is truthy                 | `25`                                               |
+
+`toQueryParams()` returns the same information as a single URL-encoded string
+(`select=...&filter=...&sort=...&include=...&page=...&limit=...`).
+
+## TypeScript
+
+Fully typed. Public types are exported for building your own helpers:
+
+```ts
+import type {
+  Op,
+  Query,
+  QueryFilter,
+  QueryFilterGroup,
+  QueryInclude,
+  QuerySort,
+} from "laravel-query-builder-js";
+```
+
+## Contributing & development
+
+```bash
+git clone https://github.com/RanaUsman3131/laravel-query-builder-js.git
+cd laravel-query-builder-js
+npm install
+
+npm test           # run the unit tests once
+npm run test:watch # watch mode
+npm run typecheck  # tsc --noEmit
+npm run build      # bundle to dist/ (ESM + CJS + d.ts)
+```
+
+Please add tests for any new behaviour.
+
+## Releasing
+
+Releases are automated by GitHub Actions. Pushing a version tag builds, tests, publishes to
+npm (with [provenance](https://docs.npmjs.com/generating-provenance-statements)), and creates
+a GitHub Release.
+
+```bash
+# bump the version (updates package.json and creates the commit + tag)
+npm version patch        # or minor / major
+git push --follow-tags
+```
+
+Or tag manually — the tag **must** match `package.json`'s version:
+
+```bash
+git tag v1.2.3
+git push origin v1.2.3
+```
+
+**One-time setup:** add an npm **Automation** access token as the repository secret
+`NPM_TOKEN` (Settings → Secrets and variables → Actions). Provenance requires the repository
+to be **public**.
+
+## License
+
+[MIT](./LICENSE) © Rana Usman / Engage Platform