@hybridly/core 0.0.1-dev.2

package/dist/index.d.ts

@@ -0,0 +1,367 @@
+import { RequestData } from '@hybridly/utils';
+import { AxiosResponse, AxiosProgressEvent } from 'axios';
+
+declare type MaybePromise<T> = T | Promise<T>;
+
+interface Hooks {
+    /**
+     * Called before anything when a visit is going to happen.
+     */
+    before: (options: VisitOptions) => MaybePromise<any | boolean>;
+    /**
+     * Called before the request of a visit is going to happen.
+     */
+    start: (context: InternalRouterContext) => MaybePromise<any>;
+    /**
+     * Called when progress on the request is being made.
+     */
+    progress: (progress: Progress) => MaybePromise<any>;
+    /**
+     * Called when data is received after a request for a visit.
+     */
+    data: (response: AxiosResponse) => MaybePromise<any>;
+    /**
+     * Called when a request is successful and there is no error.
+     */
+    success: (payload: VisitPayload) => MaybePromise<any>;
+    /**
+     * Called when a request is successful but there were errors.
+     */
+    error: (errors: Errors) => MaybePromise<any>;
+    /**
+     * Called when a request has been aborted.
+     */
+    abort: (context: InternalRouterContext) => MaybePromise<any>;
+    /**
+     * Called when a response to a request is not a valid Hybridly response.
+     */
+    invalid: (response: AxiosResponse) => MaybePromise<void>;
+    /**
+     * Called when an unknowne exception was triggered.
+     */
+    exception: (error: Error) => MaybePromise<void>;
+    /**
+     * Called whenever the request failed, for any reason, in addition to other hooks.
+     */
+    fail: (context: InternalRouterContext) => MaybePromise<void>;
+    /**
+     * Called after a request has been made, even if it didn't succeed.
+     */
+    after: (context: InternalRouterContext) => MaybePromise<void>;
+    /**
+     * Called when a visit has been made and a page component has been navigated to.
+     */
+    navigate: (options: NavigationOptions) => MaybePromise<void>;
+}
+/**
+ * Registers a global hook.
+ */
+declare function registerHook<T extends keyof Hooks>(hook: T, fn: Hooks[T]): () => void;
+/**
+ * Registers a global hook that will run only once.
+ */
+declare function registerHookOnce<T extends keyof Hooks>(hook: T, fn: Hooks[T]): void;
+
+interface Plugin {
+    name: string;
+    initialized: (context: InternalRouterContext) => MaybePromise<void>;
+    hooks: Partial<Hooks>;
+}
+declare function definePlugin(plugin: Plugin): Plugin;
+
+/** Options for creating a router context. */
+interface RouterContextOptions {
+    /** The initial payload served by the browser. */
+    payload: VisitPayload;
+    /** Adapter-specific functions. */
+    adapter: Adapter;
+    /** History state serializer. */
+    serializer?: Serializer;
+    /** List of plugins. */
+    plugins?: Plugin[];
+}
+/** Router context. */
+interface InternalRouterContext {
+    /** The current, normalized URL. */
+    url: string;
+    /** The current view. */
+    view: View;
+    /** The current, optional dialog. */
+    dialog?: View;
+    /** The current local asset version. */
+    version: string;
+    /** The current adapter's functions. */
+    adapter: Adapter;
+    /** Scroll positions of the current page's DOM elements. */
+    scrollRegions: ScrollRegion[];
+    /** Arbitrary state. */
+    state: Record<string, any>;
+    /** Currently pending visit. */
+    activeVisit?: PendingVisit;
+    /** History state serializer. */
+    serializer: Serializer;
+    /** List of plugins. */
+    plugins: Plugin[];
+    /** Global hooks. */
+    hooks: Partial<Record<keyof Hooks, Array<Function>>>;
+}
+/** Router context. */
+declare type RouterContext = Readonly<InternalRouterContext>;
+/** Adapter-specific functions. */
+interface Adapter {
+    /** Resolves a component from the given name. */
+    resolveComponent: ResolveComponent;
+    /** Swaps to the given view. */
+    swapView: SwapView;
+    /** Swaps to the given dialog. */
+    swapDialog: SwapDialog;
+    /** Called when the context is updated. */
+    update?: (context: InternalRouterContext) => void;
+}
+interface ScrollRegion {
+    top: number;
+    left: number;
+}
+/** Provides methods to serialize the state into the history state. */
+interface Serializer {
+    serialize: <T>(view: T) => any;
+    unserialize: <T>(state: any) => T;
+}
+
+/** Gets the current context. */
+declare function getRouterContext(): RouterContext;
+
+declare type UrlResolvable = string | URL | Location;
+declare type UrlTransformable = Partial<Omit<URL, 'searchParams' | 'toJSON' | 'toString'>>;
+/**
+ * Converts an input to an URL, optionally changing its properties after initialization.
+ */
+declare function makeUrl(href: UrlResolvable, transformations?: UrlTransformable): URL;
+/**
+ * Checks if the given URLs have the same origin and path.
+ */
+declare function sameUrls(...hrefs: UrlResolvable[]): boolean;
+
+declare type ConditionalNavigationOption = boolean | ((payload: VisitPayload) => boolean);
+interface LocalVisitOptions {
+    /** Name of the component to use. */
+    component?: string;
+    /** Properties to apply to the component. */
+    properties: Properties;
+    /**
+     * Whether to replace the current history state instead of adding
+     * one. This affects the browser's "back" and "forward" features.
+     */
+    replace?: ConditionalNavigationOption;
+    /** Whether to preserve the current scrollbar position. */
+    preserveScroll?: ConditionalNavigationOption;
+    /** Whether to preserve the current page component state. */
+    preserveState?: ConditionalNavigationOption;
+}
+interface NavigationOptions {
+    /** View to navigate to. */
+    payload?: VisitPayload;
+    /**
+     * Whether to replace the current history state instead of adding
+     * one. This affects the browser's "back" and "forward" features.
+     */
+    replace?: ConditionalNavigationOption;
+    /** Whether to preserve the current scrollbar position. */
+    preserveScroll?: ConditionalNavigationOption;
+    /** Whether to preserve the current page component's state. */
+    preserveState?: ConditionalNavigationOption;
+    /** Whether to preserve the current URL. */
+    preserveUrl?: ConditionalNavigationOption;
+    /**
+     * Properties of the given URL to override.
+     * @example
+     * ```ts
+     * router.get('/login?redirect=/', {
+     * 	transformUrl: { search: '' }
+     * }
+     * ```
+     */
+    transformUrl?: UrlTransformable;
+    /**
+     * Defines whether the history state should be updated.
+     * @internal This is an advanced property meant to be used internally.
+     */
+    updateHistoryState?: boolean;
+    /**
+     * Defines whether this navigation is a back/forward visit from the popstate event.
+     * @internal This is an advanced property meant to be used internally.
+     */
+    isBackForward?: boolean;
+}
+declare type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+interface VisitOptions extends Omit<NavigationOptions, 'request'> {
+    /** The URL to visit. */
+    url?: UrlResolvable;
+    /** HTTP verb to use for the request. */
+    method?: Method;
+    /** Body of the request. */
+    data?: RequestData;
+    /** Which properties to update for this visit. Other properties will be ignored. */
+    only?: string | string[];
+    /** Which properties not to update for this visit. Other properties will be updated. */
+    except?: string | string[];
+    /** Specific headers to add to the request. */
+    headers?: Record<string, string>;
+    /** The bag in which to put potential errors. */
+    errorBag?: string;
+    /** Hooks for this visit. */
+    hooks?: Partial<Hooks>;
+    /** If `true`, force the usage of a `FormData` object. */
+    useFormData?: boolean;
+}
+interface VisitResponse {
+    response?: AxiosResponse;
+    error?: {
+        type: string;
+        actual: Error;
+    };
+}
+interface Router {
+    /** Aborts the currently pending visit, if any. */
+    abort: () => Promise<void>;
+    /** Checks if there is an active request. */
+    active: () => boolean;
+    /** Makes a visit with the given options. */
+    visit: (options: VisitOptions) => Promise<VisitResponse>;
+    /** Reloads the current page. */
+    reload: (options?: VisitOptions) => Promise<VisitResponse>;
+    /** Makes a GET request to the given URL. */
+    get: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    /** Makes a POST request to the given URL. */
+    post: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    /** Makes a PUT request to the given URL. */
+    put: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    /** Makes a PATCH request to the given URL. */
+    patch: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    /** Makes a DELETE request to the given URL. */
+    delete: (url: UrlResolvable, options?: Omit<VisitOptions, 'method' | 'url'>) => Promise<VisitResponse>;
+    /** Navigates to the given external URL. Alias for `document.location.href`. */
+    external: (url: UrlResolvable, data?: VisitOptions['data']) => void;
+    /** Navigates to the given URL without a server round-trip. */
+    local: (url: UrlResolvable, options: LocalVisitOptions) => Promise<void>;
+    /** Access the history state. */
+    history: {
+        /** Remembers a value for the given route. */
+        remember: (key: string, value: any) => void;
+        /** Gets a remembered value. */
+        get: <T = any>(key: string) => T | undefined;
+    };
+}
+/** An axios visit being made. */
+interface PendingVisit {
+    /** The URL to which the request is being made. */
+    url: URL;
+    /** Abort controller associated to this request. */
+    controller: AbortController;
+    /** Options for the associated visit. */
+    options: VisitOptions;
+    /** Visit identifier. */
+    id: string;
+}
+/** A page or dialog component. */
+interface View {
+    /** Name of the component to use. */
+    name: string;
+    /** Properties to apply to the component. */
+    properties: Properties;
+}
+declare type Property = null | string | number | boolean | Property[] | {
+    [name: string]: Property;
+};
+declare type Properties = Record<string | number, Property>;
+interface SwapOptions<T> {
+    /** The new component. */
+    component: T;
+    /** Whether to preserve the state of the component. */
+    preserveState?: boolean;
+}
+declare type ViewComponent = any;
+declare type DialogComponent = any;
+declare type ResolveComponent = (name: string) => Promise<ViewComponent>;
+declare type SwapView = (options: SwapOptions<ViewComponent>) => Promise<void>;
+declare type SwapDialog = (options: SwapOptions<DialogComponent>) => Promise<void>;
+/** The payload of a visit request from the server. */
+interface VisitPayload {
+    /** The view to use in this request. */
+    view: View;
+    /** An optional dialog. */
+    dialog?: View;
+    /** The current page URL. */
+    url: string;
+    /** The current asset version. */
+    version: string;
+}
+interface Progress {
+    /** Base event. */
+    event: AxiosProgressEvent;
+    /** Computed percentage. */
+    percentage: Readonly<number>;
+}
+interface Errors {
+    [key: string]: string;
+}
+
+/**
+ * The hybridly router.
+ * This is the core function that you can use to navigate in
+ * your application. Make sure the routes you call return a
+ * hybridly response, otherwise you need to call `external`.
+ *
+ * @example
+ * router.get('/posts/edit', { post })
+ */
+declare const router: Router;
+/** Creates the hybridly router. */
+declare function createRouter(options: RouterContextOptions): Promise<InternalRouterContext>;
+
+interface Authorizable<Authorizations extends Record<string, boolean>> {
+    authorization: Authorizations;
+}
+/**
+ * Checks whether the given data has the authorization for the given action.
+ * If the data object has no authorization definition corresponding to the given action, this method will return `false`.
+ */
+declare function can<Authorizations extends Record<string, boolean>, Data extends Authorizable<Authorizations>, Action extends keyof Data['authorization']>(resource: Data, action: Action): Authorizations[Action];
+
+declare const STORAGE_EXTERNAL_KEY = "hybridly:external";
+declare const HYBRIDLY_HEADER = "x-hybridly";
+declare const EXTERNAL_VISIT_HEADER: string;
+declare const PARTIAL_COMPONENT_HEADER: string;
+declare const ONLY_DATA_HEADER: string;
+declare const EXCEPT_DATA_HEADER: string;
+declare const CONTEXT_HEADER: string;
+declare const VERSION_HEADER: string;
+declare const ERROR_BAG_HEADER: string;
+declare const SCROLL_REGION_ATTRIBUTE = "scroll-region";
+
+declare const constants_STORAGE_EXTERNAL_KEY: typeof STORAGE_EXTERNAL_KEY;
+declare const constants_HYBRIDLY_HEADER: typeof HYBRIDLY_HEADER;
+declare const constants_EXTERNAL_VISIT_HEADER: typeof EXTERNAL_VISIT_HEADER;
+declare const constants_PARTIAL_COMPONENT_HEADER: typeof PARTIAL_COMPONENT_HEADER;
+declare const constants_ONLY_DATA_HEADER: typeof ONLY_DATA_HEADER;
+declare const constants_EXCEPT_DATA_HEADER: typeof EXCEPT_DATA_HEADER;
+declare const constants_CONTEXT_HEADER: typeof CONTEXT_HEADER;
+declare const constants_VERSION_HEADER: typeof VERSION_HEADER;
+declare const constants_ERROR_BAG_HEADER: typeof ERROR_BAG_HEADER;
+declare const constants_SCROLL_REGION_ATTRIBUTE: typeof SCROLL_REGION_ATTRIBUTE;
+declare namespace constants {
+  export {
+    constants_STORAGE_EXTERNAL_KEY as STORAGE_EXTERNAL_KEY,
+    constants_HYBRIDLY_HEADER as HYBRIDLY_HEADER,
+    constants_EXTERNAL_VISIT_HEADER as EXTERNAL_VISIT_HEADER,
+    constants_PARTIAL_COMPONENT_HEADER as PARTIAL_COMPONENT_HEADER,
+    constants_ONLY_DATA_HEADER as ONLY_DATA_HEADER,
+    constants_EXCEPT_DATA_HEADER as EXCEPT_DATA_HEADER,
+    constants_CONTEXT_HEADER as CONTEXT_HEADER,
+    constants_VERSION_HEADER as VERSION_HEADER,
+    constants_ERROR_BAG_HEADER as ERROR_BAG_HEADER,
+    constants_SCROLL_REGION_ATTRIBUTE as SCROLL_REGION_ATTRIBUTE,
+  };
+}
+
+export { Authorizable, MaybePromise, Method, Plugin, ResolveComponent, Router, RouterContext, RouterContextOptions, UrlResolvable, VisitOptions, VisitPayload, VisitResponse, can, constants, createRouter, definePlugin, getRouterContext, makeUrl, registerHook, registerHookOnce, router, sameUrls };