tiny-essentials 1.28.19 → 1.29.1

package/dist/v1/libs/router/TinyRouter.d.mts

@@ -0,0 +1,320 @@
+import * as SegmentExtractor from '../../regexp/SegmentExtractor.mjs';
+import TinyDebugger from '../tools/TinyDebugger.mjs';
+export type RouterHistoryEntry = {
+    /**
+     * - The URL path recorded in history.
+     */
+    path: string;
+    /**
+     * - The Unix timestamp when this path was visited.
+     */
+    timestamp: number;
+};
+export type SegExResultExtra = {
+    /**
+     * - Stored to allow removal by string.
+     */
+    pattern?: string;
+};
+export type AddRouteOptionsWithFunction = {
+    /**
+     * - A function used to process the pattern.
+     */
+    callback: import('../../regexp/SegmentExtractor.mjs').SegExFunction;
+    /**
+     * - Stored to allow removal by string.
+     */
+    pattern: string;
+};
+export type SegExResult = import('../../regexp/SegmentExtractor.mjs').SegExResult & SegExResultExtra;
+export type AddRouteOptions = {
+    /**
+     * - Stored to allow removal by string.
+     */
+    pattern: string;
+    /**
+     * - The search pattern (string or RegExp) used to identify dynamic segments.
+     */
+    searchValue: string | RegExp;
+    /**
+     * - The function defining how to transform a segment into a capture group.
+     */
+    replaceValue: import('../../regexp/SegmentExtractor.mjs').SegExReplacer;
+    /**
+     * - Optional configuration to customize error messages.
+     */
+    errorConfig: import('../../regexp/SegmentExtractor.mjs').SegExErrorConfig;
+};
+export type RouteMatch = {
+    /**
+     * - The matched URL path.
+     */
+    path: string;
+    /**
+     * - The dynamic parameters extracted from the path.
+     */
+    params: Record<string, string>;
+    /**
+     * - The URL search parameters.
+     */
+    query: URLSearchParams;
+};
+export type RouteNotFoundData = {
+    /**
+     * - The path that failed to match.
+     */
+    path: string;
+    /**
+     * - The URL search parameters.
+     */
+    query: URLSearchParams;
+};
+export type RouteCallback = (match: RouteMatch) => Promise<void> | void;
+export type RouteNotFoundCallback = (match: RouteNotFoundData) => void;
+export type RouterOptions = {
+    /**
+     * - Whether to enable internal debug logging.
+     */
+    debugMode?: boolean;
+    /**
+     * - Whether to enable log color support.
+     */
+    useLogColors?: boolean;
+    /**
+     * - Whether to detect if the history navigation actually changed the URL.
+     */
+    detectHistoryChange?: boolean;
+    /**
+     * - A custom logger object (must implement console methods).
+     */
+    logger?: Partial<Console>;
+    /**
+     * - Callback executed whenever the route changes.
+     */
+    onRouteChanged?: RouteCallback;
+    /**
+     * - Callback executed when no route matches.
+     */
+    onRouteNotFound?: RouteNotFoundCallback;
+    /**
+     * - Maximum number of history entries. Use -1 for unlimited, or 0 to disable history.
+     */
+    historyLimit?: number;
+};
+export type RouteDefinition = {
+    /**
+     * - The extraction logic and metadata used to match the path and retrieve parameters.
+     */
+    segmentExtractor: SegExResult;
+    /**
+     * - The function to execute on match.
+     */
+    callback: RouteCallback;
+};
+/**
+ * Represents a single entry in the navigation history.
+ * @typedef {Object} RouterHistoryEntry
+ * @property {string} path - The URL path recorded in history.
+ * @property {number} timestamp - The Unix timestamp when this path was visited.
+ */
+/**
+ * Additional metadata stored alongside segment extraction results.
+ * @typedef {Object} SegExResultExtra
+ * @property {string} [pattern] - Stored to allow removal by string.
+ */
+/**
+ * Configuration for registering a route using a function to generate the pattern.
+ * @typedef {Object} AddRouteOptionsWithFunction
+ * @property {import('../../regexp/SegmentExtractor.mjs').SegExFunction} callback - A function used to process the pattern.
+ * @property {string} pattern - Stored to allow removal by string.
+ */
+/**
+ * The result of a segment extraction combined with additional metadata.
+ * @typedef {import('../../regexp/SegmentExtractor.mjs').SegExResult & SegExResultExtra} SegExResult
+ */
+/**
+ * Configuration for registering a route using a custom segment extraction pattern.
+ * @typedef {Object} AddRouteOptions
+ * @property {string} pattern - Stored to allow removal by string.
+ * @property {string|RegExp} searchValue - The search pattern (string or RegExp) used to identify dynamic segments.
+ * @property {import('../../regexp/SegmentExtractor.mjs').SegExReplacer} replaceValue - The function defining how to transform a segment into a capture group.
+ * @property {import('../../regexp/SegmentExtractor.mjs').SegExErrorConfig} errorConfig - Optional configuration to customize error messages.
+ */
+/**
+ * Data structure containing the results of a successful route match.
+ * @typedef {Object} RouteMatch
+ * @property {string} path - The matched URL path.
+ * @property {Record<string, string>} params - The dynamic parameters extracted from the path.
+ * @property {URLSearchParams} query - The URL search parameters.
+ */
+/**
+ * Data structure containing details when no route matches the current URL.
+ * @typedef {Object} RouteNotFoundData
+ * @property {string} path - The path that failed to match.
+ * @property {URLSearchParams} query - The URL search parameters.
+ */
+/**
+ * A function executed when a route is successfully matched.
+ * @callback RouteCallback
+ * @param {RouteMatch} match - The object containing path, params, and query.
+ * @returns {Promise<void>|void} - A promise or void indicating completion.
+ */
+/**
+ * A function executed when no route matches the current URL.
+ * @callback RouteNotFoundCallback
+ * @param {RouteNotFoundData} match - The object containing path and query.
+ * @returns {void}
+ */
+/**
+ * Configuration options for initializing the TinyRouter instance.
+ * @typedef {Object} RouterOptions
+ * @property {boolean} [debugMode=false] - Whether to enable internal debug logging.
+ * @property {boolean} [useLogColors=false] - Whether to enable log color support.
+ * @property {boolean} [detectHistoryChange=true] - Whether to detect if the history navigation actually changed the URL.
+ * @property {Partial<Console>} [logger=console] - A custom logger object (must implement console methods).
+ * @property {RouteCallback} [onRouteChanged] - Callback executed whenever the route changes.
+ * @property {RouteNotFoundCallback} [onRouteNotFound] - Callback executed when no route matches.
+ * @property {number} [historyLimit=0] - Maximum number of history entries. Use -1 for unlimited, or 0 to disable history.
+ */
+/**
+ * A definition of a route, combining its pattern extractor and its execution callback.
+ * @typedef {Object} RouteDefinition
+ * @property {SegExResult} segmentExtractor - The extraction logic and metadata used to match the path and retrieve parameters.
+ * @property {RouteCallback} callback - The function to execute on match.
+ */
+/**
+ * A lightweight, framework-agnostic router for managing client-side navigation.
+ */
+declare class TinyRouter extends TinyDebugger {
+    #private;
+    /** The SegmentExtractor module. */
+    static SegmentExtractor: typeof SegmentExtractor;
+    /**
+     * @param {RouterOptions} [options={}] - Configuration options for the router.
+     * @throws {TypeError} If options is not an object or if the logger lacks required methods.
+     */
+    constructor(options?: RouterOptions);
+    /** @returns {boolean} Returns whether the router instance has been destroyed. */
+    get isDestroyed(): boolean;
+    /** @returns {number} Returns the current position in history. */
+    get historyIndex(): number;
+    /** @returns {number} Returns the maximum number of history entries allowed. */
+    get historyLimit(): number;
+    /** @returns {boolean} Returns whether the router detects changes in history navigation. */
+    get detectHistoryChange(): boolean;
+    /** @param {boolean} value Sets whether the router detects changes in history navigation. */
+    set detectHistoryChange(value: boolean);
+    /** @returns {RouteCallback} Returns the callback function for route changes. */
+    get onRouteChanged(): RouteCallback;
+    /** @param {RouteCallback} value Sets the callback function for route changes. */
+    set onRouteChanged(value: RouteCallback);
+    /** @returns {RouteNotFoundCallback} Returns the callback function for unmatched routes. */
+    get onRouteNotFound(): RouteNotFoundCallback;
+    /** @param {RouteNotFoundCallback} value Sets the callback function for unmatched routes. */
+    set onRouteNotFound(value: RouteNotFoundCallback);
+    /** @returns {boolean} Returns whether the router is currently active. */
+    get started(): boolean;
+    /**
+     * Returns the current number of registered routes.
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Returns an array of all registered path patterns.
+     * @returns {string[]} An array of path pattern strings.
+     */
+    get routes(): string[];
+    /**
+     * Returns a copy of the current navigation history.
+     * @returns {RouterHistoryEntry[]} An array of history entries.
+     */
+    get history(): RouterHistoryEntry[];
+    /**
+     * Imports and validates a history log to restore previous navigation state.
+     * @param {RouterHistoryEntry[]} historyData - The array of history entries to import.
+     * @throws {TypeError} If historyData is not an array or if any entry is invalid.
+     */
+    set history(historyData: RouterHistoryEntry[]);
+    /**
+     * Registers a new route pattern.
+     * @param {string | AddRouteOptions | AddRouteOptionsWithFunction} patternOrOptions -
+     *    A path pattern string (e.g., '/user/:id') OR a configuration object for custom regex.
+     * @param {RouteCallback} callback - Function to execute when this route is matched.
+     * @throws {TypeError} If arguments are invalid.
+     * @throws {Error} If the route pattern is already registered.
+     */
+    add(patternOrOptions: string | AddRouteOptions | AddRouteOptionsWithFunction, callback: RouteCallback): void;
+    /**
+     * Removes a registered route by its original pattern string.
+     * @param {string} pathPattern - The pattern to remove.
+     * @throws {TypeError} If pathPattern is not a string.
+     */
+    remove(pathPattern: string): void;
+    /**
+     * Checks if a route pattern is already registered.
+     * @param {string} pathPattern - The pattern to check.
+     * @returns {boolean} True if the route exists, false otherwise.
+     * @throws {TypeError} If pathPattern is not a string.
+     */
+    has(pathPattern: string): boolean;
+    /**
+     * Navigates to a specific path programmatically.
+     * @param {string | URL | null | undefined} path - The target path.
+     * @param {any} [state={}] - Optional state object to associate with history.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If path is not a string or state is not an object.
+     */
+    navigate(path: string | URL | null | undefined, state?: any): Promise<void>;
+    /**
+     * Triggers the initial route resolution (for deep linking on page load).
+     * @returns {Promise<void>}
+     * @throws {Error} If the router has already been started.
+     */
+    start(): Promise<void>;
+    /**
+     * Cleans up the router, removes event listeners, and stops the router.
+     */
+    stop(): void;
+    /**
+     * Navigates to a specific number of steps in the browser's history.
+     * @param {number} delta - The number of steps to move (positive for forward, negative for backward).
+     * @returns {Promise<boolean>} A promise that resolves to true if the URL changed, false otherwise.
+     * @throws {TypeError} If delta is not an integer.
+     */
+    go(delta: number): Promise<boolean>;
+    /**
+     * Navigates to the previous entry in the browser's history stack.
+     * @returns {Promise<boolean>} A promise that resolves to true if the URL changed, false otherwise.
+     */
+    back(): Promise<boolean>;
+    /**
+     * Navigates to the next entry in the browser's history stack.
+     * @returns {Promise<boolean>} A promise that resolves to true if the URL changed, false otherwise.
+     */
+    forward(): Promise<boolean>;
+    /**
+     * Removes a specific entry from the navigation history by its index.
+     * @param {number} index - The index of the entry to remove.
+     * @throws {TypeError} If index is not an integer.
+     * @throws {RangeError} If the index is out of bounds.
+     */
+    removeHistoryEntry(index: number): void;
+    /**
+     * Clears all entries from the navigation history.
+     */
+    clearHistory(): void;
+    /**
+     * Removes all registered routes.
+     */
+    clear(): void;
+    /**
+     * Removes all instance data.
+     */
+    clearAll(): void;
+    /**
+     * Destroy the instance.
+     */
+    destroy(): void;
+}
+export default TinyRouter;
+//# sourceMappingURL=TinyRouter.d.mts.map

package/dist/v1/libs/router/TinyRouter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TinyRouter.d.mts","sourceRoot":"","sources":["../../../../src/v1/libs/router/TinyRouter.mjs"],"names":[],"mappings":"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"}