@aventara/nest 0.1.0-pilot.3 → 0.1.0-pilot.4

package/dist/aventara.module.d.ts

@@ -2,16 +2,9 @@ import { type AdapterModel, type AnyFrameworkConfig, type Framework, type Framew
 import { type DynamicModule, type FactoryProvider, type ModuleMetadata, type NestModule, type OnModuleInit } from "@nestjs/common";
 import { type PendingProtocolHost } from "./protocol-host.factory.js";
 /**
- * How the application's Framework enters Nest: either the developer's own instance
- * — they called `createFramework` — or the configuration the module hands to
- * `createFramework` itself. Exactly one arm; the `?: never` halves make both a
- * type error.
- *
- * The `config` arm is typed exactly as `createFramework`'s parameter, so a
- * configuration annotated `FrameworkConfig<M>`, written inline, inferred or
- * checked with `satisfies` is accepted — and checked against its own Adapter model
- * — wherever `createFramework` would accept it. The defaults are the untyped
- * forms.
+ * How the application's Framework enters Nest: your own instance
+ * (`{ framework }`, from `createFramework`) or a configuration the module
+ * passes to `createFramework` itself (`{ config }`). Pass exactly one.
  */
 export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
     readonly framework: Framework;
@@ -21,28 +14,40 @@ export type AventaraModuleOptions<M extends AdapterModel = AdapterModel, Cfg = A
     readonly framework?: never;
 };
 /**
- * `forRootAsync`'s options: the Nest idiom when what builds the Framework (a
- * Prisma client, a configuration service) is itself a provider. The factory
- * resolves to either arm of {@link AventaraModuleOptions}.
+ * `forRootAsync`'s options: the Nest idiom when what builds the Framework
+ * (a Prisma client, a configuration service) is itself a provider. The
+ * factory resolves to either arm of {@link AventaraModuleOptions}.
  */
 export type AventaraModuleAsyncOptions<M extends AdapterModel = AdapterModel, Cfg = AnyFrameworkConfig> = {
+    /** Modules whose providers the factory injects. */
     readonly imports?: ModuleMetadata["imports"];
+    /** The providers passed to `useFactory`, in order. */
     readonly inject?: FactoryProvider["inject"];
+    /** Returns the module options: `{ framework }` or `{ config }`. */
     readonly useFactory: (...deps: never[]) => AventaraModuleOptions<M, Cfg> | Promise<AventaraModuleOptions<M, Cfg>>;
 };
 /**
- * The global module that hosts one Aventara Framework, and mounts its protocol on
- * the application's platform from `configure()`: after the developer's `app.use` /
- * `enableCors`, before `MiddlewareConsumer` middleware and every controller, so
- * the reserved `_` namespace cannot be shadowed.
+ * The global module that hosts one Aventara Framework and mounts its protocol
+ * on the application's platform: after your `app.use` / `enableCors`, before
+ * `MiddlewareConsumer` middleware and every controller, so the reserved `_`
+ * namespace cannot be shadowed.
  */
 export declare class AventaraModule implements NestModule, OnModuleInit {
     private readonly host;
     constructor(host: PendingProtocolHost);
+    /** Mounts the protocol routes on the HTTP platform. */
     configure(): void;
-    /** An application context never receives a platform: refused here, at its init. */
+    /**
+     * Refuses to start in a Nest application context with no HTTP platform, where
+     * the protocol cannot be mounted.
+     */
     onModuleInit(): void;
+    /** Registers the module with a Framework instance or a configuration. */
     static forRoot<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleOptions<M, Cfg>): DynamicModule;
+    /**
+     * Registers the module with options built by a factory, for when the
+     * Framework's inputs (a Prisma client, a config service) are providers.
+     */
     static forRootAsync<M extends AdapterModel, const Cfg = AnyFrameworkConfig>(options: AventaraModuleAsyncOptions<M, Cfg>): DynamicModule;
     private static mount;
 }

package/dist/express-protocol.mounter.d.ts

@@ -2,21 +2,10 @@ import type { AvProtocolBinding } from "@aventara/core/protocol";
 import { type NodeIncoming, type NodeOutgoing } from "./node-exchange.translator.js";
 import type { ProtocolHost } from "./protocol-host.factory.js";
 /**
- * The protocol on Nest's Express platform.
- *
- * - **The pre-parser**, installed while Nest instantiates providers — before
- *   Nest's own body parsers: a request under `<entrypoint>/_` has its body read
- *   raw, bounded and decoded, and kept for its route. Its stream is then finished,
- *   so Nest's parsers skip it; every other request keeps Nest's parsed body. It
- *   reads; it answers nothing.
- * - **The routes**, mounted from the module's `configure()`: one platform route
- *   per `protocol.surface()` entry, each at its escaped literal path under the
- *   entrypoint, then one fallback — `protocol.answerAbsent`, the absence handler,
- *   not a catch-all: it executes nothing, and a path it does not own (`undefined`)
- *   goes on to Nest.
- *
- * Its whole job is translation: the Express request into an `AvProtocolRequest`,
- * the `AvProtocolResponse` back onto the wire.
+ * The protocol on Nest's Express platform: one platform route per protocol
+ * route under the entrypoint, translating the Express request into the
+ * protocol's request and the protocol's response back onto the wire. A path the
+ * protocol does not own goes on to Nest.
  */
 /** Express's request: Node's `IncomingMessage`, plus `originalUrl`. */
 type ExpressRequest = NodeIncoming & {

package/dist/fastify-protocol.mounter.d.ts

@@ -2,33 +2,13 @@ import type { AvProtocolBinding } from "@aventara/core/protocol";
 import { type NodeIncoming, type NodeOutgoing, type PlatformHeaders } from "./node-exchange.translator.js";
 import type { ProtocolHost } from "./protocol-host.factory.js";
 /**
- * The protocol on Nest's Fastify platform, mounted from the module's
- * `configure()`.
- *
- * - **One Fastify route per `protocol.surface()` entry**, at its literal path
- *   under the entrypoint, with Fastify's automatic `HEAD` route off, so `HEAD
- *   /_contract` reaches the protocol's `405` as on Express.
- * - **Each route is answered from its own `onRequest` hook** — Fastify's first
- *   step, before its content-type check and body parsing: the body is read raw off
- *   Node's request by the bounded reader, the bound member answers, and the reply
- *   is hijacked. Fastify's parsers, `bodyLimit` and early `415` (on a
- *   `Content-Type` it cannot parse) never run on a protocol route, so every body
- *   failure is the protocol's own answer, as on Express. The route handler is
- *   never reached.
- * - **The absence fallback** is a root `onRequest` hook acting only on a request
- *   Fastify matched to no route (`request.is404`) under `<entrypoint>/`:
- *   `protocol.answerAbsent`, and `undefined` hands the request on to Nest's own
- *   not-found handler. A not-found handler of our own could not hand back: inside
- *   one, Fastify answers its plain-text 404, not Nest's.
- * - **Literal paths**: each route is registered `decodeURI`-ed, as find-my-way
- *   decodes a request path before matching it (`café`, `a[b]`). A path find-my-way
- *   cannot match as a literal — a `*` (its wildcard) or a reserved escape (it
- *   keeps those encoded, and never matches them against a static route) — is
- *   refused while Nest builds the application, naming the Resource keys; Express
- *   mounts them all.
- * - **Writes** go through Node's response after `reply.hijack()`, with the headers
- *   Fastify hooks already set (CORS) beneath the protocol's own — what Node's
- *   `writeHead` does on Express.
+ * The protocol on Nest's Fastify platform: one Fastify route per protocol route
+ * under the entrypoint, answered from its own `onRequest` hook before Fastify's
+ * content-type check and body parsing, so every body failure is the protocol's
+ * own answer, as on Express. A path the protocol does not own goes on to Nest's
+ * not-found handler. A route path Fastify cannot match literally (a `*`, or a
+ * reserved escape) is refused while Nest builds the application, naming the
+ * Resource keys.
  */
 /** Fastify's request: Node's own under `raw`, and whether a route matched. */
 type FastifyRequest = {

package/dist/framework.token.d.ts

@@ -1,9 +1,7 @@
 /**
- * The DI token under which `AventaraModule` provides the application's
- * `Framework`. A symbol, so injection is exact: an abstract-class token would type
- * the injected value as an empty class, not the application's own `Framework<M,
- * Cfg>`.
+ * The injection token under which `AventaraModule` provides the application's
+ * `Framework`. Type the injected value with your own `Framework<M, Cfg>` alias.
  */
 export declare const AVENTARA_FRAMEWORK: unique symbol;
-/** `@InjectFramework()` — `@Inject(AVENTARA_FRAMEWORK)` in one call. */
+/** `@InjectFramework()`: `@Inject(AVENTARA_FRAMEWORK)` in one call. */
 export declare function InjectFramework(): ParameterDecorator;

package/dist/node-exchange.translator.d.ts

@@ -10,16 +10,13 @@ export type NodeOutgoing = {
 export type PlatformHeaders = Readonly<Record<string, string | number | readonly string[] | undefined>>;
 /** Zero bytes: the body of a request whose body the protocol does not read. */
 export declare const NO_BYTES: Uint8Array<ArrayBuffer>;
-/** A request URL's raw pathname — query dropped, not URL-decoded. */
+/** A request URL's raw pathname: the query is dropped and nothing is URL-decoded. */
 export declare function pathnameOf(url: string): string;
-/**
- * The request as the protocol reads it: path relative to the entrypoint,
- * `headersDistinct`, the raw arm.
- */
+/** The request as the protocol reads it: path relative to the entrypoint, distinct headers, raw body. */
 export declare function protocolRequest(method: string, url: string, incoming: NodeIncoming, entrypoint: string, content: Uint8Array): AvProtocolRequest;
 /**
- * The protocol's answer, written as it is. Headers the platform's hooks already
- * set (CORS, say) go beneath it; a protocol header of the same name, in any case,
- * wins — what Node's `writeHead` does with `setHeader`'s on Express.
+ * Writes the protocol's answer as it is. Headers the platform's hooks already
+ * set (CORS, say) go beneath it; a protocol header of the same name, in any
+ * case, wins.
  */
 export declare function writeAnswer(response: NodeOutgoing, answer: AvProtocolResponse, beneath?: PlatformHeaders): void;

package/dist/protocol-host.factory.d.ts

@@ -7,9 +7,9 @@ export type ProtocolHost = {
 };
 /**
  * Binds `framework`'s protocol for the application's platform, refusing an
- * unsupported platform while providers are instantiated — so `NestFactory.create`
- * rejects before the application listens. The routes are mounted later, from the
- * module's `configure()`.
+ * unsupported platform while providers are instantiated, so `NestFactory.create`
+ * rejects before the application listens. The routes are mounted later, from
+ * the module's `configure()`.
  */
 export declare function createProtocolHost(adapter: AbstractHttpAdapter | undefined, framework: Framework): ProtocolHost;
 /**
@@ -32,14 +32,7 @@ export type AdapterHostView = {
     };
 };
 /**
- * `NestFactory.create` sets the adapter first: the host is created at once, and an
- * unsupported platform rejects then, as before. Nest's testing module compiles
- * first and receives its adapter from `createNestApplication()`, which sets it on
- * the `HttpAdapterHost` — `init$` fires — before `app.init()` registers Nest's
- * body parsers: the host is created at that moment, so a platform's body reader is
- * still installed ahead of them. A refusal there is kept and raised by `mount()`
- * or `assertReady()`, from `app.init()` — still before the application listens.
- * With no adapter at all (`createApplicationContext`), `assertReady()` refuses
- * from `onModuleInit`.
+ * A host for an application whose HTTP adapter may arrive after the providers
+ * are instantiated (Nest's testing module).
  */
 export declare function createPendingProtocolHost(application: AdapterHostView, framework: Framework): PendingProtocolHost;

package/dist/protocol-route.table.d.ts

@@ -1,17 +1,9 @@
 import type { AvProtocolBinding, AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
-/**
- * One route `protocol.surface()` lists. Core keeps `SurfaceRoute` a module
- * type, so the host derives it from the binding — no new core export.
- */
+/** One route `protocol.surface()` lists. */
 export type SurfaceRoute = ReturnType<AvProtocolBinding["surface"]>[number];
 /** What a mounted route answers its request with: a bound protocol member. */
 export type RouteAnswer = (request: AvProtocolRequest) => AvProtocolResponse | Promise<AvProtocolResponse>;
-/**
- * The bound member each kind of surface route is answered by — total over
- * `SurfaceRoute["kind"]`, so a route kind core adds fails to compile here
- * rather than mounting a route nothing answers. Every platform's mounter
- * reads this one table; none decides an answer of its own.
- */
+/** The bound member each kind of surface route is answered by. */
 export type ProtocolRouteTable = {
     readonly [K in SurfaceRoute["kind"]]: (binding: AvProtocolBinding) => RouteAnswer;
 };

package/dist/request-body.reader.d.ts

@@ -1,18 +1,7 @@
 import type { AvProtocolBinding, AvProtocolResponse } from "@aventara/core/protocol";
 /**
- * The raw arm's body reader: a request body read off a Node stream, decoded per
- * its `Content-Encoding`, and stored up to `maxRequestBytes + 1` DECODED bytes —
- * one more than the limit is all the decoder needs to answer `A2010`, and counting
- * decoded bytes is also the decompression-bomb bound. Past the bound the stream is
- * still read to its end and discarded, so the connection stays usable; nothing
- * more is inflated.
- *
- * Platform-free: it reads an async iterable of bytes, as Node's `IncomingMessage`
- * is.
- */
-/**
- * What the reader hands on: the stored bytes; an unsupported coding; or a body
- * that does not decode in the coding it names — a malformed request.
+ * What the body reader hands on: the stored bytes, an unsupported coding, or a
+ * body that does not decode in the coding it names.
  */
 export type RequestBodyRead = {
     readonly kind: "read";
@@ -23,11 +12,9 @@ export type RequestBodyRead = {
     readonly kind: "undecodable";
 };
 /**
- * The answer to a body the reader could not hand on, through the bound `failure`
- * member — the one place the host names an A-code: an unsupported coding is `415
- * A2011`; a body that does not decode in its coding is malformed, `400 A2000`. The
- * request id is minted by core: it exposes no adoption of the client's id to a
- * host.
+ * The answer to a body the reader could not hand on, through the bound
+ * `failure` member: an unsupported coding is `415 A2011`; a body that does not
+ * decode in its coding is malformed, `400 A2000`.
  */
 export declare function unreadBodyAnswer(binding: AvProtocolBinding, read: Exclude<RequestBodyRead, {
     readonly kind: "read";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/nest",
-  "version": "0.1.0-pilot.3",
+  "version": "0.1.0-pilot.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "NestJS host integration for Aventara.",
   "type": "module",
@@ -21,7 +21,7 @@
     "LICENSE-ADDITIONAL-PERMISSION.md"
   ],
   "dependencies": {
-    "@aventara/core": "0.1.0-pilot.3"
+    "@aventara/core": "0.1.0-pilot.4"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -31,8 +31,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/prisma7-adapter": "0.1.0-pilot.3",
-    "@aventara/testing": "0.1.0-pilot.3",
+    "@aventara/prisma7-adapter": "0.1.0-pilot.4",
+    "@aventara/testing": "0.1.0-pilot.4",
     "@nestjs/common": "^12.1.2",
     "@nestjs/core": "^12.1.2",
     "@nestjs/platform-express": "^12.1.2",