@ballistix.digital/odata-query-builder 0.2.0 → 0.3.0

package/README.md

@@ -6,12 +6,30 @@ A typed, fluent builder for the OData v4 query strings that
 It builds a **query string**. It does not fetch, and it does not know about the
 `_embedded` / `_page` response envelope. It has **zero runtime dependencies**.
 
-Full documentation lives in [`docs/`](docs/README.md) — the developer entry
-point, with a module map and one page per pipeline stage.
+Full documentation lives in [`docs/`](docs/index.md): a
+[guide](docs/guide/index.md) for a developer who uses the package, and
+[maintainer pages](docs/maintainer/index.md) for a developer who changes it.
+
+## Install
+
+```sh
+npm i @ballistix.digital/odata-query-builder
+```
+
+It needs Node 20 or newer, and TypeScript 5.9, 6.0 or 7.0.
+
+## Example
 
 ```ts
-import { odataQuery, ProjectStatusEnum } from '@ballistix.digital/odata-query-builder';
+import { odataQuery } from '@ballistix.digital/odata-query-builder';
+
+enum ProjectStatusEnum {
+  DRAFT = 'draft',
+  ACTIVE = 'active',
+  ARCHIVED = 'archived',
+}
 
+// ProjectDto is your own DTO type. Getting started shows its shape.
 const query = odataQuery<ProjectDto>()
   .filter((v, o) =>
     o.and(
@@ -26,8 +44,12 @@ const query = odataQuery<ProjectDto>()
   .top(25)
   .count()
   .toQueryString();
+// $filter=archived eq false and status in ('draft','active') and children/any(a:a/priority ge 2)&$select=id,name,status&$expand=parent($select=name;$expand=owner($select=fullName))&$orderby=name desc&$top=25&$count=true
 ```
 
+[Getting started](docs/guide/getting-started.md#the-one-assumption-_embedded)
+prints the `ProjectDto` shape the examples use.
+
 ## What makes it typed
 
 The scope a `filter()` callback receives is derived from the DTO type alone:
@@ -56,112 +78,28 @@ v.year.eq(v.date.asDate().year());
 // year eq year(date)
 ```
 
-## The surface
-
-| Verb | Emits |
-| --- | --- |
-| `filter(cb)` | `$filter`; repeated calls AND together |
-| `search(term, cols)` | `$search` + the mandatory `$searchColumns` |
-| `select(...)` | `$select`; the own columns plus embedded leaf paths; omit it and nothing is narrowed, at any depth |
-| `expand.<rel>(cb?)` | `$expand`, with nested `$filter`/`$select`/`$expand` |
-| `orderBy(key, direction?)` | `$orderby`, ascending by default; `key` may be a to-one relation path or an embedded leaf path |
-| `top` / `skip` / `count` | `$top` / `$skip` / `$count=true` |
-| `toQueryString()` | the whole string, already URL-safe |
-| `toParams()` | the same options as a map, escaping undone |
-
-`odataItem<T>()` is the single-row variant: `$select` and `$expand` only.
-
-An embedded object column (a DTO property that is a plain object) reads as a
-namespace of columns, so `v.address.geo.lat` filters, selects and sorts as
-`address/geo/lat`.
-
-Inside a filter callback the second argument carries the combinators —
-`o.and`, `o.or`, `o.not`, `o.now`, `o.maxdatetime`, `o.mindatetime`, `o.raw` —
-and the same functions are importable. A single predicate needs no combinator.
-
-`isNull()` and `isNotNull()` are how you compare against null; `eq(null)` is a
-compile error, because "no filter" and "is null" must not look alike.
-
-## Filtered expansions
-
-From `@ballistix.digital/typeorm-extensions` 3.8.0 the server accepts a nested
-`$filter`, so the nested chain has `filter()`:
-
-```ts
-odataQuery<ProjectDto>()
-  .expand.children((c) => c.filter((x) => x.priority.ge(2023)).select('priority'));
-// $expand=children($filter=priority ge 2023;$select=priority)
-```
-
-The filter narrows the EXPANSION only. Every root row still comes back: a row
-whose collection matched nothing arrives with an empty collection, a to-one
-expansion that fails the filter arrives as null, and `$count` and the paging
-window are unchanged.
-
-`$orderby`, `$top`, `$skip`, `$count` and `$levels` inside `$expand` are still
-rejected by the server, so they are still absent from the nested chain.
-
 ## Escaping
 
 `toQueryString()` is already URL-safe. **Do not** run `encodeURIComponent` over
-it — that turns `%25` into `%2525`. Six rules, each measured against the
-server's own parser:
-
-| In a literal | Emitted as | Why |
-| --- | --- | --- |
-| `'` | `''` | the OData string escape |
-| `%` | `%25` | the query string is percent-decoded before parsing |
-| `+` | `%2B` | a bare `+` is read as whitespace |
-| `&` | `%26` | a bare `&` starts another query option |
-| `#` | `%23` | a bare `#` starts the URL fragment |
-| space | `%20` | only inside literals; the spaces between tokens stay raw |
+it — that turns `%25` into `%2525`.
+[The escape rules](docs/guide/sending-the-query.md#the-escape-rules) list what
+each literal character becomes.
 
 Use `toParams()` when the caller has its own serialiser (`URLSearchParams`,
 ky): it hands back the raw values so that serialiser's own encoding is the only
 one applied.
 
-## Tests
+## Documentation
 
-The suite is split into five Jest projects, each runnable on its own.
+- [Getting started](docs/guide/getting-started.md) — install, the `_embedded` assumption, a first query.
+- [Querying](docs/guide/querying.md) — every verb, the `expand` namespace, filtered expansions and `odataItem`.
+- [Filtering](docs/guide/filtering.md) — operators, functions, lambdas, dates, `cast` and the combinators.
+- [Sending the query](docs/guide/sending-the-query.md) — `toQueryString()` or `toParams()`, and the escape rules.
+- [Errors](docs/guide/errors.md) — what the builder throws and how to catch it.
+- [Cookbook](docs/guide/cookbook.md) — twelve call shapes with their strings.
 
-| Command | Needs Postgres | What it covers |
-| --- | --- | --- |
-| `npm run test:unit` | no | Golden strings for the whole emission surface, the combination matrix, `toParams()` equivalence, every runtime guard, and a cross-check that feeds each emitted string through the real server-side parser |
-| `npm run test:types` | no | The compile gate: every `.ok` fixture compiles clean and every `// @errorline TSxxxx` marker in an `.err` fixture errors with that code, on TypeScript 5.9, 6.0 and 7.0 |
-| `npm run test:packaging` | no | `npm pack --dry-run`: only `dist/**` ships |
-| `npm run test:integration` | yes | The emitted strings executed against real Postgres through the published `typeorm-extensions`, asserting rows |
-| `npm run test:e2e` | yes | The same strings sent to a real NestJS app, asserting the response envelope and the 400 body for each rejected construct |
-| `npm run test:coverage` | no | `unit`, with the coverage gate |
-| `npm test` | yes | `npm run build`, then all five projects |
+## Contributing
 
-```bash
-npm run db:up     # postgres:17-alpine on port 5557
-npm test
-npm run db:down
-```
-
-The database-backed tiers skip themselves with a clear message when the
-sidecar is down. See [Testing](docs/testing.md) for the shared test setup,
-the fixtures, the seed data, and how to add a test to each tier.
-
-## Layout
-
-```
-src/index.ts                   the public API: odataQuery, odataItem, and every exported type
-src/module/common/             what two or more areas share; it imports nothing
-src/module/common/domain/      ExceptionCode, ExceptionDetail, Scalar and Unwrap
-src/module/common/exception/   QueryBuilderException
-src/module/common/util/        escape.util — the one literal-escaping mechanism
-src/module/query/              the builder: three stages, QueryChainService, shared state, the two error classes
-src/module/query/domain/       QueryState, and one folder per stage: chain/, filter/
-src/module/query/exception/    InvalidFilterError, ReservedNameError
-src/module/query/service/      queryChain.service.ts (QueryChainService) and one facade per stage: filter/, emit/
-src/module/query/util/         pure-function folders for two stages: filter/, emit/
-test/unit/         no database
-test/types/        the compile gate, three TypeScript versions
-test/integration/  executes queries against seeded Postgres
-test/e2e/          a real NestJS app, the response envelope, the rejected constructs
-test/packaging/    tarball guard
-test/fixtures/     DTO twins, entities, the seed data
-test/support/      shared test setup: datasource, app, env
-```
+To run the tests and find your way around the source, read
+[Conventions](docs/maintainer/conventions.md#run-the-repository-locally) and
+[Testing](docs/maintainer/testing.md#the-five-tiers).

package/dist/module/query/service/queryChain.service.d.ts

@@ -33,8 +33,8 @@ export declare class QueryChainService {
      * `QueryChainService` and not the handler.
      *
      * `chain.expand.parent((parent) => parent.select('name'))` gives
-     * `$expand=parent($select=name)`. See docs/query/index.md, How `Proxy` works
-     * here.
+     * `$expand=parent($select=name)`. See docs/maintainer/architecture.md, How
+     * `Proxy` works here.
      */
     get expand(): unknown;
     select(...keys: string[]): this;

package/dist/module/query/service/queryChain.service.js

@@ -21,8 +21,8 @@ class QueryChainService {
      * `QueryChainService` and not the handler.
      *
      * `chain.expand.parent((parent) => parent.select('name'))` gives
-     * `$expand=parent($select=name)`. See docs/query/index.md, How `Proxy` works
-     * here.
+     * `$expand=parent($select=name)`. See docs/maintainer/architecture.md, How
+     * `Proxy` works here.
      */
     get expand() {
         return new Proxy(Object.create(null), {

package/dist/module/query/util/filter/scopeProxy.util.d.ts

@@ -12,7 +12,7 @@ export declare const nodeOf: (value: unknown) => ExpressionNode | undefined;
  * still reaches the trap.
  *
  * `v.name.eq('x')` on `rootScope()` gives `name eq 'x'`. See
- * docs/query/index.md, How `Proxy` works here.
+ * docs/maintainer/architecture.md, How `Proxy` works here.
  */
 export declare const createMember: (node: ExpressionNode, parent?: ExpressionNode, name?: string) => any;
 /**

package/dist/module/query/util/filter/scopeProxy.util.js

@@ -50,7 +50,7 @@ exports.nodeOf = nodeOf;
  * still reaches the trap.
  *
  * `v.name.eq('x')` on `rootScope()` gives `name eq 'x'`. See
- * docs/query/index.md, How `Proxy` works here.
+ * docs/maintainer/architecture.md, How `Proxy` works here.
  */
 const createMember = (node, parent, name) => 
 // The target is never invoked: the `apply` trap owns every call. It only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ballistix.digital/odata-query-builder",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed, fluent OData v4 query-string builder for the dialect @ballistix.digital/typeorm-extensions serves.",
   "license": "MIT",
   "repository": {