@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.cjs
CHANGED
|
@@ -195,7 +195,7 @@ var Response = class _Response {
|
|
|
195
195
|
/**
|
|
196
196
|
* Build a streamed response: `source` (an iterable, async iterable, or a generator/factory
|
|
197
197
|
* returning one) is consumed chunk by chunk as the response is flushed, each chunk written to the
|
|
198
|
-
* client as it yields
|
|
198
|
+
* client as it yields - the `response()->stream()` equivalent. No `Content-Length` is set, so
|
|
199
199
|
* Node serves it with chunked transfer encoding. The kernel/server adapter flushes streamed
|
|
200
200
|
* responses via {@link Response.writeStreamTo}.
|
|
201
201
|
*/
|
|
@@ -218,7 +218,7 @@ var Response = class _Response {
|
|
|
218
218
|
});
|
|
219
219
|
}
|
|
220
220
|
/**
|
|
221
|
-
* Build a streamed JSON response
|
|
221
|
+
* Build a streamed JSON response - the `response()->streamJson()` equivalent. An iterable (or
|
|
222
222
|
* async iterable) of rows is streamed as one JSON array, each row serialized as it yields; an
|
|
223
223
|
* object is emitted key by key with iterable values streamed as arrays and plain values encoded
|
|
224
224
|
* in place. Useful for serializing large result sets without buffering them.
|
|
@@ -234,7 +234,7 @@ var Response = class _Response {
|
|
|
234
234
|
}
|
|
235
235
|
// --- Macros (the `Response::macro` extension point) -----------------------
|
|
236
236
|
/**
|
|
237
|
-
* Register a reusable response builder under `name`. The `Response::macro()` equivalent
|
|
237
|
+
* Register a reusable response builder under `name`. The `Response::macro()` equivalent -
|
|
238
238
|
* application code installs a named factory once and invokes it via {@link Response.callMacro}
|
|
239
239
|
* (`Response.callMacro('caps', text)`). Re-registering a name overwrites the previous macro.
|
|
240
240
|
*/
|
|
@@ -368,7 +368,7 @@ var Response = class _Response {
|
|
|
368
368
|
/**
|
|
369
369
|
* Flush this response to a Node {@link ServerResponse}: status, headers, cookies, then body.
|
|
370
370
|
* Streamed responses ({@link Response.stream}) must be flushed with the async
|
|
371
|
-
* {@link Response.writeStreamTo} instead
|
|
371
|
+
* {@link Response.writeStreamTo} instead - calling `writeTo` on one throws so a stream is never
|
|
372
372
|
* silently dropped.
|
|
373
373
|
*/
|
|
374
374
|
writeTo(res) {
|
|
@@ -455,7 +455,7 @@ var ExceptionHandler = class {
|
|
|
455
455
|
renderCallbacks = [];
|
|
456
456
|
/**
|
|
457
457
|
* Error constructors whose instances are not reported. Seeded with {@link HttpException} (an
|
|
458
|
-
* `instanceof` check, so every subclass
|
|
458
|
+
* `instanceof` check, so every subclass - 404/405/… - is covered too), following the usual small
|
|
459
459
|
* internal don't-report list. Extend with {@link ExceptionHandler.ignore} / shrink with
|
|
460
460
|
* {@link ExceptionHandler.stopIgnoring}.
|
|
461
461
|
*/
|
|
@@ -470,7 +470,7 @@ var ExceptionHandler = class {
|
|
|
470
470
|
/** Per-constructor log levels consulted by {@link ExceptionHandler.levelFor}. */
|
|
471
471
|
levels = [];
|
|
472
472
|
/**
|
|
473
|
-
* Input keys never flashed back to the session on a validation redirect
|
|
473
|
+
* Input keys never flashed back to the session on a validation redirect - the conventional
|
|
474
474
|
* `$dontFlash` list, seeded with its defaults. `@plinthjs/http` itself has no redirect/flash path,
|
|
475
475
|
* so the list is stored here and exposed via {@link ExceptionHandler.getDontFlash} for the
|
|
476
476
|
* session/validation layer to consume when it re-flashes old input.
|
|
@@ -491,7 +491,7 @@ var ExceptionHandler = class {
|
|
|
491
491
|
* Map one exception type to another: whenever an instance of `from` reaches the handler, it is
|
|
492
492
|
* first converted via `to` and the *result* is reported and rendered instead. The conventional
|
|
493
493
|
* `$exceptions->map(From::class, fn ($e) => new To(..., $e))` equivalent. Mappings are checked in
|
|
494
|
-
* registration order; the first `instanceof` match applies (once
|
|
494
|
+
* registration order; the first `instanceof` match applies (once - the mapped error is not
|
|
495
495
|
* re-mapped). Chains.
|
|
496
496
|
*/
|
|
497
497
|
map(from, to) {
|
|
@@ -521,7 +521,7 @@ var ExceptionHandler = class {
|
|
|
521
521
|
return "error";
|
|
522
522
|
}
|
|
523
523
|
/**
|
|
524
|
-
* Replace the list of input keys that must never be flashed back on a validation redirect
|
|
524
|
+
* Replace the list of input keys that must never be flashed back on a validation redirect - the
|
|
525
525
|
* `$exceptions->dontFlash([...])` equivalent. Defaults to `current_password`, `password`,
|
|
526
526
|
* and `password_confirmation`. There is no redirect/flash path inside `@plinthjs/http`, so the list
|
|
527
527
|
* is exposed via {@link ExceptionHandler.getDontFlash} for the session/validation layer that
|
|
@@ -551,7 +551,7 @@ var ExceptionHandler = class {
|
|
|
551
551
|
this.ignored.push(...classes);
|
|
552
552
|
return this;
|
|
553
553
|
}
|
|
554
|
-
/** Alias of {@link ExceptionHandler.ignore}
|
|
554
|
+
/** Alias of {@link ExceptionHandler.ignore} - the `$dontReport` spelling. */
|
|
555
555
|
dontReport(...classes) {
|
|
556
556
|
return this.ignore(...classes);
|
|
557
557
|
}
|
|
@@ -589,8 +589,8 @@ var ExceptionHandler = class {
|
|
|
589
589
|
}
|
|
590
590
|
/**
|
|
591
591
|
* Report `error`: if {@link ExceptionHandler.shouldReport} and not a duplicate (when
|
|
592
|
-
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order
|
|
593
|
-
* `false` return stops the chain (the default sink is skipped)
|
|
592
|
+
* {@link ExceptionHandler.withoutDuplicates} is on), run the reportable callbacks in order - a
|
|
593
|
+
* `false` return stops the chain (the default sink is skipped) - otherwise fall through to the
|
|
594
594
|
* terminal sink.
|
|
595
595
|
*/
|
|
596
596
|
report(error) {
|
|
@@ -787,7 +787,7 @@ var HttpKernel = class _HttpKernel {
|
|
|
787
787
|
* The composed pipeline for `route` (its resolved middleware stack ending in the route action).
|
|
788
788
|
* Cached per route so alias/group resolution and closure composition happen once, not per
|
|
789
789
|
* request. A cached entry is reused only while the route's reference list is unchanged
|
|
790
|
-
* ({@link sameReferences}
|
|
790
|
+
* ({@link sameReferences} - `route.middleware(...)` can append after registration), and stacks
|
|
791
791
|
* containing `string` references are never cached: their alias/group registrations live in
|
|
792
792
|
* mutable router registries and must be re-resolved each dispatch.
|
|
793
793
|
*/
|
|
@@ -978,7 +978,7 @@ var UploadedFile = class {
|
|
|
978
978
|
get() {
|
|
979
979
|
return this.content;
|
|
980
980
|
}
|
|
981
|
-
/** The raw uploaded bytes
|
|
981
|
+
/** The raw uploaded bytes - an alias for {@link UploadedFile.get} reading more naturally as bytes. */
|
|
982
982
|
buffer() {
|
|
983
983
|
return this.content;
|
|
984
984
|
}
|
|
@@ -1002,7 +1002,7 @@ var UploadedFile = class {
|
|
|
1002
1002
|
return this.size;
|
|
1003
1003
|
}
|
|
1004
1004
|
/**
|
|
1005
|
-
* Whether the upload is valid
|
|
1005
|
+
* Whether the upload is valid - here, simply that it carries a non-empty filename. Mirrors the
|
|
1006
1006
|
* `$file->isValid()` predicate at this layer (no PHP upload-error codes exist in Node).
|
|
1007
1007
|
*/
|
|
1008
1008
|
isValid() {
|
|
@@ -1025,7 +1025,7 @@ var UploadedFile = class {
|
|
|
1025
1025
|
}
|
|
1026
1026
|
/**
|
|
1027
1027
|
* Write the upload to the exact file path `destination`, creating its parent directory as needed,
|
|
1028
|
-
* and return `destination`. The `$file->move()` equivalent
|
|
1028
|
+
* and return `destination`. The `$file->move()` equivalent - the documented filesystem seam.
|
|
1029
1029
|
*/
|
|
1030
1030
|
move(destination) {
|
|
1031
1031
|
fs.mkdirSync(path2__default.default.dirname(destination), { recursive: true });
|
|
@@ -1033,7 +1033,7 @@ var UploadedFile = class {
|
|
|
1033
1033
|
return destination;
|
|
1034
1034
|
}
|
|
1035
1035
|
/**
|
|
1036
|
-
* A unique storage filename preserving the original extension
|
|
1036
|
+
* A unique storage filename preserving the original extension - a timestamp/random base, the way
|
|
1037
1037
|
* the conventional `hashName()` produces a collision-resistant name. Used by {@link UploadedFile.store}.
|
|
1038
1038
|
*/
|
|
1039
1039
|
hashName() {
|
|
@@ -1125,7 +1125,7 @@ var Request = class _Request {
|
|
|
1125
1125
|
/** Memoized pathname; a {@link isPlainPath plain} target resolves by slicing, sparing `new URL`. */
|
|
1126
1126
|
_pathname;
|
|
1127
1127
|
_host;
|
|
1128
|
-
/** The host as received (port included, if any)
|
|
1128
|
+
/** The host as received (port included, if any) - backs {@link Request.httpHost}. */
|
|
1129
1129
|
_httpHost;
|
|
1130
1130
|
/** The matched route's name, attached by the kernel after a successful match (for `routeIs`). */
|
|
1131
1131
|
_routeName;
|
|
@@ -1333,7 +1333,7 @@ var Request = class _Request {
|
|
|
1333
1333
|
return this._httpHost;
|
|
1334
1334
|
}
|
|
1335
1335
|
/**
|
|
1336
|
-
* The scheme plus host (e.g. `https://acme.myapp.com:8080`)
|
|
1336
|
+
* The scheme plus host (e.g. `https://acme.myapp.com:8080`) - the `$request->schemeAndHttpHost()`
|
|
1337
1337
|
* equivalent. The scheme is read from the first `X-Forwarded-Proto` hop, defaulting to `http`
|
|
1338
1338
|
* (Plinth's adapter sits on plain `node:http`; a TLS-terminating proxy sets the header).
|
|
1339
1339
|
* `undefined` when no host is known.
|
|
@@ -1352,7 +1352,7 @@ var Request = class _Request {
|
|
|
1352
1352
|
return "http";
|
|
1353
1353
|
}
|
|
1354
1354
|
/**
|
|
1355
|
-
* Whether the request arrived over HTTPS
|
|
1355
|
+
* Whether the request arrived over HTTPS - the `$request->isSecure()` equivalent. Reads the first
|
|
1356
1356
|
* `X-Forwarded-Proto` hop (Plinth sits on plain `node:http` behind a TLS-terminating proxy), so it
|
|
1357
1357
|
* is the trust-proxy signal a `secure` cookie or HSTS header should gate on.
|
|
1358
1358
|
*/
|
|
@@ -1360,7 +1360,7 @@ var Request = class _Request {
|
|
|
1360
1360
|
return this.scheme() === "https";
|
|
1361
1361
|
}
|
|
1362
1362
|
/**
|
|
1363
|
-
* The full URL including the query string
|
|
1363
|
+
* The full URL including the query string - `scheme://host/path?query` when the host is known,
|
|
1364
1364
|
* otherwise just `/path?query` (matching {@link Request.url} for host-less synthetic requests).
|
|
1365
1365
|
* The `$request->fullUrl()` equivalent.
|
|
1366
1366
|
*/
|
|
@@ -1394,7 +1394,7 @@ var Request = class _Request {
|
|
|
1394
1394
|
}
|
|
1395
1395
|
// --- Path / route matching (the `is()` family, `*` wildcards) --------------
|
|
1396
1396
|
/**
|
|
1397
|
-
* Whether the request path matches any of the wildcard `patterns`
|
|
1397
|
+
* Whether the request path matches any of the wildcard `patterns` - `*` matches any run of
|
|
1398
1398
|
* characters. Patterns are matched against the path **without** its leading slash (so
|
|
1399
1399
|
* `req.is('admin/*')` matches `/admin/users`), mirroring `$request->is()`.
|
|
1400
1400
|
*/
|
|
@@ -1485,7 +1485,7 @@ var Request = class _Request {
|
|
|
1485
1485
|
return Object.keys(this.all());
|
|
1486
1486
|
}
|
|
1487
1487
|
/**
|
|
1488
|
-
* Read an input value coerced to a boolean
|
|
1488
|
+
* Read an input value coerced to a boolean - `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
|
|
1489
1489
|
* case-insensitive) are `true`, anything else `false`. When the key is absent, `def` (default
|
|
1490
1490
|
* `false`) is returned. The `$request->boolean()` equivalent.
|
|
1491
1491
|
*/
|
|
@@ -1517,7 +1517,7 @@ var Request = class _Request {
|
|
|
1517
1517
|
}
|
|
1518
1518
|
/**
|
|
1519
1519
|
* Read an input value coerced to a primitive string. When the key is absent, `def` (default `''`)
|
|
1520
|
-
* is returned. The `$request->string()` equivalent
|
|
1520
|
+
* is returned. The `$request->string()` equivalent - note this returns a primitive
|
|
1521
1521
|
* `string` rather than a `Stringable`; wrap it with `@plinthjs/support`'s `Str.of()` for fluent
|
|
1522
1522
|
* helpers if needed.
|
|
1523
1523
|
*/
|
|
@@ -1742,7 +1742,7 @@ var Request = class _Request {
|
|
|
1742
1742
|
// --- Route parameters ----------------------------------------------------
|
|
1743
1743
|
/**
|
|
1744
1744
|
* A structural copy carrying route parameters and attributes forward (kept immutable). Every
|
|
1745
|
-
* parsed artifact
|
|
1745
|
+
* parsed artifact - headers, URL memos, body buffer, parsed/multipart memos - is immutable once
|
|
1746
1746
|
* built, so clones share it by reference; only the per-clone bags (route params, attributes,
|
|
1747
1747
|
* bound models, merged input) are copied.
|
|
1748
1748
|
*/
|
|
@@ -1786,7 +1786,7 @@ var Request = class _Request {
|
|
|
1786
1786
|
return clone;
|
|
1787
1787
|
}
|
|
1788
1788
|
/**
|
|
1789
|
-
* Return a copy of this request with an arbitrary attribute attached
|
|
1789
|
+
* Return a copy of this request with an arbitrary attribute attached - the `$request->attributes`
|
|
1790
1790
|
* bag equivalent. Middleware use this to hand request-scoped values (the session, the
|
|
1791
1791
|
* authenticated user, …) to downstream handlers without mutating the original.
|
|
1792
1792
|
*/
|
|
@@ -1801,7 +1801,7 @@ var Request = class _Request {
|
|
|
1801
1801
|
return this._attributes.get(key);
|
|
1802
1802
|
}
|
|
1803
1803
|
/**
|
|
1804
|
-
* Return a copy of this request with `name` set to `value` (case-insensitive)
|
|
1804
|
+
* Return a copy of this request with `name` set to `value` (case-insensitive) - e.g. a `forceJson`
|
|
1805
1805
|
* middleware setting `Accept: application/json`. The header map is copied (clones normally share it
|
|
1806
1806
|
* by reference), so the original request is untouched.
|
|
1807
1807
|
*/
|
|
@@ -2080,7 +2080,7 @@ var Route = class {
|
|
|
2080
2080
|
return this;
|
|
2081
2081
|
}
|
|
2082
2082
|
/**
|
|
2083
|
-
* The middleware stack for this route (a copy), as registered
|
|
2083
|
+
* The middleware stack for this route (a copy), as registered - so `string` alias/group names are
|
|
2084
2084
|
* returned verbatim. The {@link Router} resolves these to concrete entries via
|
|
2085
2085
|
* {@link Router.resolveMiddleware} when dispatching a matched route.
|
|
2086
2086
|
*/
|
|
@@ -2352,7 +2352,7 @@ var Router = class _Router {
|
|
|
2352
2352
|
}
|
|
2353
2353
|
// --- Convenience routes (the `Route::view` / `Route::redirect` family) -----
|
|
2354
2354
|
/**
|
|
2355
|
-
* Install the renderer {@link Router.view} routes defer to
|
|
2355
|
+
* Install the renderer {@link Router.view} routes defer to - the seam an app (or a view package)
|
|
2356
2356
|
* plugs its template engine into. Chains.
|
|
2357
2357
|
*/
|
|
2358
2358
|
renderViewsUsing(renderer) {
|
|
@@ -2434,7 +2434,7 @@ var Router = class _Router {
|
|
|
2434
2434
|
return registration;
|
|
2435
2435
|
}
|
|
2436
2436
|
/**
|
|
2437
|
-
* Register a singleton resource
|
|
2437
|
+
* Register a singleton resource - routes for a resource with exactly one instance (a profile, a
|
|
2438
2438
|
* settings page), mapping `GET name` → `show`, `GET name/edit` → `edit`, and `PUT|PATCH name` →
|
|
2439
2439
|
* `update` (no `{param}` segment, no `index`/`create`/`store`). Chain {@link SingletonRegistration.destroyable} to add `DELETE name` → `destroy`.
|
|
2440
2440
|
* Registration is deferred exactly like {@link Router.resource}.
|
|
@@ -2518,7 +2518,7 @@ var Router = class _Router {
|
|
|
2518
2518
|
}
|
|
2519
2519
|
// --- Middleware groups + aliases (the `$middlewareGroups` / `$middlewareAliases` family) ------
|
|
2520
2520
|
/**
|
|
2521
|
-
* Register a named middleware *group*
|
|
2521
|
+
* Register a named middleware *group* - a list of references (concrete entries and/or other
|
|
2522
2522
|
* alias/group names) that expand in place wherever the group name is used on a route or group. The
|
|
2523
2523
|
* `Route::middlewareGroup('web', [...])` equivalent. Re-registering a name replaces it.
|
|
2524
2524
|
* Names are resolved (recursively) at match time by {@link Router.resolveMiddleware}.
|
|
@@ -2528,7 +2528,7 @@ var Router = class _Router {
|
|
|
2528
2528
|
return this;
|
|
2529
2529
|
}
|
|
2530
2530
|
/**
|
|
2531
|
-
* Register a middleware *alias*
|
|
2531
|
+
* Register a middleware *alias* - a short `string` name for a single concrete {@link MiddlewareEntry}.
|
|
2532
2532
|
*
|
|
2533
2533
|
* Re-registering a name replaces it.
|
|
2534
2534
|
*/
|
|
@@ -2551,7 +2551,7 @@ var Router = class _Router {
|
|
|
2551
2551
|
/**
|
|
2552
2552
|
* Resolve a middleware reference list to concrete {@link MiddlewareEntry entries}, expanding
|
|
2553
2553
|
* `string` names: a name resolves first as an **alias** (→ its single entry), else as a **group**
|
|
2554
|
-
* (→ its references, expanded recursively). An unknown name **throws
|
|
2554
|
+
* (→ its references, expanded recursively). An unknown name **throws**, which
|
|
2555
2555
|
* raises when a route references a middleware that is neither an alias nor a group. Cyclic group
|
|
2556
2556
|
* references (a group that, directly or transitively, contains itself) also throw rather than
|
|
2557
2557
|
* recursing without bound. Function/class entries pass through unchanged and in order.
|
|
@@ -2566,7 +2566,7 @@ var Router = class _Router {
|
|
|
2566
2566
|
* Recursive worker for {@link Router.resolveMiddleware}. `groupPath` is the stack of group names
|
|
2567
2567
|
* currently being expanded; revisiting a name already on the path is a cycle (a group that
|
|
2568
2568
|
* directly or transitively contains itself) and throws. The same group may still appear in
|
|
2569
|
-
* sibling branches
|
|
2569
|
+
* sibling branches - only re-entrancy along a single path is rejected.
|
|
2570
2570
|
*/
|
|
2571
2571
|
expandMiddleware(references, groupPath) {
|
|
2572
2572
|
const resolved = [];
|
|
@@ -2606,8 +2606,8 @@ var Router = class _Router {
|
|
|
2606
2606
|
* Serialize the registered routes to a plain, JSON-serializable {@link RouteCache} snapshot
|
|
2607
2607
|
* (methods, path, name, domain, middleware names, and the `[controller, method]` action).
|
|
2608
2608
|
*
|
|
2609
|
-
* Closures cannot be serialized. Mirroring the conventional `route:cache`
|
|
2610
|
-
* "Unable to prepare route … for serialization. Uses Closure."
|
|
2609
|
+
* Closures cannot be serialized. Mirroring the conventional `route:cache` - which aborts with
|
|
2610
|
+
* "Unable to prepare route … for serialization. Uses Closure." - this **throws** when any route
|
|
2611
2611
|
* uses a closure handler, rather than silently dropping it, so a cache is always complete or
|
|
2612
2612
|
* absent. Rehydrate with {@link Router.loadCache} or {@link Router.fromCache}.
|
|
2613
2613
|
*/
|