@ballistix.digital/odata-query-builder 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,167 @@
-# Temporary Holding Version
+# @ballistix.digital/odata-query-builder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed, fluent builder for the OData v4 query strings that
+`@ballistix.digital/typeorm-extensions` serves.
+
+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.
+
+```ts
+import { odataQuery, ProjectStatusEnum } from '@ballistix.digital/odata-query-builder';
+
+const query = odataQuery<ProjectDto>()
+  .filter((v, o) =>
+    o.and(
+      v.archived.isFalse(),
+      v.status.in([ProjectStatusEnum.DRAFT, ProjectStatusEnum.ACTIVE]),
+      v.children.any((a) => a.priority.ge(2)),
+    ),
+  )
+  .select('id', 'name', 'status')
+  .expand.parent((p) => p.select('name').expand.owner((u) => u.select('fullName')))
+  .orderBy('name', 'desc')
+  .top(25)
+  .count()
+  .toQueryString();
+```
+
+## What makes it typed
+
+The scope a `filter()` callback receives is derived from the DTO type alone:
+
+- an own scalar column becomes an expression typed by the column's own type, so
+  an enum column takes enum members and a number column refuses a string;
+- a `_embedded` to-one relation becomes a nested scope, emitted with `/`;
+- a `_embedded` to-many relation becomes a lambda namespace, so `any` and `all`
+  are the only things reachable on it — which is what the server accepts;
+- a primitive array column (`text[]`) becomes a lambda namespace over the
+  element.
+
+`expand.<relation>` lists exactly the relations `_embedded` declares. There is
+no code generation, no `$metadata` document, and no configuration: the DTO
+convention is `_embedded`, and the library assumes it.
+
+## A property read is never a method
+
+`v.year` is ambiguous at runtime: the `year()` function, or a column called
+`year`. Reading a property therefore never resolves a function. Read further
+from it and it was a path segment; call it and it was a function. Both roles
+work in one expression:
+
+```ts
+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 |
+
+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
+
+The suite is split into five Jest projects, each runnable on its own.
+
+| 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 |
+
+```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
+```

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one entry point of the package: the complete public API.
+ *
+ * Imports and re-exports only. Every name below is public — it keeps its name
+ * and signature across minor versions. A construct the server answers with a
+ * 400 is deliberately absent, so it is a compile error rather than a runtime
+ * failure.
+ */
+import { QueryBuilderExceptionCode } from './module/common/domain/exceptionCode.model';
+import type { ExceptionDetail } from './module/common/domain/exceptionDetail.model';
+import type { Scalar, Unwrap } from './module/common/domain/scalar.model';
+import { QueryBuilderException } from './module/common/exception/queryBuilder.exception';
+import type { Chain, QueryParams } from './module/query/domain/chain/chain.model';
+import type { EmbeddedPathKeys, ExpandKey, ExpandNamespace, FieldKey, OrderKey } from './module/query/domain/chain/expandNamespace.model';
+import type { ItemChain } from './module/query/domain/chain/itemChain.model';
+import type { ProjectChain } from './module/query/domain/chain/projectChain.model';
+import type { BooleanExpr } from './module/query/domain/filter/booleanExpr.model';
+import type { Castable, CastResult, EdmTarget } from './module/query/domain/filter/castable.model';
+import type { Comparable } from './module/query/domain/filter/comparable.model';
+import type { DateExpr, DateInput } from './module/query/domain/filter/dateExpr.model';
+import type { Node, Predicate } from './module/query/domain/filter/node.model';
+import type { NumberExpr } from './module/query/domain/filter/numberExpr.model';
+import type { Operators } from './module/query/domain/filter/operators.model';
+import type { EmbeddedObjectKeys, EmbeddedOf, ExprFor, LambdaNamespace, OwnKeys, PrimitiveArrayKeys, PrimitiveLambdaNamespace, Relation, ScalarFieldKeys, Scope, ToManyKeys, ToOneKeys } from './module/query/domain/filter/scope.model';
+import type { StringExpr } from './module/query/domain/filter/stringExpr.model';
+import { InvalidFilterError } from './module/query/exception/invalidFilter.exception';
+import { ReservedNameError } from './module/query/exception/reservedName.exception';
+import { and, maxdatetime, mindatetime, not, now, or, raw } from './module/query/service/filter/filter.facade';
+import { odataItem, odataQuery } from './module/query/service/queryChain.service';
+export { InvalidFilterError, QueryBuilderException, QueryBuilderExceptionCode, ReservedNameError, and, maxdatetime, mindatetime, not, now, odataItem, odataQuery, or, raw, };
+export type { BooleanExpr, CastResult, Castable, Chain, Comparable, DateExpr, DateInput, EdmTarget, EmbeddedObjectKeys, EmbeddedOf, EmbeddedPathKeys, ExceptionDetail, ExpandKey, ExpandNamespace, ExprFor, FieldKey, ItemChain, LambdaNamespace, Node, NumberExpr, Operators, OrderKey, OwnKeys, Predicate, PrimitiveArrayKeys, PrimitiveLambdaNamespace, ProjectChain, QueryParams, Relation, Scalar, ScalarFieldKeys, Scope, StringExpr, ToManyKeys, ToOneKeys, Unwrap, };

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * The one entry point of the package: the complete public API.
+ *
+ * Imports and re-exports only. Every name below is public — it keeps its name
+ * and signature across minor versions. A construct the server answers with a
+ * 400 is deliberately absent, so it is a compile error rather than a runtime
+ * failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.raw = exports.or = exports.odataQuery = exports.odataItem = exports.now = exports.not = exports.mindatetime = exports.maxdatetime = exports.and = exports.ReservedNameError = exports.QueryBuilderExceptionCode = exports.QueryBuilderException = exports.InvalidFilterError = void 0;
+const exceptionCode_model_1 = require("./module/common/domain/exceptionCode.model");
+Object.defineProperty(exports, "QueryBuilderExceptionCode", { enumerable: true, get: function () { return exceptionCode_model_1.QueryBuilderExceptionCode; } });
+const queryBuilder_exception_1 = require("./module/common/exception/queryBuilder.exception");
+Object.defineProperty(exports, "QueryBuilderException", { enumerable: true, get: function () { return queryBuilder_exception_1.QueryBuilderException; } });
+const invalidFilter_exception_1 = require("./module/query/exception/invalidFilter.exception");
+Object.defineProperty(exports, "InvalidFilterError", { enumerable: true, get: function () { return invalidFilter_exception_1.InvalidFilterError; } });
+const reservedName_exception_1 = require("./module/query/exception/reservedName.exception");
+Object.defineProperty(exports, "ReservedNameError", { enumerable: true, get: function () { return reservedName_exception_1.ReservedNameError; } });
+const filter_facade_1 = require("./module/query/service/filter/filter.facade");
+Object.defineProperty(exports, "and", { enumerable: true, get: function () { return filter_facade_1.and; } });
+Object.defineProperty(exports, "maxdatetime", { enumerable: true, get: function () { return filter_facade_1.maxdatetime; } });
+Object.defineProperty(exports, "mindatetime", { enumerable: true, get: function () { return filter_facade_1.mindatetime; } });
+Object.defineProperty(exports, "not", { enumerable: true, get: function () { return filter_facade_1.not; } });
+Object.defineProperty(exports, "now", { enumerable: true, get: function () { return filter_facade_1.now; } });
+Object.defineProperty(exports, "or", { enumerable: true, get: function () { return filter_facade_1.or; } });
+Object.defineProperty(exports, "raw", { enumerable: true, get: function () { return filter_facade_1.raw; } });
+const queryChain_service_1 = require("./module/query/service/queryChain.service");
+Object.defineProperty(exports, "odataItem", { enumerable: true, get: function () { return queryChain_service_1.odataItem; } });
+Object.defineProperty(exports, "odataQuery", { enumerable: true, get: function () { return queryChain_service_1.odataQuery; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,oFAAuF;AAiEtF,0GAjEQ,+CAAyB,OAiER;AA9D1B,6FAAyF;AA6DxF,sGA7DQ,8CAAqB,OA6DR;AAlBtB,8FAAsF;AAiBrF,mGAjBQ,4CAAkB,OAiBR;AAhBnB,4FAAoF;AAmBnF,kGAnBQ,0CAAiB,OAmBR;AAlBlB,+EAQqD;AAWpD,oFAlBA,mBAAG,OAkBA;AACH,4FAlBA,2BAAW,OAkBA;AACX,4FAlBA,2BAAW,OAkBA;AACX,oFAlBA,mBAAG,OAkBA;AACH,oFAlBA,mBAAG,OAkBA;AAGH,mFApBA,kBAAE,OAoBA;AACF,oFApBA,mBAAG,OAoBA;AAlBJ,kFAGmD;AAYlD,0FAdA,8BAAS,OAcA;AACT,2FAdA,+BAAU,OAcA"}

package/dist/module/common/domain/exceptionCode.model.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The stable machine-readable codes this library reports.
+ *
+ * A code never changes meaning: a caller may branch on it, and a value here is
+ * part of the public API. `QueryBuilderExceptionCode` is namespaced away from
+ * the server's own `ExceptionCode` on purpose — the two enums are unrelated
+ * even where a name looks similar.
+ */
+export declare enum QueryBuilderExceptionCode {
+    RESERVED_NAME = "RESERVED_NAME",
+    INVALID_FILTER = "INVALID_FILTER"
+}

package/dist/module/common/domain/exceptionCode.model.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * The stable machine-readable codes this library reports.
+ *
+ * A code never changes meaning: a caller may branch on it, and a value here is
+ * part of the public API. `QueryBuilderExceptionCode` is namespaced away from
+ * the server's own `ExceptionCode` on purpose — the two enums are unrelated
+ * even where a name looks similar.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilderExceptionCode = void 0;
+var QueryBuilderExceptionCode;
+(function (QueryBuilderExceptionCode) {
+    QueryBuilderExceptionCode["RESERVED_NAME"] = "RESERVED_NAME";
+    QueryBuilderExceptionCode["INVALID_FILTER"] = "INVALID_FILTER";
+})(QueryBuilderExceptionCode || (exports.QueryBuilderExceptionCode = QueryBuilderExceptionCode = {}));
+//# sourceMappingURL=exceptionCode.model.js.map

package/dist/module/common/domain/exceptionCode.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptionCode.model.js","sourceRoot":"","sources":["../../../../src/module/common/domain/exceptionCode.model.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAEH,IAAY,yBAGX;AAHD,WAAY,yBAAyB;IACpC,4DAA+B,CAAA;IAC/B,8DAAiC,CAAA;AAClC,CAAC,EAHW,yBAAyB,yCAAzB,yBAAyB,QAGpC"}

package/dist/module/common/domain/exceptionDetail.model.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The machine-readable payload behind an error message. One entry of
+ * `QueryBuilderException.errors` is one of these, and `errors[0].reason` is
+ * the exception message.
+ *
+ * Plain serializable data: an adapter can put the array straight into an HTTP
+ * response body.
+ */
+export interface ExceptionDetail {
+    /** What went wrong, in one sentence, for a human reading a log. */
+    reason: string;
+    /** The name, path or value the reason is about, where there is one. */
+    subject?: string;
+}

package/dist/module/common/domain/exceptionDetail.model.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * The machine-readable payload behind an error message. One entry of
+ * `QueryBuilderException.errors` is one of these, and `errors[0].reason` is
+ * the exception message.
+ *
+ * Plain serializable data: an adapter can put the array straight into an HTTP
+ * response body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=exceptionDetail.model.js.map

package/dist/module/common/domain/exceptionDetail.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptionDetail.model.js","sourceRoot":"","sources":["../../../../src/module/common/domain/exceptionDetail.model.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

package/dist/module/common/domain/scalar.model.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The two type primitives every other module reads a DTO with.
+ *
+ * They live in `common` because both the filter module (which turns a DTO into
+ * a filter scope) and the query module (which turns a DTO into a select/expand
+ * namespace) need the same answer to "is this a column or a relation".
+ *
+ * `Scalar` admits only the five shapes the dialect can compare, sort or
+ * select directly; an object or array field never matches it, so those two
+ * modules route it through `Unwrap` and the embedding types instead.
+ */
+/** A DTO property this dialect can compare, sort or select. */
+export type Scalar = string | number | boolean | bigint | Date;
+/** The element type of an array property; anything else is returned as-is. */
+export type Unwrap<T> = T extends readonly (infer U)[] ? U : T;

package/dist/module/common/domain/scalar.model.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * The two type primitives every other module reads a DTO with.
+ *
+ * They live in `common` because both the filter module (which turns a DTO into
+ * a filter scope) and the query module (which turns a DTO into a select/expand
+ * namespace) need the same answer to "is this a column or a relation".
+ *
+ * `Scalar` admits only the five shapes the dialect can compare, sort or
+ * select directly; an object or array field never matches it, so those two
+ * modules route it through `Unwrap` and the embedding types instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=scalar.model.js.map

package/dist/module/common/domain/scalar.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar.model.js","sourceRoot":"","sources":["../../../../src/module/common/domain/scalar.model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG"}

package/dist/module/common/exception/queryBuilder.exception.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The base of every error this library throws.
+ *
+ * It carries the same `{status, code, errors}` SHAPE
+ * `@ballistix.digital/typeorm-extensions` puts on its own errors — an
+ * HTTP-ish `status`, a stable machine-readable `code`, and a list of details —
+ * so a caller's existing handling of the server's errors (reading those three
+ * fields) also handles the builder's. It is field-compatible, not a shared
+ * type: that package exports its own, unrelated `LibraryException` and
+ * `ExceptionCode`, so this class is never an `instanceof` that one.
+ *
+ * The envelope lives in `common` because every area raises it. Nothing here
+ * depends on a framework, and nothing here depends on another area.
+ */
+import type { QueryBuilderExceptionCode } from '../domain/exceptionCode.model';
+import type { ExceptionDetail } from '../domain/exceptionDetail.model';
+export declare abstract class QueryBuilderException extends Error {
+    /** Suggested HTTP status for adapters. Always 400. */
+    readonly status: number;
+    /** The same value, under the name Nest and Axios both use. */
+    readonly statusCode: number;
+    /** Stable machine-readable code, e.g. "RESERVED_NAME". */
+    readonly code: QueryBuilderExceptionCode;
+    /** Every detail behind this error; `errors[0]` fills the message. */
+    readonly errors: ExceptionDetail[];
+    protected constructor(code: QueryBuilderExceptionCode, message: string, errors: ExceptionDetail[]);
+}

package/dist/module/common/exception/queryBuilder.exception.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * The base of every error this library throws.
+ *
+ * It carries the same `{status, code, errors}` SHAPE
+ * `@ballistix.digital/typeorm-extensions` puts on its own errors — an
+ * HTTP-ish `status`, a stable machine-readable `code`, and a list of details —
+ * so a caller's existing handling of the server's errors (reading those three
+ * fields) also handles the builder's. It is field-compatible, not a shared
+ * type: that package exports its own, unrelated `LibraryException` and
+ * `ExceptionCode`, so this class is never an `instanceof` that one.
+ *
+ * The envelope lives in `common` because every area raises it. Nothing here
+ * depends on a framework, and nothing here depends on another area.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueryBuilderException = void 0;
+class QueryBuilderException extends Error {
+    /** Suggested HTTP status for adapters. Always 400. */
+    status;
+    /** The same value, under the name Nest and Axios both use. */
+    statusCode;
+    /** Stable machine-readable code, e.g. "RESERVED_NAME". */
+    code;
+    /** Every detail behind this error; `errors[0]` fills the message. */
+    errors;
+    constructor(code, message, errors) {
+        super(message);
+        this.name = new.target.name;
+        this.status = 400;
+        this.statusCode = 400;
+        this.code = code;
+        this.errors = errors;
+    }
+}
+exports.QueryBuilderException = QueryBuilderException;
+//# sourceMappingURL=queryBuilder.exception.js.map

package/dist/module/common/exception/queryBuilder.exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryBuilder.exception.js","sourceRoot":"","sources":["../../../../src/module/common/exception/queryBuilder.exception.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAKH,MAAsB,qBAAsB,SAAQ,KAAK;IACxD,sDAAsD;IAC7C,MAAM,CAAS;IACxB,8DAA8D;IACrD,UAAU,CAAS;IAC5B,0DAA0D;IACjD,IAAI,CAA4B;IACzC,qEAAqE;IAC5D,MAAM,CAAoB;IAEnC,YACC,IAA+B,EAC/B,OAAe,EACf,MAAyB;QAEzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;QAClB,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAtBD,sDAsBC"}

package/dist/module/common/util/escape.util.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Literal escaping: the one mechanism that makes a value safe inside a query
+ * string. It sits in `common` because two areas need the same answer — filter
+ * quotes literals and search terms with it, and emit undoes its escapes for
+ * `toParams()`.
+ *
+ * These seven rules are EMITTER GUARANTEES, each one measured by feeding the
+ * emitted string back through the server's own parser and reading the literal
+ * that came out:
+ *
+ *   '   ->  ''     OData string escape. `name eq 'It''s'` parses to `It's`.
+ *   %   ->  %25    the query string is percent-DECODED before parsing, so a
+ *                  literal `a%20b` would arrive as `a b` unless the % is
+ *                  escaped first.
+ *   +   ->  %2B    the grammar reads a bare `+` as whitespace: `name eq 'a+b'`
+ *                  parses to the value `a b`. This is the rule that silently
+ *                  corrupts data if it is missing.
+ *   &   ->  %26    a bare `&` splits the query string into another option, so
+ *                  `name eq 'a&b'` is a 400, not a wrong value.
+ *   #   ->  %23    a bare `#` starts the URL fragment.
+ *   ' ' ->  %20    only inside literals; the spaces BETWEEN tokens stay raw so
+ *                  the query string is readable.
+ *   a C0 control code point (below 0x20) or DEL (0x7F)  ->  %XX
+ *                  a full WHATWG URL parse (the trip a caller's own HTTP
+ *                  client makes when it builds a request URL from the
+ *                  emitted string) deletes a raw tab, LF or CR from the query
+ *                  string outright, before any percent-decoding happens. A
+ *                  literal carrying one of those bytes raw would arrive at
+ *                  the server silently shortened.
+ *
+ * `%` is replaced first, otherwise the escapes introduced afterwards would be
+ * escaped again. The control-code pass runs after the other percent-escapes
+ * and walks the string by code point rather than by regex, so it never has to
+ * name an unprintable character inside a pattern.
+ *
+ * The output of `toQueryString()` is therefore already URL-safe. Do NOT run
+ * `encodeURIComponent` over it — that turns every `%25` into `%2525`.
+ */
+/** Every rule except the quote doubling, for values that are not quoted (`$search`). */
+export declare const escapeBareValue: (value: string) => string;
+/**
+ * Every rule: `escapeBareValue()`, then the quote doubling. No other rule adds
+ * or removes a quote, so the order does not change the result.
+ */
+export declare const escapeLiteral: (value: string) => string;
+export declare const quote: (value: string) => string;
+/**
+ * Undo the percent-escapes, for `toParams()`.
+ *
+ * A caller that hands the parts to `URLSearchParams` or ky runs its own
+ * encoder over each value, so the OData-safety escaping has to come off first
+ * or every `%25` ships as `%2525`. The OData quote doubling is NOT undone —
+ * that one belongs to the expression grammar, not to the transport.
+ */
+export declare const unescapeParamValue: (value: string) => string;

package/dist/module/common/util/escape.util.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Literal escaping: the one mechanism that makes a value safe inside a query
+ * string. It sits in `common` because two areas need the same answer — filter
+ * quotes literals and search terms with it, and emit undoes its escapes for
+ * `toParams()`.
+ *
+ * These seven rules are EMITTER GUARANTEES, each one measured by feeding the
+ * emitted string back through the server's own parser and reading the literal
+ * that came out:
+ *
+ *   '   ->  ''     OData string escape. `name eq 'It''s'` parses to `It's`.
+ *   %   ->  %25    the query string is percent-DECODED before parsing, so a
+ *                  literal `a%20b` would arrive as `a b` unless the % is
+ *                  escaped first.
+ *   +   ->  %2B    the grammar reads a bare `+` as whitespace: `name eq 'a+b'`
+ *                  parses to the value `a b`. This is the rule that silently
+ *                  corrupts data if it is missing.
+ *   &   ->  %26    a bare `&` splits the query string into another option, so
+ *                  `name eq 'a&b'` is a 400, not a wrong value.
+ *   #   ->  %23    a bare `#` starts the URL fragment.
+ *   ' ' ->  %20    only inside literals; the spaces BETWEEN tokens stay raw so
+ *                  the query string is readable.
+ *   a C0 control code point (below 0x20) or DEL (0x7F)  ->  %XX
+ *                  a full WHATWG URL parse (the trip a caller's own HTTP
+ *                  client makes when it builds a request URL from the
+ *                  emitted string) deletes a raw tab, LF or CR from the query
+ *                  string outright, before any percent-decoding happens. A
+ *                  literal carrying one of those bytes raw would arrive at
+ *                  the server silently shortened.
+ *
+ * `%` is replaced first, otherwise the escapes introduced afterwards would be
+ * escaped again. The control-code pass runs after the other percent-escapes
+ * and walks the string by code point rather than by regex, so it never has to
+ * name an unprintable character inside a pattern.
+ *
+ * The output of `toQueryString()` is therefore already URL-safe. Do NOT run
+ * `encodeURIComponent` over it — that turns every `%25` into `%2525`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unescapeParamValue = exports.quote = exports.escapeLiteral = exports.escapeBareValue = void 0;
+const encodeControlCharacters = (value) => Array.from(value)
+    .map((character) => {
+    const code = character.charCodeAt(0);
+    // A C0 control code (below 0x20) or DEL (0x7F).
+    return code < 0x20 || code === 0x7f
+        ? `%${code.toString(16).toUpperCase().padStart(2, '0')}`
+        : character;
+})
+    .join('');
+/** Every rule except the quote doubling, for values that are not quoted (`$search`). */
+const escapeBareValue = (value) => encodeControlCharacters(value
+    .replace(/%/g, '%25')
+    .replace(/\+/g, '%2B')
+    .replace(/&/g, '%26')
+    .replace(/#/g, '%23')
+    .replace(/ /g, '%20'));
+exports.escapeBareValue = escapeBareValue;
+/**
+ * Every rule: `escapeBareValue()`, then the quote doubling. No other rule adds
+ * or removes a quote, so the order does not change the result.
+ */
+const escapeLiteral = (value) => (0, exports.escapeBareValue)(value).replace(/'/g, "''");
+exports.escapeLiteral = escapeLiteral;
+const quote = (value) => `'${(0, exports.escapeLiteral)(value)}'`;
+exports.quote = quote;
+/**
+ * Undo the percent-escapes, for `toParams()`.
+ *
+ * A caller that hands the parts to `URLSearchParams` or ky runs its own
+ * encoder over each value, so the OData-safety escaping has to come off first
+ * or every `%25` ships as `%2525`. The OData quote doubling is NOT undone —
+ * that one belongs to the expression grammar, not to the transport.
+ */
+const unescapeParamValue = (value) => value
+    .replace(/%(0[0-9A-Fa-f]|1[0-9A-Fa-f]|7[Ff])/g, (_match, hexDigits) => String.fromCharCode(parseInt(hexDigits, 16)))
+    .replace(/%2B/g, '+')
+    .replace(/%26/g, '&')
+    .replace(/%23/g, '#')
+    .replace(/%20/g, ' ')
+    .replace(/%25/g, '%');
+exports.unescapeParamValue = unescapeParamValue;
+//# sourceMappingURL=escape.util.js.map

package/dist/module/common/util/escape.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape.util.js","sourceRoot":"","sources":["../../../../src/module/common/util/escape.util.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;;AAEH,MAAM,uBAAuB,GAAG,CAAC,KAAa,EAAU,EAAE,CACzD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;KACf,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;IAClB,MAAM,IAAI,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACrC,gDAAgD;IAChD,OAAO,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI;QAClC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;QACxD,CAAC,CAAC,SAAS,CAAC;AACd,CAAC,CAAC;KACD,IAAI,CAAC,EAAE,CAAC,CAAC;AAEZ,wFAAwF;AACjF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAU,EAAE,CACxD,uBAAuB,CACtB,KAAK;KACH,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;KACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;KACrB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;KACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;KACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CACtB,CAAC;AARU,QAAA,eAAe,mBAQzB;AAEH;;;GAGG;AACI,MAAM,aAAa,GAAG,CAAC,KAAa,EAAU,EAAE,CACtD,IAAA,uBAAe,EAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAD/B,QAAA,aAAa,iBACkB;AAErC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,IAAI,IAAA,qBAAa,EAAC,KAAK,CAAC,GAAG,CAAC;AAA/D,QAAA,KAAK,SAA0D;AAE5E;;;;;;;GAOG;AACI,MAAM,kBAAkB,GAAG,CAAC,KAAa,EAAU,EAAE,CAC3D,KAAK;KACH,OAAO,CACP,qCAAqC,EACrC,CAAC,MAAM,EAAE,SAAiB,EAAE,EAAE,CAC7B,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAC7C;KACA,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;KACpB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;KACpB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;KACpB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;KACpB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAXX,QAAA,kBAAkB,sBAWP"}

package/dist/module/query/domain/chain/chain.model.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The root chain: every system query option the dialect serves.
+ *
+ * The builder produces a query STRING. It does not fetch, and it does not know
+ * about the `_embedded` / `_page` response envelope.
+ */
+import type { Predicate } from '../filter/node.model';
+import type { Operators } from '../filter/operators.model';
+import type { Scope } from '../filter/scope.model';
+import type { StringExpr } from '../filter/stringExpr.model';
+import type { ExpandNamespace, FieldKey, OrderKey } from './expandNamespace.model';
+/** A flat `{ $option: value }` map, for a caller that serialises its own URL. */
+export type QueryParams = Record<string, string>;
+export interface Chain<T> {
+    readonly expand: ExpandNamespace<T, Chain<T>>;
+    select(...keys: FieldKey<T>[]): Chain<T>;
+    /** Repeated calls AND together. */
+    filter(build: (scope: Scope<T>, operators: Operators) => Predicate): Chain<T>;
+    /** `$search` + its mandatory `$searchColumns`, as one verb. */
+    search(term: string, columns: (scope: Scope<T>) => StringExpr | readonly StringExpr[]): Chain<T>;
+    /** Sorts on an own column, an embedded leaf, or a to-one relation path. */
+    orderBy(key: OrderKey<T>, direction?: 'asc' | 'desc'): Chain<T>;
+    top(count: number): Chain<T>;
+    skip(count: number): Chain<T>;
+    count(on?: boolean): Chain<T>;
+    /** The whole query string, already URL-safe. Never re-encode it. */
+    toQueryString(): string;
+    /**
+     * The same query as separate parts, with the transport escaping undone, for
+     * a caller that hands them to `URLSearchParams` or ky and lets that encode.
+     */
+    toParams(): QueryParams;
+}

package/dist/module/query/domain/chain/chain.model.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=chain.model.js.map

package/dist/module/query/domain/chain/chain.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.model.js","sourceRoot":"","sources":["../../../../../src/module/query/domain/chain/chain.model.ts"],"names":[],"mappings":""}