@orieljs/http 0.1.0-alpha.5 → 0.1.0-alpha.7

package/NOTICE

@@ -7,3 +7,10 @@ This product includes software developed by the Oriel project
 Oriel is licensed under the Apache License, Version 2.0 (see LICENSE).
 The Oriel name and logo are not covered by that license; see TRADEMARKS.md
 (https://github.com/orieljs/framework/blob/main/TRADEMARKS.md).
+
+@orieljs/support (and @orieljs/framework, which bundles it) includes transliteration data from
+voku/portable-ascii (https://github.com/voku/portable-ascii), Copyright (C) 2019 Lars Moelleken, MIT License.
+
+@orieljs/notifications (and @orieljs/framework, which bundles it) includes the HTML and CSS of
+Laravel's default notification mail (laravel/framework, https://github.com/laravel/framework),
+Copyright (c) Taylor Otwell, MIT License.

package/README.md

@@ -0,0 +1,33 @@
+# @orieljs/http
+
+The HTTP layer of Oriel: the request, responses and redirects, the middleware kernel, the error handler and its error pages, and the server for Node and Bun. It is Oriel's counterpart of Laravel's HTTP layer. Http is part of `@orieljs/framework`, which every Oriel app already installs, and is re-exported from it. In an app, import it from `@orieljs/framework`; `@orieljs/http` is also published on its own.
+
+```bash
+npm install @orieljs/framework
+```
+
+```ts title="app/Http/Controllers/SearchController.ts"
+import { request, response } from '@orieljs/framework'
+import { Post } from '../../Models/Post'
+import { Controller } from './Controller'
+
+export class SearchController extends Controller {
+  async index() {
+    const term = request().input('q', '')
+    const posts = await Post.whereLike('title', `%${term}%`).latest().get()
+    return response().json({ term, posts }, 200, { 'Cache-Control': 'no-store' })
+  }
+}
+```
+
+`request()` is the current `IncomingRequest`, with `input()`, `string()`, `boolean()`, `integer()`, `only()`, `file()` and `header()`; `await request().user()` is the signed-in user, or `undefined` for a guest. `response()`, `redirect()` and `back()` build responses, and `abort()`, `abortIf()` and `abortUnless()` stop a request with an HTTP error. `await serve(app)` runs the app on Node or Bun.
+
+Documentation: https://orieljs.vercel.app/docs/requests
+
+Status: early alpha. APIs will change.
+
+## License
+
+Oriel is open-source software licensed under the Apache License 2.0 (Apache-2.0; see `LICENSE` and `NOTICE`). The Oriel name and logo are trademarks; see `TRADEMARKS.md`.
+
+Website: https://orieljs.vercel.app

package/TRADEMARKS.md

@@ -0,0 +1,33 @@
+# Oriel trademark policy
+
+The Oriel code is open source under the Apache License 2.0. The **Oriel name and logo** are not: the license covers
+the code only (section 6 of the license says so), and the name and logo stay with the project. This page explains
+what you can and can't do with them. The goal is simple: people should always be able to tell what is the real Oriel
+and what isn't.
+
+## You can, without asking
+
+- Use, change, ship and sell the code, as the license allows.
+- Say that your app or package is "built with Oriel", "for Oriel" or "compatible with Oriel".
+- Name a package `oriel-<something>` or `<something>-for-oriel` when it works with Oriel, as long as it is clear that
+  it is not official (for example, don't publish it under the `@orieljs` npm scope).
+- Use the name and logo to write about Oriel, teach it, or link to it, in articles, talks, videos and courses.
+- Use the unmodified logo to point to the project, as it is (no recolouring, cropping or
+  distortion).
+
+## You can't, without written permission
+
+- Call a fork, a modified copy or a competing product "Oriel", or anything likely to be confused with it.
+- Use the name or logo as the name, logo or domain of your own product, company or service.
+- Suggest that the Oriel project made, endorses or supports your work when it doesn't.
+- Sell merchandise with the name or logo.
+
+## Forks
+
+Forks are welcome. Please give yours a different name and logo, keep the `LICENSE` and `NOTICE` files, and say that
+it is based on Oriel.
+
+## Questions
+
+Open an issue at https://github.com/orieljs/framework or email meeeet.dev@gmail.com. If you're unsure whether a use
+is fine, ask; the answer is usually yes.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, Redirector, UploadedFile, Rules, OrielError, RouteName, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
-import { FileType, ServiceProvider } from '@orieljs/support';
+import { HttpRequest, CookieJar, Session, Container, RedirectResponse, HeadersInit, MessageBag, Redirector, UploadedFile, Rules, InferValidatedType, OrielError, RouteName, RouteArguments, ResponseFactory, BodyInit, UrlGenerator, HttpKernel, Application, MiddlewareClass, Middleware, Next, MiddlewareConfigurator, Router, ConfigRepository, ExceptionHandler, ExceptionsConfigurator, ConsoleKernel, Route } from '@orieljs/contracts';
+import { FileType, Stringable, ServiceProvider } from '@orieljs/support';
 import { IncomingMessage, ServerResponse } from 'node:http';
+import { SpawnOptions, ChildProcess } from 'node:child_process';
 
 /**
  * Whether a JSON text nests objects and arrays deeper than `maxDepth`, found by scanning (no parsing, no recursion):
@@ -18,9 +19,7 @@ declare function currentRequest(): HttpRequest | undefined;
 declare function optionalSession(): Session | undefined;
 declare function optionalCookieJar(): CookieJar | undefined;
 
-type ErrorsInput = Record<string, string | string[]> | {
-    toObject(): Record<string, string[]>;
-};
+type ErrorsInput = Record<string, string | string[]> | MessageBag;
 /**
  * Laravel's RedirectResponse. with()/withErrors()/withInput() flash to the request's Session immediately, like
  * Laravel; without a bound Session (an API-only app) they are skipped silently.
@@ -160,7 +159,10 @@ declare class IncomingRequest implements HttpRequest {
     hasAny(...keys: Array<string | string[]>): boolean;
     missing(...keys: Array<string | string[]>): boolean;
     filled(key: string): boolean;
-    string(key: string, defaultValue?: string): string;
+    /** Laravel's string(): the input as a Stringable (the default when it is missing or null): request().string('q').trim(). */
+    string(key: string, defaultValue?: string): Stringable;
+    /** Laravel's str(): string() under its short name. */
+    str(key: string, defaultValue?: string): Stringable;
     /** PHP's FILTER_VALIDATE_BOOLEAN: '1', 'true', 'on', 'yes' (any case) and true are true. */
     boolean(key: string, defaultValue?: boolean): boolean;
     /** PHP's intval: leading digits, else 0. */
@@ -179,10 +181,17 @@ declare class IncomingRequest implements HttpRequest {
     /** One route parameter (after model binding), or all of them. */
     route<T = unknown>(key?: string): T;
     session(): Session;
-    user<T = unknown>(guard?: string): T | undefined;
+    /**
+     * The signed-in user, through the resolver Auth sets, else the current scope's guard (the default, or `guard`).
+     * The guard keeps the user it found, so it is looked up once per request. Undefined for a guest or without auth.
+     */
+    user<T = unknown>(guard?: string): Promise<T | undefined>;
     setUserResolver(resolver: (guard?: string) => unknown): void;
-    /** Validates all() through the ValidationFactory; throws its Validation error on failure. */
-    validate<T = Record<string, unknown>>(rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<T>;
+    /**
+     * Validates all() through the ValidationFactory; throws its Validation error on failure. The data is typed from the
+     * rules: `validate({ title: 'required|string' })` is `{ title: string }`.
+     */
+    validate<const R extends Rules>(rules: R, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<InferValidatedType<R>>;
 }
 
 /** Helpers for request input: PHP-style bracket keys, safe cloning (no prototype pollution) and blank checks. */
@@ -233,15 +242,18 @@ declare class HttpServerError extends Error implements OrielError {
     readonly name = "HttpServerError";
 }
 
-/** request() → the current HttpRequest; request('key', default) → its input. */
-declare function request(): HttpRequest;
+/**
+ * request() → the current request (Laravel's Illuminate\Http\Request: the HttpRequest contract plus its extras, such
+ * as string()); request('key', default) → its input.
+ */
+declare function request(): IncomingRequest;
 declare function request<T = unknown>(key: string, defaultValue?: T): T;
 /** response() → the ResponseFactory; response(content, status, headers) → a Response. */
 declare function response(): ResponseFactory;
 declare function response(content: BodyInit | null, status?: number, headers?: HeadersInit): Response;
-/** The Redirector with its route() typed by the generated route names. */
+/** The Redirector with its route() typed by the generated route names and their parameters. */
 type TypedRedirector = Omit<Redirector, 'route'> & {
-    route(name: RouteName, parameters?: unknown, status?: number): RedirectResponse;
+    route<N extends RouteName>(name: N, ...args: RouteArguments<N, [status?: number]>): RedirectResponse;
 };
 /** redirect() → the Redirector; redirect('/path', status) → a RedirectResponse. */
 declare function redirect(): TypedRedirector;
@@ -251,8 +263,11 @@ declare function back(fallback?: string, status?: number): RedirectResponse;
 /** url() → the UrlGenerator; url('/path', query, absolute) → a URL. */
 declare function url(): UrlGenerator;
 declare function url(path: string, query?: Record<string, unknown>, absolute?: boolean): string;
-/** The URL of a named route. */
-declare function route(name: RouteName, parameters?: unknown, absolute?: boolean): string;
+/**
+ * The URL of a named route: route('posts.show', post), route('posts.show', { post, page: 2 }). Once `oriel
+ * route:types` has run, the name and the route's parameters are checked.
+ */
+declare function route<N extends RouteName>(name: N, ...args: RouteArguments<N>): string;
 /** abort(404), abort(403, 'Nope', headers), or abort(response) to send a ready response. */
 declare function abort(status: number | Response, message?: string, headers?: Record<string, string>): never;
 declare function abortIf(condition: unknown, status: number | Response, message?: string, headers?: Record<string, string>): void;
@@ -378,7 +393,10 @@ declare class ExceptionsConfiguration implements ExceptionsConfigurator {
 /** Runs the withExceptions() callbacks against a handler (the provider does this when the handler is built). */
 declare function applyExceptionCallbacks(app: Application, handler: ErrorHandler): void;
 
-/** Laravel's wording for the status (its error pages say "Server Error" and "Page Expired"). */
+/**
+ * The text an error page shows for a status: Laravel's own wording where it has a view ("Server Error", "Page
+ * Expired"), else Symfony's `Response::$statusTexts`, which Laravel shows for the others.
+ */
 declare function statusText(status: number): string;
 declare function escapeHtml(value: string): string;
 /** Laravel's minimal error page: "404 | Not Found". */
@@ -467,6 +485,28 @@ declare function serve(app: Application, options?: ServeOptions): Promise<Runnin
  */
 declare function servePublicFile(publicPath: string, request: Request): Promise<Response | undefined>;
 
+interface FileWatcher {
+    close(): void;
+}
+
+/** node:child_process's spawn(), replaceable in tests. */
+type SpawnServer = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+interface WatchedServerOptions {
+    /** The server's command line: the runtime, its flags, the CLI script, then `serve --host=… --port=…`. */
+    command: readonly string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Starts watching: calls back with the changed files (relative to the base path) once they settle. */
+    watch(onChange: (files: string[]) => void): FileWatcher;
+    info(message: string): void;
+    error(message: string): void;
+    /** How long a server may take to stop before it is killed, in ms. Default 15000 (serve gives requests 10 s). */
+    stopTimeout?: number;
+    /** The signals that stop it. Default SIGINT, SIGTERM and SIGHUP. */
+    signals?: readonly NodeJS.Signals[];
+    spawn?: SpawnServer;
+}
+
 interface RouteListRow {
     /** 'GET|HEAD' */
     readonly method: string;
@@ -506,6 +546,8 @@ interface HttpCommandOptions {
     serve?: (app: Application, options: ServeOptions) => Promise<RunningServer>;
     /** The terminal width for route:list. Default: process.stdout.columns, else 120. */
     terminalWidth?: () => number;
+    /** Replaces `serve --watch`'s restarting server (tests). Resolves the command's exit code. */
+    watch?: (options: WatchedServerOptions) => Promise<number>;
 }
 /** Registers `serve`, `route:list` and `install:api` as closure commands (PC1). */
 declare function registerHttpCommands(kernel: ConsoleKernel, app: Application, options?: HttpCommandOptions): void;