@van1s1mys/ai-router 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,172 @@
+/**
+ * Configuration for a single route entry.
+ *
+ * @example
+ * ```ts
+ * const route: RouteConfig = {
+ *   path: '/pricing',
+ *   title: 'Pricing',
+ *   description: 'Plans, pricing, billing, subscription',
+ * };
+ * ```
+ */
+interface RouteConfig {
+    /** URL path of the route (e.g. `"/pricing"`, `"/about/team"`). */
+    path: string;
+    /** Human-readable title used for semantic matching. */
+    title: string;
+    /**
+     * Optional description with keywords/synonyms to improve search accuracy.
+     * The more context you provide, the better the matching quality.
+     */
+    description?: string;
+}
+/**
+ * Options for creating a {@link SmartRouter} instance.
+ *
+ * @example
+ * ```ts
+ * const options: RouteOptions = {
+ *   routes: [
+ *     { path: '/pricing', title: 'Pricing', description: 'cost, plans' },
+ *     { path: '/contact', title: 'Contact', description: 'support, phone' },
+ *   ],
+ *   model: 'Xenova/all-MiniLM-L6-v2',
+ *   threshold: 0.5,
+ * };
+ * ```
+ */
+interface RouteOptions {
+    /** Array of routes to index for semantic search. */
+    routes: RouteConfig[];
+    /**
+     * HuggingFace model ID for generating embeddings.
+     * Must produce 384-dimensional vectors.
+     * @default "Xenova/all-MiniLM-L6-v2"
+     */
+    model?: string;
+    /**
+     * Minimum similarity score (0–1) for a result to be returned.
+     * Results below this threshold are discarded.
+     * @default 0.5
+     */
+    threshold?: number;
+}
+/**
+ * Result returned by {@link SmartRouter.search}.
+ * Contains the best matching route path and its similarity score.
+ */
+interface SearchResult {
+    /** URL path of the matched route. */
+    path: string;
+    /** Similarity score between 0 and 1 (higher = better match). */
+    score: number;
+}
+
+/**
+ * AI-powered semantic search router.
+ *
+ * Runs a HuggingFace embedding model inside a Web Worker and uses
+ * Orama's hybrid (text + vector) search to find the best matching
+ * route for a natural-language query.
+ *
+ * **SSR-safe**: on the server (Node.js), the instance is created
+ * without a worker. `ready` resolves immediately and `search()`
+ * always returns `null`. The worker is only spawned in the browser.
+ *
+ * @example
+ * ```ts
+ * import { SmartRouter } from 'ai-router';
+ *
+ * const router = new SmartRouter({
+ *   routes: [
+ *     { path: '/pricing', title: 'Pricing', description: 'cost, plans, subscription' },
+ *     { path: '/contact', title: 'Contact', description: 'support, phone, address' },
+ *   ],
+ *   threshold: 0.5,
+ * });
+ *
+ * // Wait for the model to load (~22 MB on first run, cached afterwards)
+ * await router.ready;
+ *
+ * // Search by meaning — typos and synonyms work too
+ * const result = await router.search('how much does it cost?');
+ * // → { path: '/pricing', score: 0.87 }
+ *
+ * // Cleanup when done
+ * router.destroy();
+ * ```
+ */
+declare class SmartRouter {
+    private worker;
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private pendingSearches;
+    private destroyed;
+    private readonly ssr;
+    /**
+     * Creates a new SmartRouter instance.
+     *
+     * Spawns a Web Worker, downloads the embedding model, and indexes
+     * all provided routes. The instance is usable after {@link ready} resolves.
+     *
+     * In a server environment (no `Worker` API), the instance is inert:
+     * `ready` resolves immediately and `search()` returns `null`.
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     */
+    constructor(options: RouteOptions);
+    /**
+     * Promise that resolves when the model is loaded and routes are indexed.
+     * Rejects if initialization fails (e.g. network error, invalid model).
+     * Resolves immediately on the server.
+     *
+     * @example
+     * ```ts
+     * await router.ready;
+     * console.log('Model loaded, ready to search');
+     * ```
+     */
+    get ready(): Promise<void>;
+    /** @internal Initializes the worker and sends the INIT message. */
+    private initWorker;
+    /**
+     * Finds the best matching route for a natural-language query.
+     *
+     * Waits for {@link ready} automatically, so it's safe to call
+     * right after construction — the first search will just take longer.
+     *
+     * Returns `null` during SSR (server-side rendering).
+     *
+     * @param query - Free-text search query (e.g. "how to contact support").
+     * @returns The best matching route, or `null` if no route meets the threshold.
+     * @throws If the router has been {@link destroy destroyed} or the worker crashes.
+     *
+     * @example
+     * ```ts
+     * const result = await router.search('where are your offices?');
+     * if (result) {
+     *   window.location.href = result.path; // "/contact"
+     * }
+     * ```
+     */
+    search(query: string): Promise<SearchResult | null>;
+    /**
+     * Terminates the worker and rejects all pending searches.
+     *
+     * After calling `destroy()`, the instance is no longer usable.
+     * Calling `destroy()` multiple times is safe (no-op after the first call).
+     *
+     * @example
+     * ```ts
+     * // In a SPA, destroy when navigating away
+     * onUnmount(() => router.destroy());
+     * ```
+     */
+    destroy(): void;
+    /** @internal Rejects all pending search promises with the given error. */
+    private rejectAllPending;
+}
+
+export { type RouteConfig, type RouteOptions, type SearchResult, SmartRouter };

package/dist/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Configuration for a single route entry.
+ *
+ * @example
+ * ```ts
+ * const route: RouteConfig = {
+ *   path: '/pricing',
+ *   title: 'Pricing',
+ *   description: 'Plans, pricing, billing, subscription',
+ * };
+ * ```
+ */
+interface RouteConfig {
+    /** URL path of the route (e.g. `"/pricing"`, `"/about/team"`). */
+    path: string;
+    /** Human-readable title used for semantic matching. */
+    title: string;
+    /**
+     * Optional description with keywords/synonyms to improve search accuracy.
+     * The more context you provide, the better the matching quality.
+     */
+    description?: string;
+}
+/**
+ * Options for creating a {@link SmartRouter} instance.
+ *
+ * @example
+ * ```ts
+ * const options: RouteOptions = {
+ *   routes: [
+ *     { path: '/pricing', title: 'Pricing', description: 'cost, plans' },
+ *     { path: '/contact', title: 'Contact', description: 'support, phone' },
+ *   ],
+ *   model: 'Xenova/all-MiniLM-L6-v2',
+ *   threshold: 0.5,
+ * };
+ * ```
+ */
+interface RouteOptions {
+    /** Array of routes to index for semantic search. */
+    routes: RouteConfig[];
+    /**
+     * HuggingFace model ID for generating embeddings.
+     * Must produce 384-dimensional vectors.
+     * @default "Xenova/all-MiniLM-L6-v2"
+     */
+    model?: string;
+    /**
+     * Minimum similarity score (0–1) for a result to be returned.
+     * Results below this threshold are discarded.
+     * @default 0.5
+     */
+    threshold?: number;
+}
+/**
+ * Result returned by {@link SmartRouter.search}.
+ * Contains the best matching route path and its similarity score.
+ */
+interface SearchResult {
+    /** URL path of the matched route. */
+    path: string;
+    /** Similarity score between 0 and 1 (higher = better match). */
+    score: number;
+}
+
+/**
+ * AI-powered semantic search router.
+ *
+ * Runs a HuggingFace embedding model inside a Web Worker and uses
+ * Orama's hybrid (text + vector) search to find the best matching
+ * route for a natural-language query.
+ *
+ * **SSR-safe**: on the server (Node.js), the instance is created
+ * without a worker. `ready` resolves immediately and `search()`
+ * always returns `null`. The worker is only spawned in the browser.
+ *
+ * @example
+ * ```ts
+ * import { SmartRouter } from 'ai-router';
+ *
+ * const router = new SmartRouter({
+ *   routes: [
+ *     { path: '/pricing', title: 'Pricing', description: 'cost, plans, subscription' },
+ *     { path: '/contact', title: 'Contact', description: 'support, phone, address' },
+ *   ],
+ *   threshold: 0.5,
+ * });
+ *
+ * // Wait for the model to load (~22 MB on first run, cached afterwards)
+ * await router.ready;
+ *
+ * // Search by meaning — typos and synonyms work too
+ * const result = await router.search('how much does it cost?');
+ * // → { path: '/pricing', score: 0.87 }
+ *
+ * // Cleanup when done
+ * router.destroy();
+ * ```
+ */
+declare class SmartRouter {
+    private worker;
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private pendingSearches;
+    private destroyed;
+    private readonly ssr;
+    /**
+     * Creates a new SmartRouter instance.
+     *
+     * Spawns a Web Worker, downloads the embedding model, and indexes
+     * all provided routes. The instance is usable after {@link ready} resolves.
+     *
+     * In a server environment (no `Worker` API), the instance is inert:
+     * `ready` resolves immediately and `search()` returns `null`.
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     */
+    constructor(options: RouteOptions);
+    /**
+     * Promise that resolves when the model is loaded and routes are indexed.
+     * Rejects if initialization fails (e.g. network error, invalid model).
+     * Resolves immediately on the server.
+     *
+     * @example
+     * ```ts
+     * await router.ready;
+     * console.log('Model loaded, ready to search');
+     * ```
+     */
+    get ready(): Promise<void>;
+    /** @internal Initializes the worker and sends the INIT message. */
+    private initWorker;
+    /**
+     * Finds the best matching route for a natural-language query.
+     *
+     * Waits for {@link ready} automatically, so it's safe to call
+     * right after construction — the first search will just take longer.
+     *
+     * Returns `null` during SSR (server-side rendering).
+     *
+     * @param query - Free-text search query (e.g. "how to contact support").
+     * @returns The best matching route, or `null` if no route meets the threshold.
+     * @throws If the router has been {@link destroy destroyed} or the worker crashes.
+     *
+     * @example
+     * ```ts
+     * const result = await router.search('where are your offices?');
+     * if (result) {
+     *   window.location.href = result.path; // "/contact"
+     * }
+     * ```
+     */
+    search(query: string): Promise<SearchResult | null>;
+    /**
+     * Terminates the worker and rejects all pending searches.
+     *
+     * After calling `destroy()`, the instance is no longer usable.
+     * Calling `destroy()` multiple times is safe (no-op after the first call).
+     *
+     * @example
+     * ```ts
+     * // In a SPA, destroy when navigating away
+     * onUnmount(() => router.destroy());
+     * ```
+     */
+    destroy(): void;
+    /** @internal Rejects all pending search promises with the given error. */
+    private rejectAllPending;
+}
+
+export { type RouteConfig, type RouteOptions, type SearchResult, SmartRouter };