@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.js
CHANGED
|
@@ -189,7 +189,7 @@ var Response = class _Response {
|
|
|
189
189
|
/**
|
|
190
190
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
191
191
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
192
|
-
* client as it yields
|
|
192
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
193
193
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
194
194
|
* responses via {@link Response.writeStreamTo}.
|
|
195
195
|
*/
|
|
@@ -212,7 +212,7 @@ var Response = class _Response {
|
|
|
212
212
|
});
|
|
213
213
|
}
|
|
214
214
|
/**
|
|
215
|
-
* Build a streamed JSON response
|
|
215
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
216
216
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
217
217
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
218
218
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -228,7 +228,7 @@ var Response = class _Response {
|
|
|
228
228
|
}
|
|
229
229
|
// --- Macros (the `Response::macro` extension point) -----------------------
|
|
230
230
|
/**
|
|
231
|
-
* Register a reusable response builder under `name`. The `Response::macro()` equivalent
|
|
231
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
232
232
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
233
233
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
234
234
|
*/
|
|
@@ -362,7 +362,7 @@ var Response = class _Response {
|
|
|
362
362
|
/**
|
|
363
363
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
364
364
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
365
|
-
* {@link Response.writeStreamTo} instead
|
|
365
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
366
366
|
* silently dropped.
|
|
367
367
|
*/
|
|
368
368
|
writeTo(res) {
|
|
@@ -449,7 +449,7 @@ var ExceptionHandler = class {
|
|
|
449
449
|
renderCallbacks = [];
|
|
450
450
|
/**
|
|
451
451
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
452
|
-
* `instanceof` check, so every subclass
|
|
452
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
453
453
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
454
454
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
455
455
|
*/
|
|
@@ -464,7 +464,7 @@ var ExceptionHandler = class {
|
|
|
464
464
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
465
465
|
levels = [];
|
|
466
466
|
/**
|
|
467
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
467
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
468
468
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
469
469
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
470
470
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -485,7 +485,7 @@ var ExceptionHandler = class {
|
|
|
485
485
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
486
486
|
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
487
487
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
488
|
-
* registration order; the first `instanceof` match applies (once
|
|
488
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
489
489
|
* re-mapped). Chains.
|
|
490
490
|
*/
|
|
491
491
|
map(from, to) {
|
|
@@ -515,7 +515,7 @@ var ExceptionHandler = class {
|
|
|
515
515
|
return "error";
|
|
516
516
|
}
|
|
517
517
|
/**
|
|
518
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
518
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
519
519
|
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
520
520
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
521
521
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
@@ -545,7 +545,7 @@ var ExceptionHandler = class {
|
|
|
545
545
|
this.ignored.push(...classes);
|
|
546
546
|
return this;
|
|
547
547
|
}
|
|
548
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
548
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
549
549
|
dontReport(...classes) {
|
|
550
550
|
return this.ignore(...classes);
|
|
551
551
|
}
|
|
@@ -583,8 +583,8 @@ var ExceptionHandler = class {
|
|
|
583
583
|
}
|
|
584
584
|
/**
|
|
585
585
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
586
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
587
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
586
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
587
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
588
588
|
* terminal sink.
|
|
589
589
|
*/
|
|
590
590
|
report(error) {
|
|
@@ -781,7 +781,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
781
781
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
782
782
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
783
783
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
784
|
-
* ({@link sameReferences}
|
|
784
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
785
785
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
786
786
|
* mutable router registries and must be re-resolved each dispatch.
|
|
787
787
|
*/
|
|
@@ -972,7 +972,7 @@ var UploadedFile = class {
|
|
|
972
972
|
get() {
|
|
973
973
|
return this.content;
|
|
974
974
|
}
|
|
975
|
-
/** The raw uploaded bytes
|
|
975
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
976
976
|
buffer() {
|
|
977
977
|
return this.content;
|
|
978
978
|
}
|
|
@@ -996,7 +996,7 @@ var UploadedFile = class {
|
|
|
996
996
|
return this.size;
|
|
997
997
|
}
|
|
998
998
|
/**
|
|
999
|
-
* Whether the upload is valid
|
|
999
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
1000
1000
|
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
1001
1001
|
*/
|
|
1002
1002
|
isValid() {
|
|
@@ -1019,7 +1019,7 @@ var UploadedFile = class {
|
|
|
1019
1019
|
}
|
|
1020
1020
|
/**
|
|
1021
1021
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
1022
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
1022
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
1023
1023
|
*/
|
|
1024
1024
|
move(destination) {
|
|
1025
1025
|
mkdirSync(path2.dirname(destination), { recursive: true });
|
|
@@ -1027,7 +1027,7 @@ var UploadedFile = class {
|
|
|
1027
1027
|
return destination;
|
|
1028
1028
|
}
|
|
1029
1029
|
/**
|
|
1030
|
-
* A unique storage filename preserving the original extension
|
|
1030
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
1031
1031
|
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
1032
1032
|
*/
|
|
1033
1033
|
hashName() {
|
|
@@ -1119,7 +1119,7 @@ var Request = class _Request {
|
|
|
1119
1119
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
1120
1120
|
_pathname;
|
|
1121
1121
|
_host;
|
|
1122
|
-
/** The host as received (port included, if any)
|
|
1122
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
1123
1123
|
_httpHost;
|
|
1124
1124
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
1125
1125
|
_routeName;
|
|
@@ -1327,7 +1327,7 @@ var Request = class _Request {
|
|
|
1327
1327
|
return this._httpHost;
|
|
1328
1328
|
}
|
|
1329
1329
|
/**
|
|
1330
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
1330
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
1331
1331
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
1332
1332
|
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
1333
1333
|
* `undefined` when no host is known.
|
|
@@ -1346,7 +1346,7 @@ var Request = class _Request {
|
|
|
1346
1346
|
return "http";
|
|
1347
1347
|
}
|
|
1348
1348
|
/**
|
|
1349
|
-
* Whether the request arrived over HTTPS
|
|
1349
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
1350
1350
|
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
1351
1351
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
1352
1352
|
*/
|
|
@@ -1354,7 +1354,7 @@ var Request = class _Request {
|
|
|
1354
1354
|
return this.scheme() === "https";
|
|
1355
1355
|
}
|
|
1356
1356
|
/**
|
|
1357
|
-
* The full URL including the query string
|
|
1357
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
1358
1358
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
1359
1359
|
* The `$request->fullUrl()` equivalent.
|
|
1360
1360
|
*/
|
|
@@ -1388,7 +1388,7 @@ var Request = class _Request {
|
|
|
1388
1388
|
}
|
|
1389
1389
|
// --- Path / route matching (the `is()` family, `*` wildcards) --------------
|
|
1390
1390
|
/**
|
|
1391
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
1391
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
1392
1392
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
1393
1393
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
1394
1394
|
*/
|
|
@@ -1479,7 +1479,7 @@ var Request = class _Request {
|
|
|
1479
1479
|
return Object.keys(this.all());
|
|
1480
1480
|
}
|
|
1481
1481
|
/**
|
|
1482
|
-
* Read an input value coerced to a boolean
|
|
1482
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
1483
1483
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
1484
1484
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
1485
1485
|
*/
|
|
@@ -1511,7 +1511,7 @@ var Request = class _Request {
|
|
|
1511
1511
|
}
|
|
1512
1512
|
/**
|
|
1513
1513
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
1514
|
-
* is returned. The `$request->string()` equivalent
|
|
1514
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
1515
1515
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
1516
1516
|
* helpers if needed.
|
|
1517
1517
|
*/
|
|
@@ -1736,7 +1736,7 @@ var Request = class _Request {
|
|
|
1736
1736
|
// --- Route parameters ----------------------------------------------------
|
|
1737
1737
|
/**
|
|
1738
1738
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
1739
|
-
* parsed artifact
|
|
1739
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
1740
1740
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
1741
1741
|
* bound models, merged input) are copied.
|
|
1742
1742
|
*/
|
|
@@ -1780,7 +1780,7 @@ var Request = class _Request {
|
|
|
1780
1780
|
return clone;
|
|
1781
1781
|
}
|
|
1782
1782
|
/**
|
|
1783
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
1783
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
1784
1784
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
1785
1785
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
1786
1786
|
*/
|
|
@@ -1795,7 +1795,7 @@ var Request = class _Request {
|
|
|
1795
1795
|
return this._attributes.get(key);
|
|
1796
1796
|
}
|
|
1797
1797
|
/**
|
|
1798
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
1798
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
1799
1799
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
1800
1800
|
* by reference), so the original request is untouched.
|
|
1801
1801
|
*/
|
|
@@ -2074,7 +2074,7 @@ var Route = class {
|
|
|
2074
2074
|
return this;
|
|
2075
2075
|
}
|
|
2076
2076
|
/**
|
|
2077
|
-
* The middleware stack for this route (a copy), as registered
|
|
2077
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
2078
2078
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
2079
2079
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
2080
2080
|
*/
|
|
@@ -2346,7 +2346,7 @@ var Router = class _Router {
|
|
|
2346
2346
|
}
|
|
2347
2347
|
// --- Convenience routes (the `Route::view` / `Route::redirect` family) -----
|
|
2348
2348
|
/**
|
|
2349
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
2349
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
2350
2350
|
* plugs its template engine into. Chains.
|
|
2351
2351
|
*/
|
|
2352
2352
|
renderViewsUsing(renderer) {
|
|
@@ -2428,7 +2428,7 @@ var Router = class _Router {
|
|
|
2428
2428
|
return registration;
|
|
2429
2429
|
}
|
|
2430
2430
|
/**
|
|
2431
|
-
* Register a singleton resource
|
|
2431
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
2432
2432
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
2433
2433
|
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2434
2434
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
@@ -2512,7 +2512,7 @@ var Router = class _Router {
|
|
|
2512
2512
|
}
|
|
2513
2513
|
// --- Middleware groups + aliases (the `$middlewareGroups` / `$middlewareAliases` family) ------
|
|
2514
2514
|
/**
|
|
2515
|
-
* Register a named middleware *group*
|
|
2515
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
2516
2516
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
2517
2517
|
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
2518
2518
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
@@ -2522,7 +2522,7 @@ var Router = class _Router {
|
|
|
2522
2522
|
return this;
|
|
2523
2523
|
}
|
|
2524
2524
|
/**
|
|
2525
|
-
* Register a middleware *alias*
|
|
2525
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
2526
2526
|
*
|
|
2527
2527
|
* Re-registering a name replaces it.
|
|
2528
2528
|
*/
|
|
@@ -2545,7 +2545,7 @@ var Router = class _Router {
|
|
|
2545
2545
|
/**
|
|
2546
2546
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
2547
2547
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
2548
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
2548
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
2549
2549
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
2550
2550
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
2551
2551
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -2560,7 +2560,7 @@ var Router = class _Router {
|
|
|
2560
2560
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
2561
2561
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
2562
2562
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
2563
|
-
* sibling branches
|
|
2563
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
2564
2564
|
*/
|
|
2565
2565
|
expandMiddleware(references, groupPath) {
|
|
2566
2566
|
const resolved = [];
|
|
@@ -2600,8 +2600,8 @@ var Router = class _Router {
|
|
|
2600
2600
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
2601
2601
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
2602
2602
|
*
|
|
2603
|
-
* Closures cannot be serialized. Mirroring the conventional `route:cache`
|
|
2604
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
2603
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
2604
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
2605
2605
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
2606
2606
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
2607
2607
|
*/
|