@orieljs/routing 0.1.0-alpha.1 → 0.1.0-alpha.11

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,32 @@
+# @orieljs/routing
+
+The Oriel router: it maps a URL and an HTTP method to a closure or a controller action, as Laravel's routing. It 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/routing` is also published on its own.
+
+```bash
+npm install @orieljs/framework
+```
+
+```ts title="routes/web.ts"
+import { Route, view } from '@orieljs/framework'
+import { PostController } from '../app/Http/Controllers/PostController'
+
+Route.get('/', () => view('welcome')).name('home')
+
+Route.middleware(['auth', 'verified']).group(() => {
+  Route.get('/posts', [PostController, 'index']).name('posts.index')
+  Route.get('/posts/{post}', [PostController, 'show']).name('posts.show')
+  Route.post('/posts', [PostController, 'store']).middleware('throttle:10,1')
+})
+```
+
+`Route` has a method for each HTTP verb, plus `match()`, `any()`, `redirect()`, `view()`, `inertia()`, `resource()` and `fallback()`. A route takes a `name()`, `middleware()` and parameter constraints with `where()`, and groups share `middleware()`, `prefix()`, `name()` or `controller()`. A parameter named after a model, like `{post}`, receives the model, and `route('posts.show', post)` builds its URL.
+
+Documentation: https://orieljs.vercel.app/docs/routing
+
+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,4 +1,4 @@
-import { Route as Route$1, RouteAction, Class, MiddlewareReference, RouteRegistrar, ResourceOptions, ControllerAction, RouteClosure, Router, Container, MiddlewareClass, HttpRequest, UrlGenerator, OrielError, Middleware, ModelNotFoundError, Application } from '@orieljs/contracts';
+import { Route as Route$1, RouteAction, Class, MiddlewareReference, RouteRegistrar, ResourceOptions, ControllerAction, RouteClosure, InvokableClass, Router, Container, MiddlewareClass, HttpRequest, UrlGenerator, OrielError, Middleware, ModelNotFoundError, Application, Next } from '@orieljs/contracts';
 import * as _orieljs_support from '@orieljs/support';
 import { ServiceProvider } from '@orieljs/support';
 
@@ -38,9 +38,22 @@ declare class RouteDefinition implements Route$1 {
     getName(): string | undefined;
     /** Appends, like Laravel's $action['as'] .= $name. */
     name(name: string): this;
-    middleware(...middleware: MiddlewareReference[]): this;
+    /** middleware('auth', 'verified') or middleware(['auth', 'verified']). */
+    middleware(...middleware: Array<MiddlewareReference | readonly MiddlewareReference[]>): this;
     withoutMiddleware(...middleware: MiddlewareReference[]): this;
     where(parameter: string | Record<string, string>, pattern?: string): this;
+    /** Laravel's whereAlpha(): ASCII letters only. One parameter name or several. */
+    whereAlpha(parameters: string | readonly string[]): this;
+    /** Laravel's whereAlphaNumeric(): ASCII letters and digits. */
+    whereAlphaNumeric(parameters: string | readonly string[]): this;
+    /** Laravel's whereNumber(): digits only. */
+    whereNumber(parameters: string | readonly string[]): this;
+    /** Laravel's whereUlid(): 26 Crockford base-32 characters, the first at most 7. */
+    whereUlid(parameters: string | readonly string[]): this;
+    /** Laravel's whereUuid(): five groups of hex digits (8-4-4-4-12), any version. */
+    whereUuid(parameters: string | readonly string[]): this;
+    /** Laravel's whereIn(): one of the values. Unlike Laravel, each value is matched literally (`c++` is not a pattern). */
+    whereIn(parameters: string | readonly string[], values: ReadonlyArray<string | number>): this;
     gatherMiddleware(): MiddlewareReference[];
     excludedMiddleware(): MiddlewareReference[];
     wheres(): Record<string, string>;
@@ -78,17 +91,17 @@ declare class GroupRegistrar implements RouteRegistrar {
     constructor(router: GroupHost);
     prefix(prefix: string): this;
     name(prefix: string): this;
-    middleware(...middleware: MiddlewareReference[]): this;
+    middleware(...middleware: Array<MiddlewareReference | readonly MiddlewareReference[]>): this;
     controller(controller: Class<unknown>): this;
     group(routes: () => void | Promise<void>): Promise<void>;
-    get<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    post<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    put<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    patch<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    delete<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    options<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    any<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    match<C>(methods: string[], uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
+    get<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    post<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    put<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    patch<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    delete<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    options<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    any<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    match<C>(methods: string[], uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
     resource(name: string, controller: Class<unknown>, options?: ResourceOptions): void;
     apiResource(name: string, controller: Class<unknown>, options?: ResourceOptions): void;
 }
@@ -100,14 +113,14 @@ declare class BaseRouter implements Router {
     protected readonly container?: Container | undefined;
     /** `container` is the application; request-time lookups use the current (request) container first. */
     constructor(container?: Container | undefined);
-    get<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    post<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    put<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    patch<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    delete<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    options<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    any<C>(uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
-    match<C>(methods: string[], uri: string, action: ControllerAction<C> | RouteClosure | string): RouteDefinition;
+    get<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    post<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    put<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    patch<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    delete<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    options<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    any<C>(uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
+    match<C>(methods: string[], uri: string, action: ControllerAction<C> | RouteClosure | InvokableClass | string): RouteDefinition;
     /** Registers a route with the current group's prefix, name prefix, middleware and controller. GET implies HEAD. */
     addRoute(methods: readonly string[], uri: string, action: RouteHandler, options?: {
         fallback?: boolean;
@@ -117,13 +130,18 @@ declare class BaseRouter implements Router {
     permanentRedirect(from: string, to: string): RouteDefinition;
     /** Route.view('/about', 'pages.about', data): GET/HEAD; route parameters are merged into the view data. */
     view(uri: string, view: string, data?: Record<string, unknown>): RouteDefinition;
+    /**
+     * Route.inertia('/about', 'About', props): GET/HEAD; renders the page through the InertiaFactory (resolved when
+     * the route runs, so Routing needs no Inertia import). Route parameters are merged into the props.
+     */
+    inertia(uri: string, component: string, props?: Record<string, unknown>): RouteDefinition;
     resource(name: string, controller: Class<unknown>, options?: ResourceOptions): void;
     apiResource(name: string, controller: Class<unknown>, options?: ResourceOptions): void;
     /** Matches any GET path no other route matches. Always tried last. */
     fallback(action: RouteAction): RouteDefinition;
     prefix(prefix: string): GroupRegistrar;
     name(prefix: string): GroupRegistrar;
-    middleware(...middleware: MiddlewareReference[]): GroupRegistrar;
+    middleware(...middleware: Array<MiddlewareReference | readonly MiddlewareReference[]>): GroupRegistrar;
     controller(controller: Class<unknown>): GroupRegistrar;
     /**
      * Laravel's Route::group(attributes, callback). A synchronous callback's attributes are popped before this
@@ -139,6 +157,12 @@ declare class BaseRouter implements Router {
     getPatternVersion(): number;
     getBinder(parameter: string): RouteBinder | undefined;
     getModel(parameter: string): Class<unknown> | undefined;
+    /**
+     * Binds a matched route's raw parameter values as a request to it would: Route.bind() callbacks, Route.model(),
+     * then implicit binding through the RouteModelResolver of `container`. A missing model throws
+     * RouteModelNotFoundError (404). Live uses it to check a page route's `can:` middleware again on each update.
+     */
+    substituteBindings(route: RouteDefinition, values: Readonly<Record<string, string | undefined>>, container: Container): Promise<Record<string, unknown>>;
     aliasMiddleware(name: string, middleware: MiddlewareClass): this;
     /** The middleware aliases (Laravel's Router::getMiddleware()). */
     getMiddleware(): Record<string, MiddlewareClass>;
@@ -186,6 +210,20 @@ declare class BaseUrlGenerator implements UrlGenerator {
     /** The Referer header, then the session's previous URL, then `fallback`, then the root (Laravel's order). */
     previous(fallback?: string): string;
     hasRoute(name: string): boolean;
+    /**
+     * Laravel's URL::signedRoute(): the route URL with its parameters sorted by name, then a `signature` query (the
+     * HMAC-SHA256 of that URL, keyed by APP_KEY). `expiration` (a Date, or seconds from now) adds `expires`.
+     * `absolute: false` signs the path only (checked by `signed:relative`).
+     */
+    signedRoute(name: string, parameters?: unknown, expiration?: Date | number, absolute?: boolean): string;
+    /** Laravel's URL::temporarySignedRoute(): a signed URL that expires at `expiration` (a Date, or seconds from now). */
+    temporarySignedRoute(name: string, expiration: Date | number, parameters?: unknown, absolute?: boolean): string;
+    /** The request URL carries a correct signature (current or previous APP_KEY) that hasn't expired. */
+    hasValidSignature(request: HttpRequest, absolute?: boolean): boolean;
+    /** The signature matches the URL without its `signature` query, in a constant-time comparison. */
+    hasCorrectSignature(request: HttpRequest, absolute?: boolean): boolean;
+    /** No `expires` query, or one that is still in the future. */
+    signatureHasNotExpired(request: HttpRequest): boolean;
 }
 
 /** A middleware reference after alias and group expansion: 'throttle:60,1' → { cls: Throttle, parameters: ['60', '1'] }. */
@@ -300,6 +338,21 @@ declare class RoutingError extends Error implements OrielError {
     readonly status = 500;
     readonly name = "RoutingError";
 }
+/** A signed URL whose signature is missing, wrong or expired (Laravel's InvalidSignatureException). */
+declare class InvalidUrlSignatureError extends Error implements OrielError {
+    readonly kind: "Http";
+    readonly status = 403;
+    readonly name = "InvalidUrlSignatureError";
+    constructor();
+}
+/** Too many requests in the window (Laravel's ThrottleRequestsException): 429 with Retry-After and X-RateLimit-*. */
+declare class ThrottleRequestsError extends Error implements OrielError {
+    readonly headers: Record<string, string>;
+    readonly kind: "Http";
+    readonly status = 429;
+    readonly name = "ThrottleRequestsError";
+    constructor(headers?: Record<string, string>);
+}
 
 type ResourceMethod = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
 interface ResourceRoute {
@@ -323,6 +376,29 @@ declare function toResponse(request: unknown, value: unknown): Promise<Response>
  */
 declare const Route: _orieljs_support.Facade<BaseRouter, object>;
 
+/**
+ * Dispatched by the health route (`/up`) on every request (Laravel's DiagnosingHealth event). A listener checks
+ * something the application needs, such as the database or the cache, and throws when it fails: `/up` then answers
+ * 500 with "Application experiencing problems", and the exception is reported.
+ *
+ *   Event.listen(DiagnosingHealth, async () => { await DB.select('select 1') })
+ */
+declare class DiagnosingHealth {
+}
+interface HealthPage {
+    /** False when a check failed: the page says so and the status is 500 (default true). */
+    healthy?: boolean;
+    /** How long the request took, shown when given. */
+    milliseconds?: number;
+    /** The page title (default "Oriel"). */
+    appName?: string;
+}
+/**
+ * The health route's page (Laravel's health-up view): "Application up", or "Application experiencing problems" with
+ * status 500. Self-contained HTML with inline CSS: it loads nothing, so it answers even when the assets don't.
+ */
+declare function healthResponse(page?: HealthPage): Response;
+
 /** A route file may export a function instead of (or as well as) calling the Route facade at the top level. */
 type RouteFileCallback = (router: Router) => void | Promise<void>;
 /**
@@ -331,15 +407,15 @@ type RouteFileCallback = (router: Router) => void | Promise<void>;
  * A default export that is a function is called with the router.
  */
 declare function loadRoutesFrom(app: Application, router: Router, file: string): Promise<void>;
-/** The health route's page (Laravel's `/up`): 200 as long as the application boots and handles requests. */
-declare function healthResponse(): Response;
 
 /**
- * Binds the Router and the UrlGenerator, and once the app has booted loads the files given to withRouting(): the health URI,
- * then routes/web.ts in the `web` middleware group, then routes/api.ts under the api prefix in the `api` group
- * (Laravel's ApplicationBuilder::withRouting).
+ * Binds the Router and the UrlGenerator, registers the `signed` and `throttle` middleware, and once the app has booted
+ * loads the files given to withRouting(): the health URI (which dispatches DiagnosingHealth), then the web files in the
+ * `web` middleware group, then the api files under the api prefix in the `api` group (Laravel's
+ * ApplicationBuilder::withRouting).
  */
 declare class RoutingServiceProvider extends ServiceProvider {
+    #private;
     register(): void;
     /**
      * The files load in a booted() callback, after every provider's boot() (Laravel's withRouting does the same), so
@@ -349,4 +425,33 @@ declare class RoutingServiceProvider extends ServiceProvider {
     boot(): void;
 }
 
-export { BaseRouter, BaseUrlGenerator, ControllerMethodNotFoundError, type GroupAttributes, type GroupHost, GroupRegistrar, MethodNotAllowedHttpError, MiddlewareNotFoundError, NotFoundHttpError, type ResolvedMiddleware, type ResourceMethod, type ResourceRoute, Route, type RouteAttributes, type RouteBinder, RouteDefinition, type RouteFileCallback, type RouteHandler, RouteModelNotFoundError, RouteNotDefinedError, type RouteStage, RoutingError, RoutingServiceProvider, type UriParameter, UrlGenerationError, buildQuery, compareRoutes, dispatchRoute, healthResponse, loadRoutesFrom, mergeGroup, normalizePath, normalizeUri, orderForBindings, parseParameters, renderError, resolveMiddleware, resourceRoutes, runMiddleware, substituteBindings, toResponse };
+/**
+ * Laravel's ThrottleRequests (`throttle:<maxAttempts>,<decayMinutes>[,<prefix>]`): counts the client's requests
+ * (the signed-in user, else the IP) in a window and answers 429 once there are too many. Responses carry
+ * X-RateLimit-Limit and X-RateLimit-Remaining; the 429 adds Retry-After and X-RateLimit-Reset.
+ */
+declare class ThrottleRequests implements Middleware {
+    handle(request: HttpRequest, next: Next, maxAttempts?: string, decayMinutes?: string, prefix?: string): Promise<Response>;
+    /** The signed-in user's identifier, else the client IP, hashed (Laravel's resolveRequestSignature()). */
+    protected resolveRequestSignature(request: HttpRequest): Promise<string>;
+}
+
+/**
+ * Laravel's SetCacheHeaders (`cache.headers:public;max_age=3600;s_maxage=86400;etag`): a GET or HEAD response gets
+ * the Cache-Control directives, and with `etag` an ETag from the body's MD5, answering 304 to a matching
+ * If-None-Match. A response that sets a cookie, or already says `no-store`, is left alone, so a CDN never stores a
+ * page made for one visitor.
+ */
+declare class SetCacheHeaders implements Middleware {
+    handle(request: HttpRequest, next: Next, ...parameters: string[]): Promise<Response>;
+}
+
+/**
+ * Laravel's ValidateSignature (`signed`, `signed:relative`): the request URL must carry a valid, unexpired
+ * signature from URL.signedRoute()/temporarySignedRoute(), else 403. `relative` checks a path-only signature.
+ */
+declare class ValidateSignature implements Middleware {
+    handle(request: HttpRequest, next: Next, ...parameters: string[]): Promise<Response>;
+}
+
+export { BaseRouter, BaseUrlGenerator, ControllerMethodNotFoundError, DiagnosingHealth, type GroupAttributes, type GroupHost, GroupRegistrar, type HealthPage, InvalidUrlSignatureError, MethodNotAllowedHttpError, MiddlewareNotFoundError, NotFoundHttpError, type ResolvedMiddleware, type ResourceMethod, type ResourceRoute, Route, type RouteAttributes, type RouteBinder, RouteDefinition, type RouteFileCallback, type RouteHandler, RouteModelNotFoundError, RouteNotDefinedError, type RouteStage, RoutingError, RoutingServiceProvider, SetCacheHeaders, ThrottleRequests, ThrottleRequestsError, type UriParameter, UrlGenerationError, ValidateSignature, buildQuery, compareRoutes, dispatchRoute, healthResponse, loadRoutesFrom, mergeGroup, normalizePath, normalizeUri, orderForBindings, parseParameters, renderError, resolveMiddleware, resourceRoutes, runMiddleware, substituteBindings, toResponse };