@plinthjs/http 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +35 -35
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +70 -70
- package/dist/index.d.ts +70 -70
- package/dist/index.js +35 -35
- package/dist/index.js.map +1 -1
- package/package.json +6 -6
package/dist/index.d.cts
CHANGED
|
@@ -3,7 +3,7 @@ import { Collection } from '@plinthjs/support';
|
|
|
3
3
|
import { Newable, Container } from '@plinthjs/core';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
|
-
* `Controller`
|
|
6
|
+
* `Controller` - the optional convention base for `[Controller, method]` route actions. Controllers are plain classes resolved through the `@plinthjs/core`
|
|
7
7
|
* container, so extending this is not required; it gives a shared, stable base for app-wide
|
|
8
8
|
* controller helpers and a clear type. Route/group middleware is declared on the route, not here.
|
|
9
9
|
*/
|
|
@@ -28,7 +28,7 @@ type StreamChunk = string | Uint8Array;
|
|
|
28
28
|
type StreamSource = Iterable<StreamChunk> | AsyncIterable<StreamChunk> | (() => Iterable<StreamChunk> | AsyncIterable<StreamChunk>);
|
|
29
29
|
/** A JSON streaming source: rows to stream as one array, or an object whose values may be iterables. */
|
|
30
30
|
type JsonStreamData = Iterable<unknown> | AsyncIterable<unknown> | Record<string, unknown>;
|
|
31
|
-
/** Options for {@link Response.cookie}
|
|
31
|
+
/** Options for {@link Response.cookie} - the common `Set-Cookie` attributes. */
|
|
32
32
|
interface CookieOptions {
|
|
33
33
|
/** `Max-Age` in seconds. */
|
|
34
34
|
maxAge?: number;
|
|
@@ -104,7 +104,7 @@ declare class Response {
|
|
|
104
104
|
/**
|
|
105
105
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
106
106
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
107
|
-
* client as it yields
|
|
107
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
108
108
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
109
109
|
* responses via {@link Response.writeStreamTo}.
|
|
110
110
|
*/
|
|
@@ -116,7 +116,7 @@ declare class Response {
|
|
|
116
116
|
*/
|
|
117
117
|
static streamDownload(source: StreamSource, filename: string, headers?: Record<string, string>): Response;
|
|
118
118
|
/**
|
|
119
|
-
* Build a streamed JSON response
|
|
119
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
120
120
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
121
121
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
122
122
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -125,7 +125,7 @@ declare class Response {
|
|
|
125
125
|
/** Whether this is a streamed response (flush it with {@link Response.writeStreamTo}). */
|
|
126
126
|
isStream(): boolean;
|
|
127
127
|
/**
|
|
128
|
-
* Register a reusable response builder under `name`. The `Response::macro()` equivalent
|
|
128
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
129
129
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
130
130
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
131
131
|
*/
|
|
@@ -193,7 +193,7 @@ declare class Response {
|
|
|
193
193
|
/**
|
|
194
194
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
195
195
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
196
|
-
* {@link Response.writeStreamTo} instead
|
|
196
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
197
197
|
* silently dropped.
|
|
198
198
|
*/
|
|
199
199
|
writeTo(res: ServerResponse): void;
|
|
@@ -227,7 +227,7 @@ declare class UploadedFile {
|
|
|
227
227
|
constructor(init: UploadedFileInit);
|
|
228
228
|
/** The raw uploaded bytes. The `get()` content accessor. */
|
|
229
229
|
get(): Buffer;
|
|
230
|
-
/** The raw uploaded bytes
|
|
230
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
231
231
|
buffer(): Buffer;
|
|
232
232
|
/** The client-supplied original filename. The `$file->getClientOriginalName()` equivalent. */
|
|
233
233
|
getClientOriginalName(): string;
|
|
@@ -241,7 +241,7 @@ declare class UploadedFile {
|
|
|
241
241
|
/** The size of the uploaded content in bytes. The `$file->getSize()` equivalent. */
|
|
242
242
|
getSize(): number;
|
|
243
243
|
/**
|
|
244
|
-
* Whether the upload is valid
|
|
244
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
245
245
|
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
246
246
|
*/
|
|
247
247
|
isValid(): boolean;
|
|
@@ -257,18 +257,18 @@ declare class UploadedFile {
|
|
|
257
257
|
storeAs(directory: string, name: string): string;
|
|
258
258
|
/**
|
|
259
259
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
260
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
260
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
261
261
|
*/
|
|
262
262
|
move(destination: string): string;
|
|
263
263
|
/**
|
|
264
|
-
* A unique storage filename preserving the original extension
|
|
264
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
265
265
|
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
266
266
|
*/
|
|
267
267
|
hashName(): string;
|
|
268
268
|
}
|
|
269
269
|
|
|
270
270
|
/**
|
|
271
|
-
* `Request`
|
|
271
|
+
* `Request` - an immutable wrapper around an inbound HTTP request, the conventional
|
|
272
272
|
*. It normalizes the method, URL, headers, cookies, and a
|
|
273
273
|
* parsed body, and exposes the familiar accessor surface (`input`, `only`, `query`, `bearerToken`,
|
|
274
274
|
* `wantsJson`, …). Instances are immutable: {@link Request.withParams} returns a fresh copy with
|
|
@@ -313,7 +313,7 @@ interface FromNodeOptions {
|
|
|
313
313
|
}
|
|
314
314
|
/**
|
|
315
315
|
* A `413 Payload Too Large`, thrown by {@link Request.fromNode} when an inbound body exceeds the
|
|
316
|
-
* configured cap
|
|
316
|
+
* configured cap - either declared up front by `Content-Length` or discovered while accumulating
|
|
317
317
|
* chunks. The server adapter answers it with a `413` and closes the connection (the unread
|
|
318
318
|
* remainder of the body would poison keep-alive reuse).
|
|
319
319
|
*/
|
|
@@ -329,7 +329,7 @@ declare class Request {
|
|
|
329
329
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
330
330
|
private _pathname;
|
|
331
331
|
private _host;
|
|
332
|
-
/** The host as received (port included, if any)
|
|
332
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
333
333
|
private _httpHost;
|
|
334
334
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
335
335
|
private _routeName;
|
|
@@ -398,7 +398,7 @@ declare class Request {
|
|
|
398
398
|
*/
|
|
399
399
|
httpHost(): string | undefined;
|
|
400
400
|
/**
|
|
401
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
401
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
402
402
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
403
403
|
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
404
404
|
* `undefined` when no host is known.
|
|
@@ -407,13 +407,13 @@ declare class Request {
|
|
|
407
407
|
/** The request scheme: the first `X-Forwarded-Proto` hop, defaulting to `http`. */
|
|
408
408
|
private scheme;
|
|
409
409
|
/**
|
|
410
|
-
* Whether the request arrived over HTTPS
|
|
410
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
411
411
|
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
412
412
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
413
413
|
*/
|
|
414
414
|
isSecure(): boolean;
|
|
415
415
|
/**
|
|
416
|
-
* The full URL including the query string
|
|
416
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
417
417
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
418
418
|
* The `$request->fullUrl()` equivalent.
|
|
419
419
|
*/
|
|
@@ -431,7 +431,7 @@ declare class Request {
|
|
|
431
431
|
/** Reassemble the full URL from the current scheme/host/path plus an edited query bag. */
|
|
432
432
|
private rebuildFullUrl;
|
|
433
433
|
/**
|
|
434
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
434
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
435
435
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
436
436
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
437
437
|
*/
|
|
@@ -476,7 +476,7 @@ declare class Request {
|
|
|
476
476
|
/** Every merged-input key. The `$request->keys()` equivalent. */
|
|
477
477
|
keys(): string[];
|
|
478
478
|
/**
|
|
479
|
-
* Read an input value coerced to a boolean
|
|
479
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
480
480
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
481
481
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
482
482
|
*/
|
|
@@ -494,7 +494,7 @@ declare class Request {
|
|
|
494
494
|
float(key: string, def?: number): number;
|
|
495
495
|
/**
|
|
496
496
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
497
|
-
* is returned. The `$request->string()` equivalent
|
|
497
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
498
498
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
499
499
|
* helpers if needed.
|
|
500
500
|
*/
|
|
@@ -588,7 +588,7 @@ declare class Request {
|
|
|
588
588
|
allFiles(): Record<string, UploadedFile | UploadedFile[]>;
|
|
589
589
|
/**
|
|
590
590
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
591
|
-
* parsed artifact
|
|
591
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
592
592
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
593
593
|
* bound models, merged input) are copied.
|
|
594
594
|
*/
|
|
@@ -605,7 +605,7 @@ declare class Request {
|
|
|
605
605
|
*/
|
|
606
606
|
withParams(params: Record<string, string>): Request;
|
|
607
607
|
/**
|
|
608
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
608
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
609
609
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
610
610
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
611
611
|
*/
|
|
@@ -613,7 +613,7 @@ declare class Request {
|
|
|
613
613
|
/** Read a middleware-attached attribute, or `undefined` when absent. */
|
|
614
614
|
attribute<T = unknown>(key: string): T | undefined;
|
|
615
615
|
/**
|
|
616
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
616
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
617
617
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
618
618
|
* by reference), so the original request is untouched.
|
|
619
619
|
*/
|
|
@@ -636,7 +636,7 @@ declare class Request {
|
|
|
636
636
|
}
|
|
637
637
|
|
|
638
638
|
/**
|
|
639
|
-
* HTTP exceptions and the exception handler
|
|
639
|
+
* HTTP exceptions and the exception handler - the conventional
|
|
640
640
|
* `Symfony\Component\HttpKernel\Exception\HttpException` family plus
|
|
641
641
|
* `App\Exceptions\Handler`. {@link HttpException} carries a status code; {@link ExceptionHandler}
|
|
642
642
|
* renders any thrown error into a {@link Response}, negotiating JSON vs. HTML from the request.
|
|
@@ -645,14 +645,14 @@ declare class Request {
|
|
|
645
645
|
/**
|
|
646
646
|
* Container token for the application's {@link ExceptionHandler}. Bind a custom handler under this
|
|
647
647
|
* token and {@link HttpKernel} resolves and
|
|
648
|
-
* uses it
|
|
648
|
+
* uses it - `app.singleton(EXCEPTION_HANDLER, () => new MyHandler())`. A symbol token (rather than
|
|
649
649
|
* the {@link ExceptionHandler} class itself) keeps the binding key decoupled, so an app may bind any
|
|
650
650
|
* handler shape without the class participating as a key.
|
|
651
651
|
*/
|
|
652
652
|
declare const EXCEPTION_HANDLER: symbol;
|
|
653
653
|
/**
|
|
654
654
|
* A reportable callback registered via {@link ExceptionHandler.reportable}. Returning `false` halts
|
|
655
|
-
* further reporting of that error (no later reportable callbacks and no default sink run)
|
|
655
|
+
* further reporting of that error (no later reportable callbacks and no default sink run) - the
|
|
656
656
|
* `reportable(fn)->stop()` / `return false` convention. Any other return (including
|
|
657
657
|
* returning nothing) lets reporting continue; the return is `unknown` so void callbacks fit too.
|
|
658
658
|
*/
|
|
@@ -663,9 +663,9 @@ type ReportableCallback = (error: unknown) => unknown;
|
|
|
663
663
|
* to the next renderable, then the default rendering.
|
|
664
664
|
*/
|
|
665
665
|
type RenderableCallback = (error: unknown, request?: Request) => Response | undefined;
|
|
666
|
-
/** The terminal report destination
|
|
666
|
+
/** The terminal report destination - where un-stopped errors are sent. The settable log seam. */
|
|
667
667
|
type ReportSink = (error: unknown, context: Record<string, unknown>) => void;
|
|
668
|
-
/** The log severities an exception may be reported at
|
|
668
|
+
/** The log severities an exception may be reported at - the PSR-3 / `level()` levels. */
|
|
669
669
|
type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
|
|
670
670
|
/** A base HTTP error carrying a status code. The `HttpException` equivalent. */
|
|
671
671
|
declare class HttpException extends Error {
|
|
@@ -686,7 +686,7 @@ declare class MethodNotAllowedHttpException extends HttpException {
|
|
|
686
686
|
constructor(allowed?: string[], message?: string);
|
|
687
687
|
}
|
|
688
688
|
/**
|
|
689
|
-
* `ExceptionHandler`
|
|
689
|
+
* `ExceptionHandler` - renders a thrown error to a {@link Response}, the `App\Exceptions\Handler`
|
|
690
690
|
* equivalent. JSON when the request {@link Request.wantsJson wants JSON}, otherwise an HTML page.
|
|
691
691
|
* The handler is deterministic: it derives status and message from the error, never the clock.
|
|
692
692
|
*/
|
|
@@ -698,7 +698,7 @@ declare class ExceptionHandler {
|
|
|
698
698
|
private readonly renderCallbacks;
|
|
699
699
|
/**
|
|
700
700
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
701
|
-
* `instanceof` check, so every subclass
|
|
701
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
702
702
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
703
703
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
704
704
|
*/
|
|
@@ -712,7 +712,7 @@ declare class ExceptionHandler {
|
|
|
712
712
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
713
713
|
private readonly levels;
|
|
714
714
|
/**
|
|
715
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
715
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
716
716
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
717
717
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
718
718
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -734,7 +734,7 @@ declare class ExceptionHandler {
|
|
|
734
734
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
735
735
|
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
736
736
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
737
|
-
* registration order; the first `instanceof` match applies (once
|
|
737
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
738
738
|
* re-mapped). Chains.
|
|
739
739
|
*/
|
|
740
740
|
map<T>(from: Newable<T>, to: (error: T) => unknown): this;
|
|
@@ -748,7 +748,7 @@ declare class ExceptionHandler {
|
|
|
748
748
|
/** The log level `error` reports at: the first registered `instanceof` match, else `'error'`. */
|
|
749
749
|
levelFor(error: unknown): LogLevel;
|
|
750
750
|
/**
|
|
751
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
751
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
752
752
|
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
753
753
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
754
754
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
@@ -766,7 +766,7 @@ declare class ExceptionHandler {
|
|
|
766
766
|
* Add error constructors to the don't-report list. Matching is by `instanceof`, so a base class also suppresses its subclasses. Chains.
|
|
767
767
|
*/
|
|
768
768
|
ignore(...classes: Newable[]): this;
|
|
769
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
769
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
770
770
|
dontReport(...classes: Newable[]): this;
|
|
771
771
|
/** Remove error constructors from the don't-report list. */
|
|
772
772
|
stopIgnoring(...classes: Newable[]): this;
|
|
@@ -783,8 +783,8 @@ declare class ExceptionHandler {
|
|
|
783
783
|
context(): Record<string, unknown>;
|
|
784
784
|
/**
|
|
785
785
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
786
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
787
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
786
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
787
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
788
788
|
* terminal sink.
|
|
789
789
|
*/
|
|
790
790
|
report(error: unknown): void;
|
|
@@ -801,7 +801,7 @@ declare class ExceptionHandler {
|
|
|
801
801
|
}
|
|
802
802
|
|
|
803
803
|
/**
|
|
804
|
-
* Middleware
|
|
804
|
+
* Middleware - the conventional, API-driven HTTP middleware stack. A
|
|
805
805
|
* {@link Middleware} receives the {@link Request} and a `next` continuation, and either calls
|
|
806
806
|
* `next` (passing control inward) or returns a {@link Response} directly to short-circuit.
|
|
807
807
|
* {@link runMiddleware} composes a stack around a final handler; {@link isTerminable} /
|
|
@@ -846,7 +846,7 @@ declare function runMiddleware(req: Request, stack: MiddlewareEntry[], destinati
|
|
|
846
846
|
declare function terminateMiddleware(req: Request, res: Response, stack: readonly MiddlewareEntry[]): Promise<void>;
|
|
847
847
|
|
|
848
848
|
/**
|
|
849
|
-
* `Router`
|
|
849
|
+
* `Router` - registration and matching of HTTP routes, the conventional API
|
|
850
850
|
* equivalent. Routes carry a method set, a path pattern (`/users/{id}`, optional `{id?}`), an
|
|
851
851
|
* optional name, and per-route middleware. {@link Router.group} applies a shared prefix and
|
|
852
852
|
* middleware to everything registered inside it; {@link Router.match} resolves an inbound
|
|
@@ -874,18 +874,18 @@ type RouteHandlerClosure = (req: Request) => RouteResult | Promise<RouteResult>;
|
|
|
874
874
|
/** A controller action: a class plus the method name to invoke, resolved via the container. */
|
|
875
875
|
type ControllerAction = readonly [controller: Newable, method: string];
|
|
876
876
|
/**
|
|
877
|
-
* A single-action ("invokable") controller reference
|
|
877
|
+
* A single-action ("invokable") controller reference - a controller class on its own, or a
|
|
878
878
|
* one-element `[Controller]` tuple. The kernel resolves the instance via the container and calls its
|
|
879
879
|
* `__invoke` method.
|
|
880
880
|
*/
|
|
881
881
|
type InvokableAction = Newable | readonly [controller: Newable];
|
|
882
882
|
/**
|
|
883
883
|
* Either supported handler form: a closure, a `[Controller, method]` pair, or an
|
|
884
|
-
* {@link InvokableAction} (a controller class
|
|
884
|
+
* {@link InvokableAction} (a controller class - or `[Controller]` - whose `__invoke` is called).
|
|
885
885
|
*/
|
|
886
886
|
type RouteHandler = RouteHandlerClosure | ControllerAction | InvokableAction;
|
|
887
887
|
/**
|
|
888
|
-
* Resolves a route-bound parameter to a value (typically a model)
|
|
888
|
+
* Resolves a route-bound parameter to a value (typically a model) - the `Route::bind`
|
|
889
889
|
* resolver. May return synchronously or as a `Promise` (both covered by `unknown`); returning
|
|
890
890
|
* `null`/`undefined` makes the route a 404 (implicit-binding "not found").
|
|
891
891
|
*/
|
|
@@ -898,7 +898,7 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEA
|
|
|
898
898
|
*/
|
|
899
899
|
type WherePattern = string | RegExp;
|
|
900
900
|
/**
|
|
901
|
-
* A renderer the {@link Router} defers {@link Router.view} routes to
|
|
901
|
+
* A renderer the {@link Router} defers {@link Router.view} routes to - given the view name, the
|
|
902
902
|
* data bag, and the request, it produces the HTML string. The usual view-factory seam: `@plinthjs/http`
|
|
903
903
|
* has no templating, so the app (or `@plinthjs/view`-style package) installs one via
|
|
904
904
|
* {@link Router.renderViewsUsing} or the `viewRenderer` {@link RouterOptions construction option}.
|
|
@@ -908,7 +908,7 @@ type ViewRenderer = (view: string, data: Record<string, unknown>, req: Request)
|
|
|
908
908
|
interface RouteGroupOptions {
|
|
909
909
|
prefix?: string;
|
|
910
910
|
/**
|
|
911
|
-
* Parameter constraints applied to every route registered inside the group
|
|
911
|
+
* Parameter constraints applied to every route registered inside the group - the conventional
|
|
912
912
|
* `Route::group(['where' => [...]])` / group-level `pattern` equivalent. A route's own
|
|
913
913
|
* {@link Route.where} for the same parameter overrides the group's.
|
|
914
914
|
*/
|
|
@@ -937,7 +937,7 @@ type RouteMatch = {
|
|
|
937
937
|
readonly type: 'not-found';
|
|
938
938
|
};
|
|
939
939
|
/**
|
|
940
|
-
* A single route in a {@link RouteCache} snapshot
|
|
940
|
+
* A single route in a {@link RouteCache} snapshot - a plain, JSON-serializable description of a
|
|
941
941
|
* registered route. The handler is recorded as a `[controllerName, method]` pair (closures cannot
|
|
942
942
|
* be serialized; see {@link Router.toCache}), and middleware are recorded by name only.
|
|
943
943
|
*/
|
|
@@ -946,12 +946,12 @@ interface CachedRoute {
|
|
|
946
946
|
readonly path: string;
|
|
947
947
|
readonly name: string | undefined;
|
|
948
948
|
readonly domain: string | undefined;
|
|
949
|
-
/** Middleware names (function/class names)
|
|
949
|
+
/** Middleware names (function/class names) - recorded for inspection and optional rehydration. */
|
|
950
950
|
readonly middleware: readonly string[];
|
|
951
951
|
/** The controller class name and method invoked for this route. */
|
|
952
952
|
readonly action: readonly [controller: string, method: string];
|
|
953
953
|
}
|
|
954
|
-
/** A JSON-serializable snapshot of a {@link Router}'s routes
|
|
954
|
+
/** A JSON-serializable snapshot of a {@link Router}'s routes - the `route:cache` artifact. */
|
|
955
955
|
interface RouteCache {
|
|
956
956
|
readonly routes: readonly CachedRoute[];
|
|
957
957
|
}
|
|
@@ -970,7 +970,7 @@ interface LoadCacheOptions {
|
|
|
970
970
|
*/
|
|
971
971
|
middleware?: MiddlewareResolver;
|
|
972
972
|
}
|
|
973
|
-
/** Why a signature failed to validate, or `'valid'`
|
|
973
|
+
/** Why a signature failed to validate, or `'valid'` - surfaced by {@link Router.validateSignature}. */
|
|
974
974
|
type SignatureResult = 'valid' | 'missing' | 'invalid' | 'expired';
|
|
975
975
|
/** A single registered route. Builder methods ({@link Route.name}, {@link Route.middleware}) chain. */
|
|
976
976
|
declare class Route {
|
|
@@ -1032,7 +1032,7 @@ declare class Route {
|
|
|
1032
1032
|
*/
|
|
1033
1033
|
middleware(...entries: MiddlewareReference[]): this;
|
|
1034
1034
|
/**
|
|
1035
|
-
* The middleware stack for this route (a copy), as registered
|
|
1035
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
1036
1036
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
1037
1037
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
1038
1038
|
*/
|
|
@@ -1083,12 +1083,12 @@ interface ResourceContext {
|
|
|
1083
1083
|
readonly where: Record<string, WherePattern>;
|
|
1084
1084
|
}
|
|
1085
1085
|
/**
|
|
1086
|
-
* A pending resource-route registration
|
|
1086
|
+
* A pending resource-route registration - the builder returned by {@link Router.resource} /
|
|
1087
1087
|
* {@link Router.apiResource}, the `PendingResourceRegistration` equivalent. Routes are not
|
|
1088
1088
|
* created when this is returned; instead the registration is **deferred** and finalized (built into
|
|
1089
1089
|
* real {@link Route}s) the first time the owning {@link Router} is matched, enumerated, has a named
|
|
1090
1090
|
* URL generated, or is cached. This lets `.only()` / `.except()` / `.names()` / `.parameters()` /
|
|
1091
|
-
* `.shallow()` be chained after the call and still take effect
|
|
1091
|
+
* `.shallow()` be chained after the call and still take effect - each just narrows/renames config,
|
|
1092
1092
|
* then returns `this`. The group prefix/middleware/domain in force when {@link Router.resource} was
|
|
1093
1093
|
* called are captured up-front, so deferred building still honors the enclosing group.
|
|
1094
1094
|
*
|
|
@@ -1133,7 +1133,7 @@ declare class ResourceRegistration {
|
|
|
1133
1133
|
/** The singleton-resource methods. */
|
|
1134
1134
|
type SingletonMethod = 'show' | 'edit' | 'update' | 'destroy';
|
|
1135
1135
|
/**
|
|
1136
|
-
* A pending singleton-resource registration
|
|
1136
|
+
* A pending singleton-resource registration - the builder returned by {@link Router.singleton} /
|
|
1137
1137
|
* {@link Router.apiSingleton}, the `PendingSingletonResourceRegistration` equivalent. A
|
|
1138
1138
|
* singleton resource has exactly one instance per context (a profile, a thumbnail), so no `index`,
|
|
1139
1139
|
* `create`/`store`, or `{param}` segment is registered:
|
|
@@ -1192,7 +1192,7 @@ declare class Router {
|
|
|
1192
1192
|
/** Register a route for an explicit set of verbs. The `Route::match()` equivalent. */
|
|
1193
1193
|
on(methods: HttpMethod[], path: string, handler: RouteHandler): Route;
|
|
1194
1194
|
/**
|
|
1195
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
1195
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
1196
1196
|
* plugs its template engine into. Chains.
|
|
1197
1197
|
*/
|
|
1198
1198
|
renderViewsUsing(renderer: ViewRenderer): this;
|
|
@@ -1240,7 +1240,7 @@ declare class Router {
|
|
|
1240
1240
|
/** Shared builder for {@link Router.resource} / {@link Router.apiResource}. */
|
|
1241
1241
|
private registerResource;
|
|
1242
1242
|
/**
|
|
1243
|
-
* Register a singleton resource
|
|
1243
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
1244
1244
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
1245
1245
|
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
1246
1246
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
@@ -1273,14 +1273,14 @@ declare class Router {
|
|
|
1273
1273
|
/** The binding resolver registered for `key`, if any. */
|
|
1274
1274
|
binding(key: string): BindingResolver | undefined;
|
|
1275
1275
|
/**
|
|
1276
|
-
* Register a named middleware *group*
|
|
1276
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
1277
1277
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
1278
1278
|
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
1279
1279
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
1280
1280
|
*/
|
|
1281
1281
|
middlewareGroup(name: string, entries: MiddlewareReference[]): this;
|
|
1282
1282
|
/**
|
|
1283
|
-
* Register a middleware *alias*
|
|
1283
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
1284
1284
|
*
|
|
1285
1285
|
* Re-registering a name replaces it.
|
|
1286
1286
|
*/
|
|
@@ -1295,7 +1295,7 @@ declare class Router {
|
|
|
1295
1295
|
/**
|
|
1296
1296
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
1297
1297
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
1298
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
1298
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
1299
1299
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
1300
1300
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
1301
1301
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -1308,7 +1308,7 @@ declare class Router {
|
|
|
1308
1308
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
1309
1309
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
1310
1310
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
1311
|
-
* sibling branches
|
|
1311
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
1312
1312
|
*/
|
|
1313
1313
|
private expandMiddleware;
|
|
1314
1314
|
/** Every registered route (a copy). Pending resource registrations are materialized first. */
|
|
@@ -1317,8 +1317,8 @@ declare class Router {
|
|
|
1317
1317
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
1318
1318
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
1319
1319
|
*
|
|
1320
|
-
* Closures cannot be serialized. Mirroring the conventional `route:cache`
|
|
1321
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
1320
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
1321
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
1322
1322
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
1323
1323
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
1324
1324
|
*/
|
|
@@ -1386,7 +1386,7 @@ declare class Router {
|
|
|
1386
1386
|
}
|
|
1387
1387
|
|
|
1388
1388
|
/**
|
|
1389
|
-
* `HttpKernel`
|
|
1389
|
+
* `HttpKernel` - the request lifecycle.
|
|
1390
1390
|
* {@link HttpKernel.handle} runs a request through the global middleware stack, matches it against
|
|
1391
1391
|
* the {@link Router}, runs any route middleware, invokes the handler (resolving controller classes
|
|
1392
1392
|
* through the `@plinthjs/core` container), and coerces the result to a {@link Response}.
|
|
@@ -1441,7 +1441,7 @@ declare class HttpKernel {
|
|
|
1441
1441
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
1442
1442
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
1443
1443
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
1444
|
-
* ({@link sameReferences}
|
|
1444
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
1445
1445
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
1446
1446
|
* mutable router registries and must be re-resolved each dispatch.
|
|
1447
1447
|
*/
|
|
@@ -1525,15 +1525,15 @@ interface GracefulShutdownOptions {
|
|
|
1525
1525
|
signals?: readonly NodeJS.Signals[];
|
|
1526
1526
|
/** Milliseconds to wait for in-flight requests before forcing exit. Default `10000`. */
|
|
1527
1527
|
timeout?: number;
|
|
1528
|
-
/** Run after the server stops accepting and before exit
|
|
1528
|
+
/** Run after the server stops accepting and before exit - close DB pools, flush logs, etc. */
|
|
1529
1529
|
onShutdown?: () => void | Promise<void>;
|
|
1530
1530
|
/** Exit hook (override in tests). Default `process.exit`. */
|
|
1531
1531
|
exit?: (code: number) => void;
|
|
1532
1532
|
}
|
|
1533
1533
|
/**
|
|
1534
|
-
* Drain and stop a server on a termination signal
|
|
1534
|
+
* Drain and stop a server on a termination signal - the production lifecycle Node needs (k8s/systemd
|
|
1535
1535
|
* send `SIGTERM` on a rolling deploy). Stops accepting new connections, lets in-flight requests
|
|
1536
|
-
* finish (up to `timeout`), runs `onShutdown` (close the DB, etc.), then exits 0
|
|
1536
|
+
* finish (up to `timeout`), runs `onShutdown` (close the DB, etc.), then exits 0 - or exits 1 if the
|
|
1537
1537
|
* drain times out. Returns an unsubscribe function that removes the signal handlers.
|
|
1538
1538
|
*/
|
|
1539
1539
|
declare function gracefulShutdown(server: Server, options?: GracefulShutdownOptions): () => void;
|
|
@@ -1555,7 +1555,7 @@ interface SecurityHeadersOptions {
|
|
|
1555
1555
|
referrerPolicy?: string | false;
|
|
1556
1556
|
}
|
|
1557
1557
|
/**
|
|
1558
|
-
* Attach baseline security response headers
|
|
1558
|
+
* Attach baseline security response headers - the helmet-style defaults a server-rendered app should
|
|
1559
1559
|
* always set: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, and optionally HSTS.
|
|
1560
1560
|
* Existing headers are never overwritten, so a route can opt out per response.
|
|
1561
1561
|
*/
|
|
@@ -1576,11 +1576,11 @@ interface CorsOptions {
|
|
|
1576
1576
|
maxAge?: number;
|
|
1577
1577
|
}
|
|
1578
1578
|
/**
|
|
1579
|
-
* Cross-Origin Resource Sharing
|
|
1579
|
+
* Cross-Origin Resource Sharing - the `HandleCors` equivalent for API stacks. Answers preflight
|
|
1580
1580
|
* `OPTIONS` with the negotiated headers and stamps actual responses with `Access-Control-Allow-*`.
|
|
1581
1581
|
*/
|
|
1582
1582
|
declare function cors(options?: CorsOptions): Middleware;
|
|
1583
|
-
/** The rate-limiter surface {@link throttle} needs
|
|
1583
|
+
/** The rate-limiter surface {@link throttle} needs - `@plinthjs/rate-limiter`'s `RateLimiter` fits by shape. */
|
|
1584
1584
|
interface RateLimiterSeam {
|
|
1585
1585
|
/** Record one hit against `key`, expiring after `decaySeconds`; returns the new count. */
|
|
1586
1586
|
hit(key: string, decaySeconds?: number): number;
|
|
@@ -1601,19 +1601,19 @@ interface ThrottleOptions {
|
|
|
1601
1601
|
key?: (req: Request) => string;
|
|
1602
1602
|
}
|
|
1603
1603
|
/**
|
|
1604
|
-
* Rate-limit requests
|
|
1604
|
+
* Rate-limit requests - the `throttle:max,minutes` middleware. Over the limit, responds
|
|
1605
1605
|
* `429 Too Many Requests` with a `Retry-After` header; otherwise records a hit and continues. Key by
|
|
1606
1606
|
* ip+route by default; pass `key` to scope it (e.g. by login email).
|
|
1607
1607
|
*/
|
|
1608
1608
|
declare function throttle(options: ThrottleOptions): Middleware;
|
|
1609
1609
|
|
|
1610
1610
|
/**
|
|
1611
|
-
* @plinthjs/http
|
|
1611
|
+
* @plinthjs/http - the conventional API and its supporting layer (Tier 3).
|
|
1612
1612
|
*
|
|
1613
|
-
* The {@link Request} / {@link Response} value objects
|
|
1613
|
+
* The {@link Request} / {@link Response} value objects - including response macros
|
|
1614
1614
|
* ({@link Response.macro}), redirect helpers with flash intent ({@link Response.redirectTo} /
|
|
1615
1615
|
* {@link Response.with}), and file/download builders ({@link Response.file} /
|
|
1616
|
-
* {@link Response.download})
|
|
1616
|
+
* {@link Response.download}) - the async middleware pipeline ({@link Middleware} /
|
|
1617
1617
|
* {@link runMiddleware}, with {@link TerminableMiddleware} support), the HTTP exception hierarchy
|
|
1618
1618
|
* ({@link HttpException} and friends) and its {@link ExceptionHandler}, the {@link Router} (params,
|
|
1619
1619
|
* optional params, groups, named routes + URL generation, signed URLs via {@link Router.signedUrl},
|