@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.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 — the `response()->stream()` equivalent. No `Content-Length` is set, so
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 — the `response()->streamJson()` equivalent. An iterable (or
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 — calling `writeTo` on one throws so a stream is never
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 — 404/405/… — is covered too), following the usual small
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 — the conventional
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 — the mapped error is not
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 — the
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} — the `$dontReport` spelling. */
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 — a
587
- * `false` return stops the chain (the default sink is skipped) — otherwise fall through to the
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} — `route.middleware(...)` can append after registration), and stacks
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 — an alias for {@link UploadedFile.get} reading more naturally as 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 — here, simply that it carries a non-empty filename. Mirrors the
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 — the documented filesystem seam.
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 — a timestamp/random base, the way
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) — backs {@link Request.httpHost}. */
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`) — the `$request->schemeAndHttpHost()`
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 — the `$request->isSecure()` equivalent. Reads the first
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 — `scheme://host/path?query` when the host is known,
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` — `*` matches any run of
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 — `true`/`1`/`'1'`/`'true'`/`'on'`/`'yes'` (strings
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 — note this returns a primitive
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 — headers, URL memos, body buffer, parsed/multipart memos — is immutable once
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 — the `$request->attributes`
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) — e.g. a `forceJson`
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 — so `string` alias/group names are
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 — the seam an app (or a view package)
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 — routes for a resource with exactly one instance (a profile, a
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* — a list of references (concrete entries and/or other
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* — a short `string` name for a single concrete {@link MiddlewareEntry}.
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** —, which
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 — only re-entrancy along a single path is rejected.
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` — which aborts with
2604
- * "Unable to prepare route … for serialization. Uses Closure." — this **throws** when any route
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
  */