@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/contracts.d.ts

@@ -41,14 +41,26 @@ interface Session {
     start(): Promise<void>;
     save(): Promise<void>;
     all(): Record<string, unknown>;
+    only(keys: string[]): Record<string, unknown>;
+    except(keys: string[]): Record<string, unknown>;
+    /** Whether every key is present, even with a null value. */
+    exists(...keys: string[]): boolean;
+    missing(...keys: string[]): boolean;
+    /** Whether the key is present and not null. */
     has(key: string): boolean;
     get<T = unknown>(key: string, defaultValue?: T): T;
     put(key: string | Record<string, unknown>, value?: unknown): void;
     push(key: string, value: unknown): void;
+    /** Adds `amount` (default 1) to the number under the key and returns the new value. */
+    increment(key: string, amount?: number): number;
+    decrement(key: string, amount?: number): number;
     pull<T = unknown>(key: string, defaultValue?: T): T;
+    /** Forgets the key and returns its value. */
+    remove<T = unknown>(key: string): T;
     forget(...keys: string[]): void;
     flush(): void;
-    flash(key: string, value: unknown): void;
+    /** Puts the value (true when omitted) for the next request only. */
+    flash(key: string, value?: unknown): void;
     now(key: string, value: unknown): void;
     reflash(): void;
     keep(...keys: string[]): void;
@@ -70,6 +82,370 @@ interface SessionHandler {
     gc(maxLifetimeSeconds: number): Promise<void>;
 }
 
+/**
+ * What one rule tells the validated data's type about a value that passed it. Every member is optional:
+ * - `value`: the type of a passing value. A field's type is the intersection of its rules' values
+ *   (`'string|in:a,b'` is `'a' | 'b'`); a field whose rules set none is `unknown`.
+ * - `presence`: `'required'` puts the key in the data and rules out null (`required`, `accepted`); `'present'` puts
+ *   the key in the data; `'filled'` rules out null without putting the key in; `'excluded'` leaves the key out;
+ *   `'optional'` may leave the key out whatever else would put it in (`sometimes` skips a missing key, and a rule that
+ *   excludes the field under a condition drops it with its children), so the key is optional and doesn't put its
+ *   parent in. A key nothing puts in is optional, as the validated data has only the keys the input had.
+ * - `each`: on a field that also has `array`, the type of each item instead of `value` (`in` checks every item of an
+ *   array: `'array|in:a,b'` is `Array<'a' | 'b'>`).
+ * - `nullable`: null passes, unless a `'required'` or `'filled'` rule says otherwise.
+ */
+interface RuleTyping {
+    value?: unknown;
+    each?: unknown;
+    presence?: 'required' | 'present' | 'filled' | 'excluded' | 'optional';
+    nullable?: true;
+}
+/** A number, or the text of one: a form sends every field as text, and `integer` and `numeric` accept both. */
+type NumericValue = number | `${number}`;
+/** `a,b,c` → `'a' | 'b' | 'c'`: a rule's comma-separated parameters, as Validator splits them. */
+type RuleParameterList<P extends string> = P extends `${infer Head},${infer Tail}` ? Head | RuleParameterList<Tail> : P;
+/**
+ * What `in` (and `Rule.in()`) lets through: it compares the value's text with each listed value, so `'1'` lets the
+ * number 1 through too, and `'true'` the boolean. A list known only as `string` (`` `in:${list.join(',')}` ``) says
+ * nothing, as any value whose text is listed passes.
+ */
+type InValue<V> = string extends V ? unknown : V extends string ? V | (V extends `${infer N extends number}` ? N : never) | (V extends 'true' ? true : V extends 'false' ? false : never) : V extends number | boolean ? V | `${V}` : V;
+/**
+ * The string rules that tell the validated data's type something, by name, each a RuleTyping. `Parameters` is the
+ * rule's text after the colon (`'a,b'` for `in:a,b`). A rule that only checks a value it doesn't change the type of
+ * (`max`, `confirmed`, `unique`) has no entry. Add a member for a new type-setting rule; an app adds its own
+ * `Validator.extend()` rules by declaration merging, with the same type parameter.
+ */
+interface ValidationRuleTypes<Parameters extends string = string> {
+    required: {
+        presence: 'required';
+    };
+    /** Skips the field when the key is missing, so the key may be left out even with `required`. */
+    sometimes: {
+        presence: 'optional';
+    };
+    nullable: {
+        nullable: true;
+    };
+    accepted: {
+        presence: 'required';
+        value: true | 1 | 'yes' | 'on' | '1' | 'true';
+    };
+    declined: {
+        presence: 'required';
+        value: false | 0 | 'no' | 'off' | '0' | 'false';
+    };
+    present: {
+        presence: 'present';
+    };
+    filled: {
+        presence: 'filled';
+    };
+    missing: {
+        presence: 'excluded';
+    };
+    exclude: {
+        presence: 'excluded';
+    };
+    /** Drop the field, children and all, under a condition, so the key may be left out even with `required`. */
+    exclude_if: {
+        presence: 'optional';
+    };
+    exclude_unless: {
+        presence: 'optional';
+    };
+    exclude_with: {
+        presence: 'optional';
+    };
+    exclude_without: {
+        presence: 'optional';
+    };
+    /**
+     * Passes only when the field is missing or empty, so a value that is there is null, blank or whitespace-only text,
+     * [] or {}.
+     */
+    prohibited: {
+        value: null | string | [] | Record<string, never>;
+    };
+    string: {
+        value: string;
+    };
+    /** `integer:strict` and `numeric:strict` refuse the text of a number. */
+    integer: {
+        value: Parameters extends 'strict' ? number : NumericValue;
+    };
+    numeric: {
+        value: Parameters extends 'strict' ? number : NumericValue;
+    };
+    /** `boolean:strict` lets only true and false through. */
+    boolean: {
+        value: Parameters extends 'strict' ? boolean : boolean | 0 | 1 | '0' | '1';
+    };
+    /** `array` is a list; `array:a,b` an object whose keys are among those named. */
+    array: {
+        value: Parameters extends '' ? unknown[] : {
+            [K in RuleParameterList<Parameters>]?: unknown;
+        };
+    };
+    list: {
+        value: unknown[];
+    };
+    contains: {
+        value: unknown[];
+    };
+    doesnt_contain: {
+        value: unknown[];
+    };
+    required_array_keys: {
+        value: {
+            [K in RuleParameterList<Parameters>]: unknown;
+        };
+    };
+    in_array_keys: {
+        value: Record<string, unknown>;
+    };
+    email: {
+        value: string;
+    };
+    url: {
+        value: string;
+    };
+    uuid: {
+        value: string;
+    };
+    alpha: {
+        value: string;
+    };
+    alpha_num: {
+        value: string;
+    };
+    alpha_dash: {
+        value: string;
+    };
+    regex: {
+        value: string;
+    };
+    lowercase: {
+        value: string | number;
+    };
+    uppercase: {
+        value: string | number;
+    };
+    ascii: {
+        value: string | number;
+    };
+    hex_color: {
+        value: string;
+    };
+    json: {
+        value: string;
+    };
+    ip: {
+        value: string;
+    };
+    ipv4: {
+        value: string;
+    };
+    ipv6: {
+        value: string;
+    };
+    mac_address: {
+        value: string;
+    };
+    ulid: {
+        value: string;
+    };
+    timezone: {
+        value: string;
+    };
+    active_url: {
+        value: string;
+    };
+    digits: {
+        value: NumericValue;
+    };
+    digits_between: {
+        value: NumericValue;
+    };
+    max_digits: {
+        value: NumericValue;
+    };
+    min_digits: {
+        value: NumericValue;
+    };
+    decimal: {
+        value: NumericValue;
+    };
+    multiple_of: {
+        value: NumericValue;
+    };
+    date: {
+        value: string;
+    };
+    /** A number passes a format made of digits (`Y`, `U`), as in Laravel. */
+    date_format: {
+        value: string | number;
+    };
+    /** A number passes the comparisons as a timestamp, as in Laravel; with `date` in the set, the value is text. */
+    before: {
+        value: string | number;
+    };
+    before_or_equal: {
+        value: string | number;
+    };
+    after: {
+        value: string | number;
+    };
+    after_or_equal: {
+        value: string | number;
+    };
+    date_equals: {
+        value: string | number;
+    };
+    current_password: {
+        value: string;
+    };
+    in: {
+        value: InValue<RuleParameterList<Parameters>>;
+        each: InValue<RuleParameterList<Parameters>>;
+    };
+    file: {
+        value: UploadedFile;
+    };
+    image: {
+        value: UploadedFile;
+    };
+    mimes: {
+        value: UploadedFile;
+    };
+    mimetypes: {
+        value: UploadedFile;
+    };
+    extensions: {
+        value: UploadedFile;
+    };
+    dimensions: {
+        value: UploadedFile;
+    };
+}
+/**
+ * A rule object that tells the validated data's type what it lets through, as a string rule's entry in
+ * ValidationRuleTypes does. `__typing` is never set or read at run time: declare it (`declare readonly __typing?:
+ * { value: string }`). A rule object without it changes nothing, so its field takes the type of the string rules
+ * beside it (`['required', 'string', new Uppercase()]` is a string).
+ */
+interface TypedValidationRule<T extends RuleTyping = RuleTyping> extends ValidationRule {
+    readonly __typing?: T;
+}
+type RuleName<R extends string> = R extends `${infer Name}:${string}` ? Name : R;
+type RuleParameters<R extends string> = R extends `${string}:${infer Parameters}` ? Parameters : '';
+type PipeRules<S extends string> = S extends `${infer Head}|${infer Tail}` ? Head | PipeRules<Tail> : S;
+/** What a rule without an entry, or a rule object without `__typing`, says: nothing. */
+type NoTyping = Record<never, never>;
+type StringRuleTyping<R extends string> = R extends unknown ? RuleName<R> extends keyof ValidationRuleTypes ? ValidationRuleTypes<RuleParameters<R>>[RuleName<R>] : NoTyping : never;
+type ObjectRuleTyping<O> = '__typing' extends keyof O ? Exclude<O['__typing' & keyof O], undefined> : NoTyping;
+type ItemTyping<I> = I extends string ? StringRuleTyping<I> : ObjectRuleTyping<I>;
+/** The typings of one field's rules, as a union: `'required|string'` or `['required', 'string', rule]`. */
+type SpecTypings<Spec> = Spec extends string ? StringRuleTyping<PipeRules<Spec>> : Spec extends ReadonlyArray<infer Item> ? ItemTyping<Item> : NoTyping;
+/** A rule string the compiler only knows as `string` (rules written without `as const`) says nothing. */
+type IsWide<Spec> = Spec extends string ? (string extends Spec ? true : false) : Spec extends ReadonlyArray<infer Item> ? (string extends Extract<Item, string> ? true : false) : false;
+type Intersect<U> = (U extends unknown ? (value: U) => void : never) extends (value: infer I) => void ? I : never;
+type Boxed<T> = T extends {
+    value: infer V;
+} ? {
+    v: V;
+} : never;
+type BoxedEach<T> = T extends {
+    each: infer E;
+} ? {
+    v: E;
+} : never;
+type Unbox<B> = [B] extends [never] ? unknown : Intersect<B> extends {
+    v: infer V;
+} ? V : never;
+type WithoutEach<T> = T extends {
+    each: unknown;
+} ? never : T;
+/** The intersection of the rules' values; on an array, the rules with `each` type its items instead. */
+type ValueOf<T> = [BoxedEach<T>] extends [never] ? Unbox<Boxed<T>> : Unbox<Boxed<WithoutEach<T>>> extends readonly unknown[] ? Array<Unbox<BoxedEach<T>>> : Unbox<Boxed<T>>;
+type PresenceOf<T> = T extends {
+    presence: infer P;
+} ? P : never;
+type NullableOf<T> = T extends {
+    nullable: true;
+} ? true : never;
+interface FieldInfo {
+    value: unknown;
+    required: boolean;
+    optional: boolean;
+    nullable: boolean;
+    excluded: boolean;
+}
+type FieldFrom<T, Optional = [Extract<PresenceOf<T>, 'optional'>] extends [never] ? false : true> = {
+    value: ValueOf<T>;
+    required: Optional extends true ? false : [Extract<PresenceOf<T>, 'required' | 'present'>] extends [never] ? false : true;
+    optional: Optional;
+    nullable: [NullableOf<T>] extends [never] ? false : [Extract<PresenceOf<T>, 'required' | 'filled'>] extends [never] ? true : false;
+    excluded: [Extract<PresenceOf<T>, 'excluded'>] extends [never] ? false : true;
+};
+/** Rules the compiler only knows as `string` say nothing, not even that the key is there. */
+type FieldOf<Spec> = IsWide<Spec> extends true ? NoRules : FieldFrom<SpecTypings<Spec>>;
+type NoRules = {
+    value: unknown;
+    required: false;
+    optional: false;
+    nullable: false;
+    excluded: false;
+};
+type Keys<R> = Extract<keyof R, string>;
+type Head<K extends string> = K extends `${infer H}.${string}` ? H : K;
+type Heads<R> = Head<Keys<R>>;
+type Children<R, H extends string> = {
+    [K in Keys<R> as K extends `${H}.${infer Rest}` ? Rest : never]: R[K];
+};
+type HasChildren<R, H extends string> = [Keys<Children<R, H>>] extends [never] ? false : true;
+type Own<R, H extends string> = H extends keyof R ? FieldOf<R[H]> : NoRules;
+type OrNull<T, Nullable> = Nullable extends true ? T | null : T;
+/**
+ * A wildcard's rules (`items.*.name`) make an array of what they describe; dotted keys (`author.name`) an object.
+ * Without a rule that makes the parent a list (`array`, `list`), validated() may give an object instead: an object
+ * sent under `items.*` stays one, and a sparse match (`{ items: [{}, { qty: 1 }] }`) keeps its index keys.
+ */
+type Structure<C, Parent> = '*' extends Heads<C> ? Items<ValueAt<C, '*'>, Parent> : Shape<C>;
+type Items<V, Parent> = [Parent] extends [readonly unknown[]] ? V[] : V[] | Record<string, V>;
+type ValueAt<R, H extends string, F extends FieldInfo = Own<R, H>> = OrNull<HasChildren<R, H> extends true ? Structure<Children<R, H>, F['value']> : F['value'], F['nullable']>;
+/**
+ * A key is in the data when a rule puts it there, or when a child key without a wildcard is required, unless a rule
+ * may leave it out.
+ */
+type IsRequired<R, H extends string> = Own<R, H>['optional'] extends true ? false : Own<R, H>['required'] extends true ? true : HasChildren<R, H> extends true ? '*' extends Heads<Children<R, H>> ? false : [RequiredHeads<Children<R, H>>] extends [never] ? false : true : false;
+type RequiredHeads<R> = {
+    [H in Heads<R>]: Own<R, H>['excluded'] extends true ? never : IsRequired<R, H> extends true ? H : never;
+}[Heads<R>];
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Shape<R> = string extends Keys<R> ? Record<string, unknown> : Simplify<{
+    [H in Heads<R> as Own<R, H>['excluded'] extends true ? never : IsRequired<R, H> extends true ? H : never]: ValueAt<R, H>;
+} & {
+    [H in Heads<R> as Own<R, H>['excluded'] extends true ? never : IsRequired<R, H> extends true ? never : H]?: ValueAt<R, H>;
+}>;
+/**
+ * The type of one field's passing value, from its rule string: `'nullable|integer'` → `number | \`${number}\` | null`.
+ * A rule string the compiler only knows as `string` gives unknown.
+ */
+type InferRuleType<S extends string> = string extends S ? unknown : OrNull<FieldOf<S>['value'], FieldOf<S>['nullable']>;
+/**
+ * The validated data a Rules object gives: nested as Validator's validated() nests it (`author.name` → `{ author: {
+ * name } }`, `tags.*` → an array, or an object too unless `tags` has `array` or `list`), each key optional unless a
+ * rule puts it in, each value typed by its rules. Rules known only as `Rules` (or any `Record<string, …>`) give
+ * `Record<string, unknown>`, and rule strings known only as `string` give optional keys of unknown. Write a
+ * FormRequest's `rules()` with `as const` so its rule strings keep their text; `request().validate({ … })` needs
+ * nothing.
+ */
+type InferValidatedType<R> = R extends unknown ? Shape<R> : never;
+
 /** A rule object (Laravel's ValidationRule). Call fail() to reject the value. */
 interface ValidationRule {
     validate(attribute: string, value: unknown, fail: (message: string) => void, data: Record<string, unknown>): void | Promise<void>;
@@ -77,6 +453,7 @@ interface ValidationRule {
 /** 'required|string|max:255', or an array mixing strings and rule objects. Keys support dot + `*` wildcards. */
 type Rules = Record<string, string | ReadonlyArray<string | ValidationRule>>;
 interface MessageBag {
+    add(key: string, message: string): void;
     has(key: string): boolean;
     first(key?: string): string | undefined;
     get(key: string): string[];
@@ -85,18 +462,21 @@ interface MessageBag {
     count(): number;
     toObject(): Record<string, string[]>;
 }
-interface Validator {
+/** `R` is the rules' type: `validated()` is typed from them, as `request().validate()` is. */
+interface Validator<R extends Rules = Rules> {
     passes(): Promise<boolean>;
     fails(): Promise<boolean>;
     /** Only the keys that have rules. Throws ValidationError (Exceptions.ts) on failure. */
-    validated<T = Record<string, unknown>>(): Promise<T>;
+    validated<T = InferValidatedType<R>>(): Promise<T>;
     /** Valid only after passes()/fails()/validated() has run. */
     errors(): MessageBag;
     after(callback: (validator: Validator) => void | Promise<void>): this;
+    /** Adds a failure message for `field` (from an after() hook). */
+    fail(field: string, message: string): void;
 }
 type RuleCallback = (attribute: string, value: unknown, parameters: string[], data: Record<string, unknown>) => boolean | Promise<boolean>;
 interface ValidationFactory {
-    make(data: Record<string, unknown>, rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Validator;
+    make<const R extends Rules>(data: Record<string, unknown>, rules: R, messages?: Record<string, string>, attributes?: Record<string, string>): Validator<R>;
     /** Registers a string rule, e.g. extend('uppercase', fn, ':attribute must be uppercase'). */
     extend(name: string, callback: RuleCallback, message?: string): void;
 }
@@ -110,7 +490,13 @@ interface UploadedFile {
     readonly mimeType: string;
     readonly size: number;
     extension(): string;
+    /** The extension of the name the browser gave the file, lower-cased ('' without one). */
+    clientExtension(): string;
+    /** A random 40-character name with extension(): the name store() gives the file. */
+    hashName(): string;
     arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+    stream(): ReadableStream<Uint8Array>;
     /** Stores on a Filesystem disk. Returns the stored path. */
     store(directory: string, disk?: string): Promise<string>;
     storeAs(directory: string, name: string, disk?: string): Promise<string>;
@@ -154,11 +540,18 @@ interface HttpRequest {
     /** Route parameter (after model binding), or every parameter when called with no key. */
     route<T = unknown>(key?: string): T;
     session(): Session;
-    /** The user resolved earlier by auth middleware. Undefined for guests. Use `await Auth.user()` to resolve lazily. */
-    user<T = unknown>(guard?: string): T | undefined;
+    /**
+     * The signed-in user, found through the request's guard (the default one, or the one named) the first time it is
+     * asked for, then the same instance for the rest of the request. Undefined for a guest.
+     */
+    user<T = unknown>(guard?: string): Promise<T | undefined>;
+    /** How user() finds the user (Auth sets it). The resolver may return a promise. */
     setUserResolver(resolver: (guard?: string) => unknown): void;
-    /** Validates this request's input via the ValidationFactory; throws a Validation OrielError (422) on failure. */
-    validate<T = Record<string, unknown>>(rules: Rules, messages?: Record<string, string>, attributes?: Record<string, string>): Promise<T>;
+    /**
+     * Validates this request's input via the ValidationFactory; throws a Validation OrielError (422) on failure. The
+     * validated 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>>;
 }
 declare const HttpRequest: Token<HttpRequest>;
 type Next = (request: HttpRequest) => Promise<Response>;
@@ -187,6 +580,8 @@ interface MiddlewareConfigurator {
         except: string[];
     }): this;
     redirectGuestsTo(url: string | ((request: HttpRequest) => string)): this;
+    /** Where the `guest` middleware sends a signed-in user. */
+    redirectUsersTo(url: string | ((request: HttpRequest) => string)): this;
 }
 interface HttpKernel {
     handle(request: Request): Promise<Response>;
@@ -197,7 +592,11 @@ interface ResponseFactory {
     make(content?: BodyInit | null, status?: number, headers?: HeadersInit): Response;
     json(data: unknown, status?: number, headers?: HeadersInit): Response;
     noContent(status?: number): Response;
+    /** Renders the view into an HTML response. */
+    view(name: string, data?: Record<string, unknown>, status?: number, headers?: HeadersInit): Promise<Response>;
     download(path: string, name?: string, headers?: HeadersInit): Promise<Response>;
+    /** Sends the file inline, for the browser to show (download() sends it as an attachment). */
+    file(path: string, headers?: HeadersInit): Promise<Response>;
     stream(body: ReadableStream, status?: number, headers?: HeadersInit): Response;
 }
 declare const ResponseFactory: Token<ResponseFactory>;
@@ -240,6 +639,13 @@ interface Application extends Container {
     /** Register a callback that terminate() runs, in registration order. */
     terminating(callback: () => void | Promise<void>): void;
     terminate(): Promise<void>;
+    /**
+     * Register a callback that shutdown() runs once, before the process exits: close pools and clients, write out
+     * files. terminating() callbacks run after every request; these run once, at the end.
+     */
+    onShutdown(callback: () => void | Promise<void>): void;
+    /** Runs the shutdown callbacks once, newest first; a failing one is printed and the rest still run. Never rejects. */
+    shutdown(): Promise<void>;
 }
 declare const Application: Token<Application>;
 interface ExceptionHandler {
@@ -434,6 +840,27 @@ interface RouteList {
 }
 /** A route name: the generated ones, or any string before `oriel route:types` has run. */
 type RouteName = [keyof RouteList] extends [never] ? string : Extract<keyof RouteList, string>;
+/** A route parameter's value: a scalar, or a model (its route key, or the `{post:slug}` column, goes in the URL). */
+type RouteParameter = string | number | bigint | boolean | {
+    getRouteKey(): unknown;
+};
+type GeneratedParameters<N extends keyof RouteList> = {
+    [K in keyof RouteList[N]]: RouteParameter;
+};
+type RequiredParameters<P> = {
+    [K in keyof P]-?: Record<never, never> extends Pick<P, K> ? never : K;
+}[keyof P];
+/**
+ * A named route's parameters: named (`{ post }`, extra keys become the query string), one value (it fills the first
+ * parameter), or values in URI order (`[post, comment]`).
+ */
+type RouteParameters<N extends string> = N extends keyof RouteList ? (GeneratedParameters<N> & Record<string, unknown>) | RouteParameter | readonly RouteParameter[] : unknown;
+/**
+ * The arguments after a route name in route() and redirect().route(): the parameters, required when the route has a
+ * required one, then `Rest` (route()'s `absolute`, redirect().route()'s `status`). Before `oriel route:types` has
+ * named the route, anything is accepted.
+ */
+type RouteArguments<N extends string, Rest extends unknown[] = [absolute?: boolean]> = N extends keyof RouteList ? [RequiredParameters<RouteList[N]>] extends [never] ? [parameters?: RouteParameters<N>, ...rest: Rest] : [parameters: RouteParameters<N>, ...rest: Rest] : [parameters?: unknown, ...rest: Rest];
 interface UrlGenerator {
     to(path: string, query?: Record<string, unknown>, absolute?: boolean): string;
     route(name: string, parameters?: unknown, absolute?: boolean): string;
@@ -452,16 +879,23 @@ declare const UrlGenerator: Token<UrlGenerator>;
 interface RedirectResponse extends Responsable {
     readonly targetUrl: string;
     with(key: string | Record<string, unknown>, value?: unknown): this;
-    withErrors(errors: Record<string, string | string[]>, bag?: string): this;
+    /** Flashes the errors (a record, or a validator's `errors()`) into the bag, `default` unless named. */
+    withErrors(errors: Record<string, string | string[]> | MessageBag, bag?: string): this;
     withInput(input?: Record<string, unknown>): this;
     withCookie(name: string, value: string, minutes?: number): this;
+    header(name: string, value: string): this;
 }
 interface Redirector {
     to(path: string, status?: number): RedirectResponse;
     route(name: string, parameters?: unknown, status?: number): RedirectResponse;
     back(fallback?: string, status?: number): RedirectResponse;
-    intended(fallback?: string): RedirectResponse;
+    intended(fallback?: string, status?: number): RedirectResponse;
     away(url: string, status?: number): RedirectResponse;
+    /** Remembers the URL a guest was going to (for intended()), then redirects to `path`. */
+    guest(path: string, status?: number): RedirectResponse;
+    /** Redirects to the current URL. */
+    refresh(status?: number): RedirectResponse;
+    setIntendedUrl(url: string): void;
 }
 declare const Redirector: Token<Redirector>;
 
@@ -540,6 +974,8 @@ interface Logger {
 interface LogManager extends Logger {
     channel(name?: string): Logger;
     stack(channels: string[]): Logger;
+    /** Writes out and closes the channels opened so far (log files are written asynchronously); a script awaits it last. */
+    flush(): Promise<void>;
 }
 declare const LogManager: Token<LogManager>;
 
@@ -630,6 +1066,8 @@ interface DatabaseConnection {
 interface DatabaseManager extends DatabaseConnection {
     connection(name?: string): DatabaseConnection;
     disconnect(name?: string): Promise<void>;
+    /** Closes every open connection and forgets them (the application's shutdown, the end of a test). */
+    disconnectAll(): Promise<void>;
 }
 declare const DatabaseManager: Token<DatabaseManager>;
 /** What non-Database components may rely on from a model instance. */
@@ -752,7 +1190,11 @@ interface ShouldQueue {
     backoff?: number | number[];
     /** Seconds. */
     timeout?: number;
-    uniqueId?(): string;
+    /**
+     * Laravel's ShouldBeUnique: while a job with this id is pending, another one is dropped. A queued listener's
+     * receives the event (Laravel 13); a number is used as its string.
+     */
+    uniqueId?(...args: never[]): string | number;
 }
 /** A job: public fields are its serialized data; handle() runs on the worker (inject() works inside it). */
 interface Job extends Partial<ShouldQueue> {
@@ -927,6 +1369,8 @@ interface ConsoleKernel {
     command(signature: string, handler: (this: CommandContext, ...args: unknown[]) => number | void | Promise<number | void>): ClosureCommand;
 }
 declare const ConsoleKernel: Token<ConsoleKernel>;
+/** A callback a scheduled event runs before or after itself (before(), after(), onSuccess(), onFailure()). */
+type ScheduleHook = () => unknown;
 interface ScheduledEvent {
     readonly expression: string;
     /**
@@ -939,24 +1383,69 @@ interface ScheduledEvent {
     /** Minutes the withoutOverlapping() lock is kept at most (1440 unless withoutOverlapping() says). Laravel's `$event->expiresAt`. */
     readonly expiresAt: number;
     cron(expression: string): this;
+    /**
+     * Runs every N seconds: the event is due every minute, and schedule:run (or schedule:work) keeps running it until
+     * the minute ends. N divides 60.
+     */
+    everySecond(): this;
+    everyTwoSeconds(): this;
+    everyFiveSeconds(): this;
+    everyTenSeconds(): this;
+    everyFifteenSeconds(): this;
+    everyTwentySeconds(): this;
+    everyThirtySeconds(): this;
     everyMinute(): this;
+    everyTwoMinutes(): this;
+    everyThreeMinutes(): this;
+    everyFourMinutes(): this;
     everyFiveMinutes(): this;
+    everyTenMinutes(): this;
     everyFifteenMinutes(): this;
     everyThirtyMinutes(): this;
     hourly(): this;
-    hourlyAt(minute: number): this;
+    /** At these minutes past every hour. */
+    hourlyAt(minute: number | readonly number[]): this;
+    /** Every odd hour (1, 3, … 23), at `minute` past (0 by default). */
+    everyOddHour(minute?: number | readonly number[]): this;
+    everyTwoHours(minute?: number | readonly number[]): this;
+    everyThreeHours(minute?: number | readonly number[]): this;
+    everyFourHours(minute?: number | readonly number[]): this;
+    everySixHours(minute?: number | readonly number[]): this;
     daily(): this;
+    /** The same as dailyAt(). */
+    at(time: string): this;
     dailyAt(time: string): this;
     twiceDaily(first?: number, second?: number): this;
+    /** At hours `first` and `second`, `minute` past. */
+    twiceDailyAt(first?: number, second?: number, minute?: number): this;
+    weekdays(): this;
+    weekends(): this;
+    mondays(): this;
+    tuesdays(): this;
+    wednesdays(): this;
+    thursdays(): this;
+    fridays(): this;
+    saturdays(): this;
+    sundays(): this;
     weekly(): this;
-    weeklyOn(day: number, time?: string): this;
+    /** On these days of the week (0 = Sunday … 6 = Saturday), at `time` ('0:0' by default). */
+    weeklyOn(day: number | readonly number[], time?: string): this;
     monthly(): this;
-    monthlyOn(day: number, time?: string): this;
+    monthlyOn(day?: number, time?: string): this;
+    twiceMonthly(first?: number, second?: number, time?: string): this;
+    /** On the last day of every month, at `time`. */
+    lastDayOfMonth(time?: string): this;
+    quarterly(): this;
+    /** On day `day` of the first month of each quarter, at `time`. */
+    quarterlyOn(day?: number, time?: string): this;
     yearly(): this;
-    weekdays(): this;
-    weekends(): this;
+    yearlyOn(month?: number, day?: number, time?: string): this;
+    /** On these days of the week (0 = Sunday … 6 = Saturday): `days([1, 3])` or `days(1, 3)`. */
+    days(days: number | readonly number[], ...more: number[]): this;
     timezone(timezone: string): this;
     between(start: string, end: string): this;
+    /** Skips the event between these times (a window may cross midnight: '23:00', '4:00'). */
+    unlessBetween(start: string, end: string): this;
     when(callback: () => boolean | Promise<boolean>): this;
     skip(callback: () => boolean | Promise<boolean>): this;
     /** Uses a cache lock (default 1440 minutes). */
@@ -966,6 +1455,15 @@ interface ScheduledEvent {
     runInBackground(): this;
     name(name: string): this;
     description(description: string): this;
+    /** Runs before the event, once its filters and locks let it run. */
+    before(callback: ScheduleHook): this;
+    /** Runs after the event, whether it succeeded or failed (also then()). */
+    after(callback: ScheduleHook): this;
+    then(callback: ScheduleHook): this;
+    /** Runs after the event when it succeeded: a command exited 0, a closure neither threw nor returned false. */
+    onSuccess(callback: ScheduleHook): this;
+    /** Runs after the event when it failed: a command exited non-zero, a closure threw or returned false. */
+    onFailure(callback: ScheduleHook): this;
     /** The name, else the description: the command, the job's class, or 'Closure'. schedule:list shows it. */
     getSummaryForDisplay(): string;
     /**
@@ -1384,4 +1882,4 @@ interface LiveManager {
 }
 declare const LiveManager: Token<LiveManager>;
 
-export { type AbilityCallback, type Abstract, type ActionMethods, type Address, Application, type Arrayable, type Attachment, AuthFactory, type Authenticatable, type AuthenticationError, type Batch, BatchRepository, type BodyInit, BusDispatcher, CacheManager, type CacheRepository, type Class, ClassRegistry, type ClosureCommand, type Command, type CommandContext, type Concrete, type ConfigCallbacks, ConfigRepository, ConsoleKernel, Container, type Content, type ControllerAction, type Cookie, CookieJar, type Credentials, CurrentRoute, type DatabaseConnection, DatabaseManager, type DatabaseNotification, type DriverName, Encrypter, type Enumerable, type Envelope, type ErrorKind, EventDispatcher, ExceptionCallbacks, ExceptionHandler, type ExceptionsConfigurator, type Factory, type FailedJob, FailedJobProvider, type Filesystem, FilesystemManager, Gate, type Guard, Hasher, type HeadersInit, type Htmlable, HttpKernel, HttpRequest, InertiaFactory, type InertiaOnceProp, type InertiaPage, type InertiaResponse, type InertiaScrollProp, InertiaSsrGateway, type InertiaSsrResponse, type InvokableClass, type Job, type Jsonable, type Listener, type ListenerClass, type LiveEffects, LiveManager, type LiveSnapshot, type LiveUpdateRequest, type LiveUpdateResponse, type Lock, type LogLevel, LogManager, type Logger, MailManager, type MailRecipient, type MailTransport, type Mailable, type Mailer, type MessageBag, type Middleware, MiddlewareCallbacks, type MiddlewareClass, type MiddlewareConfigurator, type MiddlewareReference, type ModelInstance, type ModelNotFoundError, type ModelStatic, type MustVerifyEmail, type Next, type Notifiable, type Notification, type NotificationChannel, NotificationDispatcher, type Operator, type OptionValue, type OrielError, type OutgoingMessage, PaginationState, PasswordBroker, type PasswordStatus, type PendingBatch, type PendingBatchOptions, type PendingChain, type PendingMail, type Pipe, type PipeClosure, type PipeNext, type Pipeline, PipelineFactory, type PropCallback, type PutOptions, type QueryBuilder, type Queue, type QueueJob, QueueManager, type QueuePayload, RateLimiter, type RedirectResponse, Redirector, type ResourceOptions, type Responsable, ResponseFactory, type Route, type RouteAction, type RouteClosure, type RouteList, RouteModelResolver, type RouteName, type RouteRegistrar, Router, RoutingPaths, type Row, type RuleCallback, type Rules, Schedule, type ScheduledEvent, type SentMessage, type ServiceProvider, type ServiceProviderClass, Session, type SessionHandler, type ShouldQueue, type StatefulGuard, type Token, type UploadedFile, UrlGenerator, type UserProvider, type ValidationError, ValidationFactory, type ValidationRule, type Validator, type View, ViewFactory, token };
+export { type AbilityCallback, type Abstract, type ActionMethods, type Address, Application, type Arrayable, type Attachment, AuthFactory, type Authenticatable, type AuthenticationError, type Batch, BatchRepository, type BodyInit, BusDispatcher, CacheManager, type CacheRepository, type Class, ClassRegistry, type ClosureCommand, type Command, type CommandContext, type Concrete, type ConfigCallbacks, ConfigRepository, ConsoleKernel, Container, type Content, type ControllerAction, type Cookie, CookieJar, type Credentials, CurrentRoute, type DatabaseConnection, DatabaseManager, type DatabaseNotification, type DriverName, Encrypter, type Enumerable, type Envelope, type ErrorKind, EventDispatcher, ExceptionCallbacks, ExceptionHandler, type ExceptionsConfigurator, type Factory, type FailedJob, FailedJobProvider, type Filesystem, FilesystemManager, Gate, type Guard, Hasher, type HeadersInit, type Htmlable, HttpKernel, HttpRequest, type InValue, InertiaFactory, type InertiaOnceProp, type InertiaPage, type InertiaResponse, type InertiaScrollProp, InertiaSsrGateway, type InertiaSsrResponse, type InferRuleType, type InferValidatedType, type InvokableClass, type Job, type Jsonable, type Listener, type ListenerClass, type LiveEffects, LiveManager, type LiveSnapshot, type LiveUpdateRequest, type LiveUpdateResponse, type Lock, type LogLevel, LogManager, type Logger, MailManager, type MailRecipient, type MailTransport, type Mailable, type Mailer, type MessageBag, type Middleware, MiddlewareCallbacks, type MiddlewareClass, type MiddlewareConfigurator, type MiddlewareReference, type ModelInstance, type ModelNotFoundError, type ModelStatic, type MustVerifyEmail, type Next, type Notifiable, type Notification, type NotificationChannel, NotificationDispatcher, type NumericValue, type Operator, type OptionValue, type OrielError, type OutgoingMessage, PaginationState, PasswordBroker, type PasswordStatus, type PendingBatch, type PendingBatchOptions, type PendingChain, type PendingMail, type Pipe, type PipeClosure, type PipeNext, type Pipeline, PipelineFactory, type PropCallback, type PutOptions, type QueryBuilder, type Queue, type QueueJob, QueueManager, type QueuePayload, RateLimiter, type RedirectResponse, Redirector, type ResourceOptions, type Responsable, ResponseFactory, type Route, type RouteAction, type RouteArguments, type RouteClosure, type RouteList, RouteModelResolver, type RouteName, type RouteParameter, type RouteParameters, type RouteRegistrar, Router, RoutingPaths, type Row, type RuleCallback, type RuleParameterList, type RuleTyping, type Rules, Schedule, type ScheduleHook, type ScheduledEvent, type SentMessage, type ServiceProvider, type ServiceProviderClass, Session, type SessionHandler, type ShouldQueue, type StatefulGuard, type Token, type TypedValidationRule, type UploadedFile, UrlGenerator, type UserProvider, type ValidationError, ValidationFactory, type ValidationRule, type ValidationRuleTypes, type Validator, type View, ViewFactory, token };