@ddd-ts-kit/http 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,389 @@
-# Temporary Holding Version
+# @ddd-ts-kit/http
 
-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.
+Declare a route once, without a framework. Mount it on Express 5, Fastify 5 or NestJS, and
+generate the OpenAPI 3.1 contract from the same declaration.
+
+Every adapter goes through one pipeline (`executeRoute`): validation, handler, error mapping.
+The behaviour is therefore the same on the three frameworks, and one test suite proves it.
+
+## Declare
+
+```ts
+import { z } from 'zod';
+import { defineRoute, defineRoutes } from '@ddd-ts-kit/http';
+import { zodSchema } from '@ddd-ts-kit/validation/zod';
+
+const order = zodSchema(z.object({ id: z.string(), total: z.number() }), { io: 'output' });
+
+export const orderRoutes = (orders: OrderQueries) =>
+  defineRoutes(
+    defineRoute(
+      {
+        method: 'GET',
+        path: '/orders/:orderId',
+        operationId: 'getOrder',
+        summary: 'Read an order',
+        tags: ['orders'],
+        request: { params: zodSchema(z.object({ orderId: z.string().uuid() })) },
+        responses: { 200: { description: 'The order.', body: order } },
+        errors: ['NOT_FOUND'],
+        security: ['bearer'],
+      },
+      async ({ params, context }) => ({
+        status: 200, // must be a declared status, and the body must match its schema
+        body: await orders.byId(params.orderId, context.principal),
+      }),
+    ),
+  );
+```
+
+- `params`, `query`, `headers` and `body` are typed from the schemas. Any `Schema` of
+  `@ddd-ts-kit/validation` works (zod, class-validator, Standard Schema).
+- Paths are literal segments and `:name` parameters, the form Express and Fastify share.
+- Frameworks hand query values over as strings: coerce in the schema (`z.coerce.number()`).
+- `context` is `{ requestId, execution, principal?, raw }`. `execution` is the kernel
+  `ExecutionContext` of the request (see "The execution context of a request"); `raw` is the
+  framework's request object.
+- `security` is required: the names of the security schemes that apply, or `false` for a route
+  anybody may call. A route is never public by omission: leaving it out does not compile, and
+  `defineRoute` refuses an empty list, which would say the same as `false` without saying it.
+- `defineRoutes` and every mount refuse a duplicate `operationId` or method and path.
+- `prefixRoutes('/api', routes)` moves routes under a prefix, for the server and the contract.
+
+## Errors
+
+A handler throws a `DomainError`; its `code` is mapped to a status in one place and answered as
+`application/problem+json` (RFC 9457):
+
+```json
+{ "type": "urn:problem:not-found", "title": "Not Found", "status": 404, "code": "NOT_FOUND",
+  "detail": "Order 7 does not exist.", "requestId": "..." }
+```
+
+Defaults: `VALIDATION_FAILED` 422 (with `issues`, paths prefixed by the part:
+`body.items.0.sku`), `NOT_FOUND` 404, `CONFLICT` 409, `INVARIANT_VIOLATION` 422, `UNAUTHORIZED`
+401, `FORBIDDEN` 403. A domain code that is not mapped answers 422.
+
+```ts
+import { createErrorMapper } from '@ddd-ts-kit/http';
+
+const errorMapper = createErrorMapper({ ORDER_ALREADY_SHIPPED: 409, QUOTA_EXCEEDED: 429 });
+```
+
+Anything that is not a `DomainError` answers 500 `Internal Server Error` with no detail: the
+message of an unexpected error never leaves the process. Log it from the `onError` hook, and
+report it to the error tracker with `onError: reportHttpErrors(errorReporter)`: every request
+answered 5xx goes to the kernel `ErrorReporter`, once, with the correlation, actor and tenant
+ids of its execution context (`context.execution`, present once the request got that far); a
+4xx never does.
+
+## Options shared by the adapters
+
+```ts
+import type { ExecuteOptions } from '@ddd-ts-kit/http';
+
+const options: ExecuteOptions = {
+  errorMapper,
+  resolvePrincipal: (raw) => authenticate(raw), // throw UnauthorizedError to refuse
+  onError: (error, { requestId, correlationId, operationId, problem }) => {
+    if (problem.status >= 500) {
+      logger.error({ requestId, correlationId, operationId, error });
+    }
+  },
+  validateResponses: process.env.NODE_ENV === 'test', // checks answers against the declaration
+  around: tracedRoutes(), // of @ddd-ts-kit/tracing: the span of the request, named by its route template
+};
+```
+
+`around(route, respond)` wraps the whole handling of a request, from authentication to the
+answer, refusals included, and is told the route that was matched (`method`, `path` as
+declared, `operationId`). It is where a tracer names a request `POST /orders/:id/lines` instead
+of by its URL; this package depends on no tracing library.
+
+The request id is the incoming `x-request-id` when well formed, else a UUID; it is echoed in
+the `x-request-id` response header and in every problem.
+
+## The execution context of a request
+
+`executeRoute` builds a kernel `ExecutionContext` for every request and hands it to the handler
+as `context.execution`:
+
+| Field | Value |
+|---|---|
+| `correlationId` | the incoming `x-correlation-id` when well formed (letters, digits, `._:-`, at most 128), else the request id; echoed in the `x-correlation-id` response header, on problems too, and given to `onError` |
+| `origin` | `http` |
+| `actor`, `session` | from what `resolvePrincipal` answered, read structurally: a `Session` gives both, an `Actor` gives the actor, anything else is the anonymous actor |
+| `tenantId` | the tenant of the actor |
+| `locale` | the locale of the session, else the preferred language of `Accept-Language` |
+| `deadline` | arrival plus `requestTimeoutMs`, when the option is set |
+
+```ts
+import { Clock, ExecutionScope } from '@ddd-ts-kit/kernel';
+
+const options: ExecuteOptions = {
+  resolvePrincipal: principalResolver(authenticator), // of @ddd-ts-kit/auth: answers a Session
+  executionScope: app.resolve(ExecutionScope), // the scope the application runs its use cases in
+  clock: app.resolve(Clock),
+  requestTimeoutMs: 10_000,
+};
+```
+
+With `executionScope`, every handler runs inside `scope.run(context.execution, ...)`: loggers,
+audit columns, tenant scoping and outgoing headers read the context of the request with no
+wrapper around the handler, and no route can forget it. `withPrincipal` stays, for a scope of
+your own; it runs inside the execution scope. The pipeline does not interrupt a handler at its
+deadline: a timeout wrapper or an outgoing call reads `deadline` and honours it. `clock` is the
+option that says when a request arrived, the system clock by default.
+
+Use cases still receive the actor explicitly: `new PlaceOrder(context.execution.actor, body)`,
+or `actorOf(context.principal)` of `@ddd-ts-kit/auth`, which reads the same actor.
+
+## In the composition root
+
+The package binds and resolves nothing: routes are a plain list and `ExecuteOptions` a plain
+object, both built where the server starts. What it takes from the application are ports,
+resolved by their class:
+
+```ts
+import { createApplication, defineContextModule, kernelModule } from '@ddd-ts-kit/di';
+import { ErrorMapper, createErrorMapper, type ExecuteOptions } from '@ddd-ts-kit/http';
+import { Clock, ExecutionScope } from '@ddd-ts-kit/kernel';
+
+const httpModule = defineContextModule({
+  name: 'http',
+  register(builder) {
+    builder.bind(ErrorMapper).toValue(createErrorMapper({ ORDER_ALREADY_SHIPPED: 409 }));
+  },
+});
+
+const app = createApplication({ modules: [kernelModule(), httpModule, orderingModule] });
+
+const options: ExecuteOptions = {
+  errorMapper: app.resolve(ErrorMapper),
+  executionScope: app.resolve(ExecutionScope),
+  clock: app.resolve(Clock),
+};
+```
+
+| What | Is | Why |
+|---|---|---|
+| `ErrorMapper` | a port: an abstract class, the class is the token | one per application, and the server and the contract generator must be given the same one; binding it is optional, `createErrorMapper(...)` in a constant works as well |
+| `ExecutionScope`, `Clock` | ports of the kernel | resolved from the application and handed over in the options |
+| `resolvePrincipal`, `withPrincipal`, `onError`, `requestId` | functions of `ExecuteOptions` | hooks of one server, written where it starts; the injectable side of authentication is the `Authenticator` of `@ddd-ts-kit/auth`, which `principalResolver` turns into `resolvePrincipal` |
+| the route list | a value, `readonly Route[]` | the result of `defineRoutes(...)`, passed to the mount and to `generateOpenApi` |
+| `Schema` | an interface of `@ddd-ts-kit/validation` | one value per request part, declared in the route |
+
+## Pagination
+
+One query vocabulary and one answer for every search, on top of the kernel `PageRequest` and
+`Page`: `limit`, `offset` or `cursor`, and `sort` (`placedAt,-total`: comma-separated fields, a
+leading `-` for descending).
+
+```ts
+import { defineRoute, pageQuerySchema, pageResponse, pageSchemaOf } from '@ddd-ts-kit/http';
+
+const searchOrders = defineRoute(
+  {
+    method: 'GET',
+    path: '/orders',
+    operationId: 'searchOrders',
+    summary: 'Search orders',
+    request: { query: pageQuerySchema({ sortable: ['placedAt', 'total'], maxSize: 50 }) },
+    responses: { 200: { description: 'A page of orders.', body: pageSchemaOf(order) } },
+    security: ['bearer'],
+  },
+  async ({ query }) => ({
+    status: 200, // query is a PageRequest<'placedAt' | 'total'>
+    body: pageResponse(await orders.search(query), toOrderDto),
+  }),
+);
+```
+
+| Helper | Does |
+|---|---|
+| `pageRequestFrom(query, options?)` | reads the four parameters, as strings or already coerced, into a `PageRequest`; throws the `ValidationError` of the pipeline, so a wrong parameter answers 422 with one issue per parameter (`query.limit`, `query.sort`...). For a route whose query schema also has filters: declare the four parameters in that schema and call it in the handler |
+| `pageQuerySchema(options?)` | the same reading as a `Schema`, for a route whose whole query is the page |
+| `pageResponse(page, map)` | the JSON body `{ items, total?, nextCursor? }`, each item through `map` |
+| `pageRequestParameters(options?)` | the JSON Schema of the query (one OpenAPI parameter per property); `properties` merges into a wider schema |
+| `pageSchemaOf(itemSchema)` | the `Schema` of a page of items: validates the envelope and each item, describes both in the contract |
+
+`options` are the `PageLimits` of the kernel (`defaultSize` 20, `maxSize` 100) plus `sortable`,
+the closed list of fields a client may sort by, and `kind`, the variant of a query that names
+neither `offset` nor `cursor` (`offset` by default). Without `sortable`, a `sort` parameter is
+refused: a client never chooses a column the read port did not offer. `offset` and `cursor`
+together are refused. These helpers depend on no validation library; `pageQuerySchema` and
+`pageSchemaOf` are plain `Schema`s and sit next to zod or class-validator schemas.
+
+## Filters and sorting
+
+One query grammar for every search route, on top of the kernel `Criteria`: the read port declares
+what it accepts with `defineCriteria`, and the route reads the query into a criteria that
+definition accepts, or answers 422.
+
+```ts
+import { criteriaQuerySchema, defineRoute, pageResponse, pageSchemaOf } from '@ddd-ts-kit/http';
+
+const searchAppointments = defineRoute(
+  {
+    method: 'GET',
+    path: '/appointments',
+    operationId: 'searchAppointments',
+    summary: 'Search appointments',
+    request: { query: criteriaQuerySchema(appointmentCriteria) },
+    responses: { 200: { description: 'A page of appointments.', body: pageSchemaOf(appointment) } },
+    security: ['bearer'],
+  },
+  async ({ query, context }) => ({
+    status: 200, // query is a Criteria<AppointmentRow>
+    body: pageResponse(await queries.execute(new SearchAppointments(context.execution.actor, query)), toAppointmentDto),
+  }),
+);
+```
+
+```
+GET /appointments?filter[status]=in:booked,confirmed&filter[startsAt]=gte:2026-10-01T00:00:00Z
+                 &filter[or][practitionerId]=eq:p-7&filter[or][remote]=true
+                 &sort=-startsAt,id&limit=20&cursor=eyJzdGFydHNBdCI6...
+```
+
+| Written | Means |
+|---|---|
+| `filter[<field>]=<operator>:<value>` | one condition. The operators are those of the kernel: `eq`, `ne`, `in`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith`, `isNull`, `between` |
+| `filter[<field>]=<value>` | `eq`. The text before the first colon is an operator only when it is the name of one: `filter[title]=10:30 review` is an `eq`, and a value that starts like an operator is written `eq:in:the morning` |
+| several `filter[...]` | joined by AND; the same field may be repeated: `filter[seats]=gte:2&filter[seats]=lte:4` |
+| `in:<a>,<b>,<c>` | a list, separated by commas. A comma inside a value is written `\,`, a backslash `\\`; a colon needs nothing |
+| `between:<from>,<to>` | two values, both bounds included |
+| `isNull:true`, `isNull:false`, `isNull` | without a value, or with one; `isNull` alone means `true` |
+| `contains:<text>`, `startsWith:<text>` | the text as it is, commas included; case sensitive |
+| `filter[or][<field>]=...` | the conditions written under `or` are alternatives; under `not`, the rows that satisfy them all are refused; `and` exists for symmetry |
+| `filter[or][0][<field>]=...&filter[or][0][<other>]=...&filter[or][1][<field>]=...` | an index holds several conditions together inside a group: `or(and(...), ...)`. It counts as one more level of depth, which the definition allows or not (`maxDepth`, 1 by default) |
+| `sort=-startsAt,id` | comma-separated or repeated, a leading `-` for descending, among the fields declared sortable and the tie-breaker |
+| `limit`, `offset`, `cursor` | the page, read by the helpers of "Pagination" with the limits of the definition |
+
+A value is read by the type its field declares: a number in plain digits (no exponent), `true`
+or `false`, a decimal kept as written, an instant in ISO 8601 with its zone
+(`2026-10-01T08:00:00Z`, `2026-10-01T10:00:00+02:00`) or a date alone, taken at midnight UTC.
+Percent-encoding is the transport's: `+` in a zone is sent `%2B`. `and`, `or`, `not` and
+numbers are reserved names: a field called so cannot be filtered. Both ways a framework hands
+a query are read: the keys as written (`'filter[status]'`, Express 5 and Fastify by default)
+and already nested (`filter: { status }`, a `qs` parser).
+
+Anything the definition does not declare is refused with the 422 problem of the pipeline, one
+issue per mistake, none quoting a value:
+
+| `path` | `code` |
+|---|---|
+| `query.filter.<field>` | `unknown_field`, `operator_not_allowed`, `invalid_value`, `in_list_too_long`, `invalid_filter` (not written `filter[<field>]=<operator>:<value>`) |
+| `query.filter` | `too_deep`, `empty_group`, `too_many_filters`, `invalid_filter` |
+| `query.sort` | `unsortable_field`, `invalid_sort` |
+| `query.limit`, `query.offset`, `query.cursor` | `invalid_limit`, `invalid_offset`, `invalid_cursor`, `offset_with_cursor` |
+
+| Helper | Does |
+|---|---|
+| `criteriaQuerySchema(definition, { kind? })` | the reading as a `Schema`, for a route whose whole query is the criteria |
+| `criteriaFrom(query, definition, { kind? })` | the same reading in a handler, for a route whose query schema holds other parameters too; throws the `ValidationError` of the pipeline |
+| `criteriaParameters(definition)` | the JSON Schema of the query, one OpenAPI parameter per property: `filter[<field>]` for each field with an operator, with the operators in its description and in `x-filter-operators`, its type in `x-filter-type`; `sort` as the list of the values it accepts; `limit`, `offset` and `cursor` |
+
+The scope of the actor is not a parameter: the handler of the query joins it with `scoped`,
+and nothing in a query string can remove it.
+
+## Express 5
+
+```ts
+import express from 'express';
+import { mountExpress } from '@ddd-ts-kit/http/express';
+
+const app = express();
+app.use(express.json()); // required: the adapter does not parse bodies
+mountExpress(app, orderRoutes(orders), options); // an express.Router() works too
+```
+
+## Fastify 5
+
+```ts
+import Fastify from 'fastify';
+import { fastifyRoutes, mountFastify } from '@ddd-ts-kit/http/fastify';
+
+const app = Fastify();
+mountFastify(app, orderRoutes(orders), options);
+// or, as a plugin:
+await app.register(fastifyRoutes(orderRoutes(orders), options), { prefix: '/api' });
+```
+
+## NestJS
+
+No decorator per route: a module mounts the routes on the underlying HTTP server at module
+init, whether Nest runs on Express or on Fastify. Handlers get their dependencies by closure.
+
+```ts
+import { Module } from '@nestjs/common';
+import { createRoutesModule } from '@ddd-ts-kit/http/nest';
+
+@Module({
+  imports: [
+    createRoutesModule(
+      { inject: [OrderQueries], useFactory: (orders: OrderQueries) => orderRoutes(orders) },
+      { ...options, imports: [OrdersModule] }, // the modules exporting the injected tokens
+    ),
+  ],
+})
+export class AppModule {}
+```
+
+A plain array works as well: `createRoutesModule(routes, options)`. These routes bypass Nest's
+pipes, guards, interceptors, exception filters and global prefix: validation and error mapping
+are those described above. Use `prefixRoutes` for a prefix.
+
+## OpenAPI 3.1
+
+```ts
+import { readFileSync, writeFileSync } from 'node:fs';
+import { checkOpenApiDrift, generateOpenApi, stringifyOpenApi } from '@ddd-ts-kit/http/openapi';
+
+const document = generateOpenApi({
+  info: { title: 'Orders', version: '1.0.0' },
+  servers: [{ url: 'https://api.example.com' }],
+  routes: orderRoutes(orders),
+  securitySchemes: { bearer: { type: 'http', scheme: 'bearer' } },
+  errorMapper, // the one the server runs with
+});
+
+writeFileSync('openapi.json', stringifyOpenApi(document));
+
+// In CI: regenerate and fail on a difference.
+if (checkOpenApiDrift(document, readFileSync('openapi.json', 'utf8')).drift) {
+  process.exit(1);
+}
+```
+
+What is generated: `{param}` paths, one parameter per property of the params, query and headers
+schemas, the request body, the declared responses, the `security` of every operation (an empty
+list for a public route), one `application/problem+json` response per
+status of the declared `errors` (codes listed in the description and in `x-error-codes`), 422
+whenever the route validates input, a shared `Problem` schema. Local `$defs` of the schemas are
+moved to `components.schemas`. Paths, statuses and component keys are sorted: the output does
+not depend on the order of the routes, so the committed file diffs cleanly.
+
+## Serving the contract and its page
+
+```ts
+import { openApiDocsRoutes } from '@ddd-ts-kit/http/docs';
+
+const routes = [...orderRoutes(orders), ...openApiDocsRoutes(document, { ui: 'scalar' })];
+```
+
+Two public routes (`security: false`), mounted next to the application routes and absent
+from the contract they display:
+the JSON document (`jsonPath`, default `/openapi.json`) and an interactive page (`uiPath`,
+default `/docs`) rendered by `ui`: `swagger` (default), `scalar` or `redoc`. The page loads the
+assets of the UI from a public CDN pinned to a major version; `assetsUrl` points it at
+self-hosted files when it must work offline or under a strict content security policy. A
+project generated by the CLI mounts them in `src/platform/http/with-documentation.ts`, with
+the UI chosen by `--docs-ui`, unless documentation is switched off by its configuration.
+
+## Limits
+
+- A body the framework itself refuses (malformed JSON, payload too large) is answered by the
+  framework's own error handler, before the pipeline runs.
+- Routes are JSON first. A handler may answer a string or bytes by setting its own
+  `content-type` header; streaming is out of scope.

package/dist/criteria/coerce-value.d.ts

@@ -0,0 +1,8 @@
+import type { FieldType, FieldValue } from '@ddd-ts-kit/kernel';
+/**
+ * A value of a query string as the type of its field reads it, `undefined` when it does not:
+ * a number in plain digits, `true` or `false`, an ISO 8601 instant with its zone (or a date,
+ * taken at midnight UTC), a decimal kept as written.
+ */
+export declare function coerceValue(type: FieldType, text: string): FieldValue | undefined;
+//# sourceMappingURL=coerce-value.d.ts.map

package/dist/criteria/coerce-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce-value.d.ts","sourceRoot":"","sources":["../../src/criteria/coerce-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAKhE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAajF"}

package/dist/criteria/coerce-value.js

@@ -0,0 +1,29 @@
+const NUMBER = /^-?\d+(?:\.\d+)?$/;
+const INSTANT = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2}))?$/;
+/**
+ * A value of a query string as the type of its field reads it, `undefined` when it does not:
+ * a number in plain digits, `true` or `false`, an ISO 8601 instant with its zone (or a date,
+ * taken at midnight UTC), a decimal kept as written.
+ */
+export function coerceValue(type, text) {
+    switch (type) {
+        case 'string':
+            return text;
+        case 'number':
+            return NUMBER.test(text) ? Number(text) : undefined;
+        case 'decimal':
+            return NUMBER.test(text) ? text : undefined;
+        case 'boolean':
+            return booleanOf(text);
+        case 'instant':
+            return instantOf(text);
+    }
+}
+function booleanOf(text) {
+    return text === 'true' || text === 'false' ? text === 'true' : undefined;
+}
+function instantOf(text) {
+    const instant = new Date(text);
+    return INSTANT.test(text) && !Number.isNaN(instant.getTime()) ? instant : undefined;
+}
+//# sourceMappingURL=coerce-value.js.map

package/dist/criteria/coerce-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce-value.js","sourceRoot":"","sources":["../../src/criteria/coerce-value.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,mBAAmB,CAAC;AACnC,MAAM,OAAO,GAAG,oFAAoF,CAAC;AAErG;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe,EAAE,IAAY;IACvD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9C,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,OAAO,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACtF,CAAC"}

package/dist/criteria/criteria-from.d.ts

@@ -0,0 +1,11 @@
+import type { Criteria, CriteriaDefinition } from '@ddd-ts-kit/kernel';
+import type { CriteriaQueryOptions } from './criteria-query-options.js';
+/**
+ * Reads the criteria of a search route from its query: `filter[<field>]=<operator>:<value>`,
+ * groups, and the `sort`, `limit`, `offset` and `cursor` of a page. Anything the definition of
+ * the read port does not declare throws the `ValidationError` of the pipeline: a 422 whose
+ * issues name `query.filter.<field>` and a stable code. For a route whose query schema holds
+ * other parameters too; `criteriaQuerySchema` is the same reading as a schema.
+ */
+export declare function criteriaFrom<Row>(query: unknown, definition: CriteriaDefinition<Row>, options?: CriteriaQueryOptions): Criteria<Row>;
+//# sourceMappingURL=criteria-from.d.ts.map

package/dist/criteria/criteria-from.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-from.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-from.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGxE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAC9B,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,EACnC,OAAO,GAAE,oBAAyB,GACjC,QAAQ,CAAC,GAAG,CAAC,CAWf"}

package/dist/criteria/criteria-from.js

@@ -0,0 +1,17 @@
+import { ValidationError } from '@ddd-ts-kit/validation';
+import { parseCriteriaQuery } from './parse-criteria-query.js';
+/**
+ * Reads the criteria of a search route from its query: `filter[<field>]=<operator>:<value>`,
+ * groups, and the `sort`, `limit`, `offset` and `cursor` of a page. Anything the definition of
+ * the read port does not declare throws the `ValidationError` of the pipeline: a 422 whose
+ * issues name `query.filter.<field>` and a stable code. For a route whose query schema holds
+ * other parameters too; `criteriaQuerySchema` is the same reading as a schema.
+ */
+export function criteriaFrom(query, definition, options = {}) {
+    const parsed = parseCriteriaQuery(query, definition, options);
+    if (parsed.ok) {
+        return parsed.value;
+    }
+    throw new ValidationError(parsed.error.map((issue) => ({ ...issue, path: `query.${issue.path}` })), 'The request is not valid.');
+}
+//# sourceMappingURL=criteria-from.js.map

package/dist/criteria/criteria-from.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-from.js","sourceRoot":"","sources":["../../src/criteria/criteria-from.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,UAAmC,EACnC,OAAO,GAAyB,EAAE;IAElC,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAE9D,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,MAAM,IAAI,eAAe,CACvB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EACxE,2BAA2B,CAC5B,CAAC;AACJ,CAAC"}

package/dist/criteria/criteria-parameters.d.ts

@@ -0,0 +1,10 @@
+import type { CriteriaDefinition } from '@ddd-ts-kit/kernel';
+import type { JsonSchema } from '@ddd-ts-kit/validation';
+/**
+ * The query parameters of a criteria as a JSON Schema object, one OpenAPI parameter per
+ * property: a `filter[<field>]` for each field that can be filtered, its operators in the
+ * description and in `x-filter-operators`, its type in `x-filter-type`; `sort` as the list of
+ * the values it accepts; `limit`, `offset` and `cursor` as `pageRequestParameters` gives them.
+ */
+export declare function criteriaParameters<Row>(definition: CriteriaDefinition<Row>): JsonSchema;
+//# sourceMappingURL=criteria-parameters.d.ts.map

package/dist/criteria/criteria-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-parameters.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-parameters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAoB,MAAM,oBAAoB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAazD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,UAAU,CAgBvF"}

package/dist/criteria/criteria-parameters.js

@@ -0,0 +1,45 @@
+import { pageRequestParameters } from '../pagination/page-request-parameters.js';
+import { isRecord } from '../support/is-record.js';
+import { sortableFields } from './sortable-fields.js';
+const WRITTEN = {
+    string: 'text',
+    number: 'a number',
+    boolean: '`true` or `false`',
+    instant: 'an ISO 8601 instant with its zone',
+    decimal: 'a decimal number',
+};
+/**
+ * The query parameters of a criteria as a JSON Schema object, one OpenAPI parameter per
+ * property: a `filter[<field>]` for each field that can be filtered, its operators in the
+ * description and in `x-filter-operators`, its type in `x-filter-type`; `sort` as the list of
+ * the values it accepts; `limit`, `offset` and `cursor` as `pageRequestParameters` gives them.
+ */
+export function criteriaParameters(definition) {
+    const { defaultPageSize, maxPageSize } = definition.limits;
+    const page = pageRequestParameters({ defaultSize: defaultPageSize, maxSize: maxPageSize })['properties'];
+    const filters = Object.entries(definition.fields).flatMap(([field, declared]) => declared.filter.length === 0 ? [] : [[`filter[${field}]`, filterParameter(field, declared)]]);
+    return {
+        type: 'object',
+        properties: {
+            ...Object.fromEntries(filters),
+            sort: sortParameter(sortableFields(definition)),
+            ...(isRecord(page) ? page : {}),
+        },
+    };
+}
+function filterParameter(field, { type, filter }) {
+    return {
+        type: 'string',
+        description: `Filters on \`${field}\`, written \`<operator>:<value>\`; the value alone means \`eq\`. Operators: ${filter.join(', ')}. The value is ${WRITTEN[type]}.`,
+        'x-filter-operators': [...filter],
+        'x-filter-type': type,
+    };
+}
+function sortParameter(sortable) {
+    return {
+        type: 'array',
+        items: { type: 'string', enum: sortable.flatMap((field) => [field, `-${field}`]) },
+        description: 'The fields to sort by, a leading "-" for descending, repeated or separated by commas.',
+    };
+}
+//# sourceMappingURL=criteria-parameters.js.map

package/dist/criteria/criteria-parameters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-parameters.js","sourceRoot":"","sources":["../../src/criteria/criteria-parameters.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,MAAM,OAAO,GAAuD;IAClE,MAAM,EAAE,MAAM;IACd,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,mBAAmB;IAC5B,OAAO,EAAE,mCAAmC;IAC5C,OAAO,EAAE,kBAAkB;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAM,UAAmC;IACzE,MAAM,EAAE,eAAe,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC;IAC3D,MAAM,IAAI,GAAY,qBAAqB,CAAC,EAAE,WAAW,EAAE,eAAe,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;IAElH,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,CAC9E,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,KAAK,GAAG,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,CAC7F,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC;YAC9B,IAAI,EAAE,aAAa,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;YAC/C,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;SAChC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAoB;IACxE,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,gBAAgB,KAAK,gFAAgF,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,OAAO,CAAC,IAAI,CAAC,GAAG;QACrK,oBAAoB,EAAE,CAAC,GAAG,MAAM,CAAC;QACjC,eAAe,EAAE,IAAI;KACtB,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,QAA2B;IAChD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,EAAE;QAClF,WAAW,EAAE,uFAAuF;KACrG,CAAC;AACJ,CAAC"}

package/dist/criteria/criteria-query-options.d.ts

@@ -0,0 +1,6 @@
+import type { PageRequest } from '@ddd-ts-kit/kernel';
+export interface CriteriaQueryOptions {
+    /** The variant of a query that names neither `offset` nor `cursor`. Default `offset`. */
+    readonly kind?: PageRequest['kind'];
+}
+//# sourceMappingURL=criteria-query-options.d.ts.map

package/dist/criteria/criteria-query-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-query-options.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-query-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC"}

package/dist/criteria/criteria-query-options.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=criteria-query-options.js.map

package/dist/criteria/criteria-query-options.js.map

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

package/dist/criteria/criteria-query-schema.d.ts

@@ -0,0 +1,10 @@
+import type { Criteria, CriteriaDefinition } from '@ddd-ts-kit/kernel';
+import { type Schema } from '@ddd-ts-kit/validation';
+import type { CriteriaQueryOptions } from './criteria-query-options.js';
+/**
+ * The query of a search route as a `Schema`: `request: { query: criteriaQuerySchema(definition) }`
+ * hands the handler a `Criteria` the read port accepts, and documents every filter, the sort
+ * and the page in the contract.
+ */
+export declare function criteriaQuerySchema<Row>(definition: CriteriaDefinition<Row>, options?: CriteriaQueryOptions): Schema<Criteria<Row>>;
+//# sourceMappingURL=criteria-query-schema.d.ts.map

package/dist/criteria/criteria-query-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-query-schema.d.ts","sourceRoot":"","sources":["../../src/criteria/criteria-query-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGxE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EACrC,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,EACnC,OAAO,GAAE,oBAAyB,GACjC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAEvB"}

package/dist/criteria/criteria-query-schema.js

@@ -0,0 +1,12 @@
+import { customSchema } from '@ddd-ts-kit/validation';
+import { criteriaParameters } from './criteria-parameters.js';
+import { parseCriteriaQuery } from './parse-criteria-query.js';
+/**
+ * The query of a search route as a `Schema`: `request: { query: criteriaQuerySchema(definition) }`
+ * hands the handler a `Criteria` the read port accepts, and documents every filter, the sort
+ * and the page in the contract.
+ */
+export function criteriaQuerySchema(definition, options = {}) {
+    return customSchema((query) => parseCriteriaQuery(query, definition, options), criteriaParameters(definition));
+}
+//# sourceMappingURL=criteria-query-schema.js.map

package/dist/criteria/criteria-query-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria-query-schema.js","sourceRoot":"","sources":["../../src/criteria/criteria-query-schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAe,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAmC,EACnC,OAAO,GAAyB,EAAE;IAElC,OAAO,YAAY,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC;AACjH,CAAC"}

package/dist/criteria/filter-entries.d.ts

@@ -0,0 +1,9 @@
+import type { FilterEntry } from './filter-entry.js';
+/**
+ * The filter parameters of a query, whichever way the framework hands them: the keys as
+ * written (`{ 'filter[status]': 'eq:booked' }`, Express 5 and Fastify by default) or already
+ * nested (`{ filter: { status: 'eq:booked' } }`, a `qs` parser). A repeated parameter comes as
+ * a list of values.
+ */
+export declare function filterEntries(query: Readonly<Record<string, unknown>>): FilterEntry[];
+//# sourceMappingURL=filter-entries.d.ts.map

package/dist/criteria/filter-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-entries.d.ts","sourceRoot":"","sources":["../../src/criteria/filter-entries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,WAAW,EAAE,CAQrF"}

package/dist/criteria/filter-entries.js

@@ -0,0 +1,28 @@
+import { isRecord } from '../support/is-record.js';
+const FLAT = /^filter((?:\[[^[\]]*\])+)$/;
+/**
+ * The filter parameters of a query, whichever way the framework hands them: the keys as
+ * written (`{ 'filter[status]': 'eq:booked' }`, Express 5 and Fastify by default) or already
+ * nested (`{ filter: { status: 'eq:booked' } }`, a `qs` parser). A repeated parameter comes as
+ * a list of values.
+ */
+export function filterEntries(query) {
+    const flat = Object.entries(query).flatMap(([key, value]) => {
+        const brackets = FLAT.exec(key)?.[1];
+        return brackets === undefined ? [] : [{ path: brackets.slice(1, -1).split(']['), values: listed(value) }];
+    });
+    return query['filter'] === undefined ? flat : [...flat, ...nested(query['filter'], [])];
+}
+function nested(value, path) {
+    if (isRecord(value)) {
+        return Object.entries(value).flatMap(([key, inner]) => nested(inner, [...path, key]));
+    }
+    if (Array.isArray(value) && value.some((item) => isRecord(item))) {
+        return value.flatMap((item, index) => nested(item, [...path, String(index)]));
+    }
+    return [{ path, values: listed(value) }];
+}
+function listed(value) {
+    return Array.isArray(value) ? value : [value];
+}
+//# sourceMappingURL=filter-entries.js.map