swup 4.2.0 → 4.3.1

package/dist/types/modules/Hooks.d.ts

@@ -1,250 +1,268 @@
-import { DelegateEvent } from 'delegate-it';
-import Swup from '../Swup.js';
-import { Visit } from './Visit.js';
-import { FetchOptions, PageData } from './fetchPage.js';
-export interface HookDefinitions {
-    'animation:out:start': undefined;
-    'animation:out:await': {
-        skip: boolean;
-    };
-    'animation:out:end': undefined;
-    'animation:in:start': undefined;
-    'animation:in:await': {
-        skip: boolean;
-    };
-    'animation:in:end': undefined;
-    'animation:skip': undefined;
-    'cache:clear': undefined;
-    'cache:set': {
-        page: PageData;
-    };
-    'content:replace': {
-        page: PageData;
-    };
-    'content:scroll': undefined;
-    'enable': undefined;
-    'disable': undefined;
-    'fetch:request': {
-        url: string;
-        options: FetchOptions;
-    };
-    'fetch:error': {
-        url: string;
-        status: number;
-        response: Response;
-    };
-    'history:popstate': {
-        event: PopStateEvent;
-    };
-    'link:click': {
-        el: HTMLAnchorElement;
-        event: DelegateEvent<MouseEvent>;
-    };
-    'link:self': undefined;
-    'link:anchor': {
-        hash: string;
-    };
-    'link:newtab': {
-        href: string;
-    };
-    'page:load': {
-        page?: PageData;
-        cache?: boolean;
-        options: FetchOptions;
-    };
-    'page:view': {
-        url: string;
-        title: string;
-    };
-    'scroll:top': {
-        options: ScrollIntoViewOptions;
-    };
-    'scroll:anchor': {
-        hash: string;
-        options: ScrollIntoViewOptions;
-    };
-    'visit:start': undefined;
-    'visit:end': undefined;
-}
-export type HookArguments<T extends HookName> = HookDefinitions[T];
-export type HookName = keyof HookDefinitions;
-/** A hook handler. */
-export type Handler<T extends HookName> = (
-/** Context about the current visit. */
-visit: Visit, 
-/** Local arguments passed into the handler. */
-args: HookArguments<T>, 
-/** Default handler to be executed. Available if replacing an internal hook handler. */
-defaultHandler?: Handler<T>) => Promise<any> | any;
-export type Handlers = {
-    [K in HookName]: Handler<K>[];
-};
-/** Unregister a previously registered hook handler. */
-export type HookUnregister = () => void;
-/** Define when and how a hook handler is executed. */
-export type HookOptions = {
-    /** Execute the hook once, then remove the handler */
-    once?: boolean;
-    /** Execute the hook before the internal default handler */
-    before?: boolean;
-    /** Set a priority for when to execute this hook. Lower numbers execute first. Default: `0` */
-    priority?: number;
-    /** Replace the internal default handler with this hook handler */
-    replace?: boolean;
-};
-export type HookRegistration<T extends HookName> = {
-    id: number;
-    hook: T;
-    handler: Handler<T>;
-    defaultHandler?: Handler<T>;
-} & HookOptions;
-type HookLedger<T extends HookName> = Map<Handler<T>, HookRegistration<T>>;
-interface HookRegistry extends Map<HookName, HookLedger<HookName>> {
-    get<K extends HookName>(key: K): HookLedger<K> | undefined;
-    set<K extends HookName>(key: K, value: HookLedger<K>): this;
-}
-/**
- * Hook registry.
- *
- * Create, trigger and handle hooks.
- *
- */
-export declare class Hooks {
-    /** Swup instance this registry belongs to */
-    protected swup: Swup;
-    /** Map of all registered hook handlers. */
-    protected registry: HookRegistry;
-    protected readonly hooks: HookName[];
-    constructor(swup: Swup);
-    /**
-     * Create ledgers for all core hooks.
-     */
-    protected init(): void;
-    /**
-     * Create a new hook type.
-     */
-    create(hook: string): void;
-    /**
-     * Check if a hook type exists.
-     */
-    exists(hook: HookName): boolean;
-    /**
-     * Get the ledger with all registrations for a hook.
-     */
-    protected get<T extends HookName>(hook: T): HookLedger<T> | undefined;
-    /**
-     * Remove all handlers of all hooks.
-     */
-    clear(): void;
-    /**
-     * Register a new hook handler.
-     * @param hook Name of the hook to listen for
-     * @param handler The handler function to execute
-     * @param options Object to specify how and when the handler is executed
-     *                Available options:
-     *                - `once`: Only execute the handler once
-     *                - `before`: Execute the handler before the default handler
-     *                - `priority`: Specify the order in which the handlers are executed
-     *                - `replace`: Replace the default handler with this handler
-     * @returns A function to unregister the handler
-     */
-    on<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-    on<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
-    /**
-     * Register a new hook handler to run before the default handler.
-     * Shortcut for `hooks.on(hook, handler, { before: true })`.
-     * @param hook Name of the hook to listen for
-     * @param handler The handler function to execute
-     * @param options Any other event options (see `hooks.on()` for details)
-     * @returns A function to unregister the handler
-     * @see on
-     */
-    before<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-    before<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
-    /**
-     * Register a new hook handler to replace the default handler.
-     * Shortcut for `hooks.on(hook, handler, { replace: true })`.
-     * @param hook Name of the hook to listen for
-     * @param handler The handler function to execute instead of the default handler
-     * @param options Any other event options (see `hooks.on()` for details)
-     * @returns A function to unregister the handler
-     * @see on
-     */
-    replace<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-    replace<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
-    /**
-     * Register a new hook handler to run once.
-     * Shortcut for `hooks.on(hook, handler, { once: true })`.
-     * @param hook Name of the hook to listen for
-     * @param handler The handler function to execute
-     * @param options Any other event options (see `hooks.on()` for details)
-     * @see on
-     */
-    once<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
-    once<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
-    /**
-     * Unregister a hook handler.
-     * @param hook Name of the hook the handler is registered for
-     * @param handler The handler function that was registered.
-     *                If omitted, all handlers for the hook will be removed.
-     */
-    off<T extends HookName>(hook: T): void;
-    off<T extends HookName>(hook: T, handler: Handler<T>): void;
-    /**
-     * Trigger a hook asynchronously, executing its default handler and all registered handlers.
-     * Will execute all handlers in order and `await` any `Promise`s they return.
-     * @param hook Name of the hook to trigger
-     * @param args Arguments to pass to the handler
-     * @param defaultHandler A default implementation of this hook to execute
-     * @returns The resolved return value of the executed default handler
-     */
-    call<T extends HookName>(hook: T, args?: HookArguments<T>, defaultHandler?: Handler<T>): Promise<any>;
-    /**
-     * Trigger a hook synchronously, executing its default handler and all registered handlers.
-     * Will execute all handlers in order, but will **not** `await` any `Promise`s they return.
-     * @param hook Name of the hook to trigger
-     * @param args Arguments to pass to the handler
-     * @param defaultHandler A default implementation of this hook to execute
-     * @returns The (possibly unresolved) return value of the executed default handler
-     */
-    callSync<T extends HookName>(hook: T, args?: HookArguments<T>, defaultHandler?: Handler<T>): any;
-    /**
-     * Execute the handlers for a hook, in order, as `Promise`s that will be `await`ed.
-     * @param registrations The registrations (handler + options) to execute
-     * @param args Arguments to pass to the handler
-     */
-    protected run<T extends HookName>(registrations: HookRegistration<T>[], args?: HookArguments<T>): Promise<any>;
-    /**
-     * Execute the handlers for a hook, in order, without `await`ing any returned `Promise`s.
-     * @param registrations The registrations (handler + options) to execute
-     * @param args Arguments to pass to the handler
-     */
-    protected runSync<T extends HookName>(registrations: HookRegistration<T>[], args?: HookArguments<T>): any[];
-    /**
-     * Get all registered handlers for a hook, sorted by priority and registration order.
-     * @param hook Name of the hook
-     * @param defaultHandler The optional default handler of this hook
-     * @returns An object with the handlers sorted into `before` and `after` arrays,
-     *          as well as a flag indicating if the original handler was replaced
-     */
-    protected getHandlers<T extends HookName>(hook: T, defaultHandler?: Handler<T>): {
-        found: boolean;
-        before: HookRegistration<T>[];
-        handler: HookRegistration<T>[];
-        after: HookRegistration<T>[];
-        replaced: boolean;
-    };
-    /**
-     * Sort two hook registrations by priority and registration order.
-     * @param a The registration object to compare
-     * @param b The other registration object to compare with
-     * @returns The sort direction
-     */
-    protected sortRegistrations<T extends HookName>(a: HookRegistration<T>, b: HookRegistration<T>): number;
-    /**
-     * Dispatch a custom event on the `document` for a hook. Prefixed with `swup:`
-     * @param hook Name of the hook.
-     */
-    protected dispatchDomEvent<T extends HookName>(hook: T, args?: HookArguments<T>): void;
-}
-export {};
+import { DelegateEvent } from 'delegate-it';
+import Swup from '../Swup.js';
+import { Visit } from './Visit.js';
+import { FetchOptions, PageData } from './fetchPage.js';
+export interface HookDefinitions {
+    'animation:out:start': undefined;
+    'animation:out:await': {
+        skip: boolean;
+    };
+    'animation:out:end': undefined;
+    'animation:in:start': undefined;
+    'animation:in:await': {
+        skip: boolean;
+    };
+    'animation:in:end': undefined;
+    'animation:skip': undefined;
+    'cache:clear': undefined;
+    'cache:set': {
+        page: PageData;
+    };
+    'content:replace': {
+        page: PageData;
+    };
+    'content:scroll': undefined;
+    'enable': undefined;
+    'disable': undefined;
+    'fetch:request': {
+        url: string;
+        options: FetchOptions;
+    };
+    'fetch:error': {
+        url: string;
+        status: number;
+        response: Response;
+    };
+    'history:popstate': {
+        event: PopStateEvent;
+    };
+    'link:click': {
+        el: HTMLAnchorElement;
+        event: DelegateEvent<MouseEvent>;
+    };
+    'link:self': undefined;
+    'link:anchor': {
+        hash: string;
+    };
+    'link:newtab': {
+        href: string;
+    };
+    'page:load': {
+        page?: PageData;
+        cache?: boolean;
+        options: FetchOptions;
+    };
+    'page:view': {
+        url: string;
+        title: string;
+    };
+    'scroll:top': {
+        options: ScrollIntoViewOptions;
+    };
+    'scroll:anchor': {
+        hash: string;
+        options: ScrollIntoViewOptions;
+    };
+    'visit:start': undefined;
+    'visit:end': undefined;
+}
+export interface HookReturnValues {
+    'content:scroll': Promise<boolean>;
+    'fetch:request': Promise<Response>;
+    'page:load': Promise<PageData>;
+    'scroll:top': boolean;
+    'scroll:anchor': boolean;
+}
+export type HookArguments<T extends HookName> = HookDefinitions[T];
+export type HookName = keyof HookDefinitions;
+/** A generic hook handler. */
+export type Handler<T extends HookName> = (
+/** Context about the current visit. */
+visit: Visit, 
+/** Local arguments passed into the handler. */
+args: HookArguments<T>) => Promise<unknown> | unknown;
+/** A default hook handler with an expected return type. */
+export type DefaultHandler<T extends HookName> = (
+/** Context about the current visit. */
+visit: Visit, 
+/** Local arguments passed into the handler. */
+args: HookArguments<T>, 
+/** Default handler to be executed. Available if replacing an internal hook handler. */
+defaultHandler?: DefaultHandler<T>) => T extends keyof HookReturnValues ? HookReturnValues[T] : Promise<unknown> | unknown;
+export type Handlers = {
+    [K in HookName]: Handler<K>[];
+};
+/** Unregister a previously registered hook handler. */
+export type HookUnregister = () => void;
+/** Define when and how a hook handler is executed. */
+export type HookOptions = {
+    /** Execute the hook once, then remove the handler */
+    once?: boolean;
+    /** Execute the hook before the internal default handler */
+    before?: boolean;
+    /** Set a priority for when to execute this hook. Lower numbers execute first. Default: `0` */
+    priority?: number;
+    /** Replace the internal default handler with this hook handler */
+    replace?: boolean;
+};
+export type HookRegistration<T extends HookName, H extends Handler<T> | DefaultHandler<T> = Handler<T>> = {
+    id: number;
+    hook: T;
+    handler: H;
+    defaultHandler?: DefaultHandler<T>;
+} & HookOptions;
+type HookLedger<T extends HookName> = Map<Handler<T>, HookRegistration<T>>;
+interface HookRegistry extends Map<HookName, HookLedger<HookName>> {
+    get<K extends HookName>(key: K): HookLedger<K> | undefined;
+    set<K extends HookName>(key: K, value: HookLedger<K>): this;
+}
+/**
+ * Hook registry.
+ *
+ * Create, trigger and handle hooks.
+ *
+ */
+export declare class Hooks {
+    /** Swup instance this registry belongs to */
+    protected swup: Swup;
+    /** Map of all registered hook handlers. */
+    protected registry: HookRegistry;
+    protected readonly hooks: HookName[];
+    constructor(swup: Swup);
+    /**
+     * Create ledgers for all core hooks.
+     */
+    protected init(): void;
+    /**
+     * Create a new hook type.
+     */
+    create(hook: string): void;
+    /**
+     * Check if a hook type exists.
+     */
+    exists(hook: HookName): boolean;
+    /**
+     * Get the ledger with all registrations for a hook.
+     */
+    protected get<T extends HookName>(hook: T): HookLedger<T> | undefined;
+    /**
+     * Remove all handlers of all hooks.
+     */
+    clear(): void;
+    /**
+     * Register a new hook handler.
+     * @param hook Name of the hook to listen for
+     * @param handler The handler function to execute
+     * @param options Object to specify how and when the handler is executed
+     *                Available options:
+     *                - `once`: Only execute the handler once
+     *                - `before`: Execute the handler before the default handler
+     *                - `priority`: Specify the order in which the handlers are executed
+     *                - `replace`: Replace the default handler with this handler
+     * @returns A function to unregister the handler
+     */
+    on<T extends HookName, O extends HookOptions>(hook: T, handler: DefaultHandler<T>, options: O & {
+        replace: true;
+    }): HookUnregister;
+    on<T extends HookName, O extends HookOptions>(hook: T, handler: Handler<T>, options: O): HookUnregister;
+    on<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+    /**
+     * Register a new hook handler to run before the default handler.
+     * Shortcut for `hooks.on(hook, handler, { before: true })`.
+     * @param hook Name of the hook to listen for
+     * @param handler The handler function to execute
+     * @param options Any other event options (see `hooks.on()` for details)
+     * @returns A function to unregister the handler
+     * @see on
+     */
+    before<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
+    before<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+    /**
+     * Register a new hook handler to replace the default handler.
+     * Shortcut for `hooks.on(hook, handler, { replace: true })`.
+     * @param hook Name of the hook to listen for
+     * @param handler The handler function to execute instead of the default handler
+     * @param options Any other event options (see `hooks.on()` for details)
+     * @returns A function to unregister the handler
+     * @see on
+     */
+    replace<T extends HookName>(hook: T, handler: DefaultHandler<T>, options: HookOptions): HookUnregister;
+    replace<T extends HookName>(hook: T, handler: DefaultHandler<T>): HookUnregister;
+    /**
+     * Register a new hook handler to run once.
+     * Shortcut for `hooks.on(hook, handler, { once: true })`.
+     * @param hook Name of the hook to listen for
+     * @param handler The handler function to execute
+     * @param options Any other event options (see `hooks.on()` for details)
+     * @see on
+     */
+    once<T extends HookName>(hook: T, handler: Handler<T>, options: HookOptions): HookUnregister;
+    once<T extends HookName>(hook: T, handler: Handler<T>): HookUnregister;
+    /**
+     * Unregister a hook handler.
+     * @param hook Name of the hook the handler is registered for
+     * @param handler The handler function that was registered.
+     *                If omitted, all handlers for the hook will be removed.
+     */
+    off<T extends HookName>(hook: T, handler: Handler<T> | DefaultHandler<T>): void;
+    off<T extends HookName>(hook: T): void;
+    /**
+     * Trigger a hook asynchronously, executing its default handler and all registered handlers.
+     * Will execute all handlers in order and `await` any `Promise`s they return.
+     * @param hook Name of the hook to trigger
+     * @param args Arguments to pass to the handler
+     * @param defaultHandler A default implementation of this hook to execute
+     * @returns The resolved return value of the executed default handler
+     */
+    call<T extends HookName>(hook: T, args: HookArguments<T>, defaultHandler?: DefaultHandler<T>): Promise<Awaited<ReturnType<DefaultHandler<T>>>>;
+    /**
+     * Trigger a hook synchronously, executing its default handler and all registered handlers.
+     * Will execute all handlers in order, but will **not** `await` any `Promise`s they return.
+     * @param hook Name of the hook to trigger
+     * @param args Arguments to pass to the handler
+     * @param defaultHandler A default implementation of this hook to execute
+     * @returns The (possibly unresolved) return value of the executed default handler
+     */
+    callSync<T extends HookName>(hook: T, args: HookArguments<T>, defaultHandler?: DefaultHandler<T>): ReturnType<DefaultHandler<T>>;
+    /**
+     * Execute the handlers for a hook, in order, as `Promise`s that will be `await`ed.
+     * @param registrations The registrations (handler + options) to execute
+     * @param args Arguments to pass to the handler
+     */
+    protected run<T extends HookName>(registrations: HookRegistration<T, DefaultHandler<T>>[], args: HookArguments<T>): Promise<Awaited<ReturnType<DefaultHandler<T>>>[]>;
+    protected run<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): Promise<unknown[]>;
+    /**
+     * Execute the handlers for a hook, in order, without `await`ing any returned `Promise`s.
+     * @param registrations The registrations (handler + options) to execute
+     * @param args Arguments to pass to the handler
+     */
+    protected runSync<T extends HookName>(registrations: HookRegistration<T, DefaultHandler<T>>[], args: HookArguments<T>): ReturnType<DefaultHandler<T>>[];
+    protected runSync<T extends HookName>(registrations: HookRegistration<T>[], args: HookArguments<T>): unknown[];
+    /**
+     * Get all registered handlers for a hook, sorted by priority and registration order.
+     * @param hook Name of the hook
+     * @param defaultHandler The optional default handler of this hook
+     * @returns An object with the handlers sorted into `before` and `after` arrays,
+     *          as well as a flag indicating if the original handler was replaced
+     */
+    protected getHandlers<T extends HookName>(hook: T, defaultHandler?: DefaultHandler<T>): {
+        found: boolean;
+        before: HookRegistration<T, Handler<T>>[];
+        handler: HookRegistration<T, DefaultHandler<T>>[];
+        after: HookRegistration<T, Handler<T>>[];
+        replaced: boolean;
+    };
+    /**
+     * Sort two hook registrations by priority and registration order.
+     * @param a The registration object to compare
+     * @param b The other registration object to compare with
+     * @returns The sort direction
+     */
+    protected sortRegistrations<T extends HookName>(a: HookRegistration<T>, b: HookRegistration<T>): number;
+    /**
+     * Dispatch a custom event on the `document` for a hook. Prefixed with `swup:`
+     * @param hook Name of the hook.
+     */
+    protected dispatchDomEvent<T extends HookName>(hook: T, args?: HookArguments<T>): void;
+}
+export {};