@void-snippets/react 0.2.2 → 0.6.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import * as _tanstack_react_query from '@tanstack/react-query';
-import { ResourceAdapters, TQueryParams, TPagination, ResourceListResult } from '@void-snippets/core';
+import { InfiniteData } from '@tanstack/react-query';
+import { VSAdapters, VSQueryParams, VSPagination, VSListResult } from '@void-snippets/core';
+import { Socket } from 'socket.io-client';
+import { ReactNode } from 'react';
 
-type CapitalizeStr<S extends string> = S extends `${infer F}${infer Rest}` ? `${Uppercase<F>}${Rest}` : S;
 interface WithResourceTypes {
     readonly __types: {
         id: unknown;
@@ -20,88 +22,621 @@ type Create<S extends WithResourceTypes> = S["__types"]["create"];
 type Update<S extends WithResourceTypes> = S["__types"]["update"];
 type ListRaw<S extends WithResourceTypes> = S["__types"]["listRaw"];
 type SingleRaw<S extends WithResourceTypes> = S["__types"]["singleRaw"];
-type UseListReturn<K extends string, TBase> = {
-    [P in K]: TBase[];
-} & {
-    pagination: TPagination;
-} & {
-    [P in `is${CapitalizeStr<K>}Loading`]: boolean;
-} & {
-    [P in `${K}Error`]: Error | null;
-} & {
-    [P in `invalidate${CapitalizeStr<K>}`]: () => void;
+interface VSUseListReturn<TBase> {
+    list: TBase[];
+    pagination: VSPagination;
+    /**
+     * True only on the very first fetch when there is no cached data yet.
+     * Use this to render a full-page spinner or skeleton.
+     * Does NOT become true during background refetches — for that see `isRefetching`.
+     */
+    isLoading: boolean;
+    /**
+     * True during any fetch in progress — initial load or background refetch.
+     * Use for a subtle progress indicator that doesn't blank out the list.
+     */
+    isFetching: boolean;
+    /**
+     * True during a background refetch while cached data is already present.
+     * Equivalent to `isFetching && !isLoading`.
+     * Use for a lightweight "Refreshing…" badge overlaid on the existing list.
+     */
+    isRefetching: boolean;
+    /** True when the last fetch attempt resulted in an error. */
+    isError: boolean;
+    error: Error | null;
+    /**
+     * Re-runs this specific query. Wire to a retry button in your error state.
+     * Narrower than `invalidate` — only refetches this exact param variant.
+     */
+    refetch: () => Promise<unknown>;
+    /**
+     * Marks all active queries under this resource prefix as stale and
+     * triggers a background refetch. Broader than `refetch` — affects every
+     * mounted param variant of this resource simultaneously.
+     */
+    invalidate: () => void;
+}
+interface VSUseGetReturn<TDetail> {
+    item: TDetail | undefined;
+    /** True only on the first fetch when no cached data exists. */
+    isLoading: boolean;
+    /** True during any fetch in progress. */
+    isFetching: boolean;
+    /** True during a background refetch while cached data is already present. */
+    isRefetching: boolean;
+    /** True when the last fetch attempt resulted in an error. */
+    isError: boolean;
+    error: Error | null;
+    /** Re-runs this query. */
+    refetch: () => Promise<unknown>;
+}
+/**
+ * The operation context passed to `onError` and `onSuccess` callbacks.
+ * Discriminate by `kind` to handle each mutation type differently.
+ */
+type VSOptimisticOperation<TId, TCreate, TUpdate> = {
+    kind: "create";
+    payload: TCreate;
+    tempId: string;
+} | {
+    kind: "update";
+    _id: TId;
+    payload: TUpdate;
+} | {
+    kind: "remove";
+    _id: TId;
 };
-interface CreateResourceHooksOptions<TListRaw, TBase, TSingleRaw, TDetail> {
+interface VSOptimisticHandlers<TBase, TId, TUpdate, TCreate = Partial<TBase>, TDetail = TBase> {
     /**
-     * Adapters map your API's raw response shapes to the library's internal
-     * format. Omit this entirely if your API matches the default shape:
-     * List:   { data: { items, page, limit, totalPages, totalDocuments } }
-     * Single: { data: <item> }
+     * Optimistically transforms the list when `update.mutate()` fires.
+     * `_id` is the mutation target — it is **separate** from `payload`.
+     * Applied to every active `useList` and `useInfinite` cache.
+     * The `useGet` cache is shallow-merged automatically; override with `updateSingle`.
+     * Return a new array — never mutate `cache` in place.
      *
      * @example
-     * createResourceHooks("contacts", ContactsApis, {
-     *   adapters: {
-     *     fromList: (raw) => ({
-     *       items: raw.results,
-     *       pagination: {
-     *         page: raw.meta.page,
-     *         limit: raw.meta.perPage,
-     *         totalPages: raw.meta.lastPage,
-     *         totalDocuments: raw.meta.total,
-     *       },
-     *     }),
-     *     fromSingle: (raw) => raw.payload,
-     *   },
-     * })
-     */
-    adapters?: ResourceAdapters<TListRaw, TBase, TSingleRaw, TDetail>;
-    /**
-     * Default params passed to useList and useInfinite when none are provided.
-     * @default { page: 1, limit: 10 }
-     */
-    defaultParams?: TQueryParams;
+     * update: (cache, { _id, payload }) =>
+     *   cache.map(item => item._id === _id ? { ...item, ...payload } : item)
+     */
+    update?: (cache: TBase[], args: {
+        _id: TId;
+        payload: TUpdate;
+    }) => TBase[];
+    /**
+     * Overrides the default `{ ...current, ...payload }` shallow-merge for the
+     * `useGet` cache. Only needed when `TDetail` has nested objects requiring
+     * a deep merge. Ignored if `update` is not also provided.
+     */
+    updateSingle?: (current: TDetail, payload: TUpdate) => TDetail;
+    /**
+     * Optimistically removes an item when `remove.mutate()` fires.
+     * `totalDocuments` / `totalPages` are patched automatically from the diff.
+     * The matching `useGet` entry is staled (keeps showing data until confirmed).
+     * Return a new array — never mutate `cache` in place.
+     *
+     * @example
+     * remove: (cache, id) => cache.filter(item => item._id !== id)
+     */
+    remove?: (cache: TBase[], id: TId) => TBase[];
+    /**
+     * Optimistically inserts an item when `create.mutate()` fires.
+     * Applied to every `useList` cache and the **first page** of every
+     * `useInfinite` cache. `totalDocuments` / `totalPages` are patched automatically.
+     * `tempId` is a library-generated UUID — use it to set `_id` on the item.
+     * Return a new array — never mutate `cache` in place.
+     *
+     * @example
+     * create: (cache, { payload, tempId }) => [
+     *   { ...payload, _id: tempId as Contact.Id },
+     *   ...cache,
+     * ]
+     */
+    create?: (cache: TBase[], args: {
+        payload: TCreate;
+        tempId: string;
+    }) => TBase[];
+    /**
+     * Called after the optimistic rollback completes when a mutation fails.
+     * The cache is already restored to the correct state when this fires.
+     * Use for resource-level error notifications across all call sites.
+     *
+     * @example
+     * onError: (error, operation) => {
+     *   toast.error(`Failed to ${operation.kind} item: ${error.message}`)
+     * }
+     */
+    onError?: (error: Error, operation: VSOptimisticOperation<TId, TCreate, TUpdate>) => void;
+    /**
+     * Called after `effectiveBase` has been advanced for this operation.
+     * Fires once per successfully confirmed mutation, before the final
+     * invalidation when all pending operations have settled.
+     *
+     * @example
+     * onSuccess: (operation) => {
+     *   if (operation.kind === 'create') analytics.track('item_created')
+     * }
+     */
+    onSuccess?: (operation: VSOptimisticOperation<TId, TCreate, TUpdate>) => void;
 }
-/**
- * Creates a set of TanStack Query hooks for a resource.
- * All types are fully inferred from the `apiService` instance — no generics
- * need to be passed manually.
- *
- * @param queryKeyPrefix  - TanStack Query cache key prefix and the base name
- *                          for the returned hook properties.
- *                          e.g. "contacts" → { contacts, isContactsLoading, ... }
- * @param apiService      - An instance of ResourceService (or a subclass).
- * @param options         - Optional adapters and default params.
- *
- * @example
- * // contacts.hooks.ts
- * import { createResourceHooks } from '@void-snippets/react';
- * import { ContactsApis } from './contacts.api';
- *
- * // No generics needed — all types are inferred from ContactsApis
- * export const contactHooks = createResourceHooks('contacts', ContactsApis);
- *
- * // In a component:
- * const { contacts, isContactsLoading } = contactHooks.useList();
- * const { data } = contactHooks.useGet(id);  // data: Contact.WithCreatedBy
- * const { create, update, delete: remove } = contactHooks.useMutations();
- */
-declare function createResourceHooks<K extends string, S extends WithResourceTypes>(queryKeyPrefix: K, apiService: S, options?: CreateResourceHooksOptions<ListRaw<S>, Base<S>, SingleRaw<S>, Detail<S>>): {
-    useList: (params?: TQueryParams) => UseListReturn<K, Base<S>>;
-    useGet: (id: Id<S>, staleTime?: number) => {
-        data: _tanstack_react_query.NoInfer<Detail<S>> | undefined;
-        isLoading: boolean;
-        error: Error | null;
-        refetch: (options?: _tanstack_react_query.RefetchOptions) => Promise<_tanstack_react_query.QueryObserverResult<_tanstack_react_query.NoInfer<Detail<S>>, Error>>;
-    };
+interface VSResourceHooksOptions<TListRaw, TBase, TSingleRaw, TDetail, TId = unknown, TUpdate = unknown, TCreate = unknown> {
+    adapters?: VSAdapters<TListRaw, TBase, TSingleRaw, TDetail>;
+    defaultParams?: VSQueryParams;
+    optimistic?: VSOptimisticHandlers<TBase, TId, TUpdate, TCreate, TDetail>;
+}
+type MutationContext = {
+    operationId: symbol;
+};
+declare function createResourceHooks<K extends string, S extends WithResourceTypes>(queryKeyPrefix: K, apiService: S, options?: VSResourceHooksOptions<ListRaw<S>, Base<S>, SingleRaw<S>, Detail<S>, Id<S>, Update<S>, Create<S>>): {
+    useList: (params?: VSQueryParams) => VSUseListReturn<Base<S>>;
+    useGet: (id: Id<S>, staleTime?: number) => VSUseGetReturn<Detail<S>>;
     useMutations: () => {
-        create: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Create<S>, unknown>;
+        create: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Create<S>, MutationContext | undefined>;
         update: _tanstack_react_query.UseMutationResult<Detail<S>, Error, {
             _id: Id<S>;
             payload: Update<S>;
-        }, unknown>;
-        delete: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Id<S>, unknown>;
+        }, MutationContext | undefined>;
+        remove: _tanstack_react_query.UseMutationResult<Detail<S>, Error, Id<S>, MutationContext | undefined>;
+    };
+    useInfinite: (params?: VSQueryParams) => _tanstack_react_query.UseInfiniteQueryResult<InfiniteData<VSListResult<Base<S>>, unknown>, Error>;
+};
+
+type EventParams<TEvents, K extends keyof TEvents> = TEvents[K] extends (...args: infer P) => void ? P : never;
+type LastIsCallback<P extends readonly unknown[]> = P extends [...infer _Rest, infer Last] ? Last extends (...args: any[]) => void ? true : false : false;
+type NoAckArgs<TEvents, K extends keyof TEvents> = EventParams<TEvents, K> extends [...infer Rest, infer Last] ? Last extends (...args: any[]) => void ? Rest : EventParams<TEvents, K> : EventParams<TEvents, K>;
+type AckEventKeys<TEvents> = {
+    [K in keyof TEvents]: LastIsCallback<TEvents[K] extends (...args: infer P) => void ? P : never> extends true ? K : never;
+}[keyof TEvents];
+type AckResponseType<TEvents, K extends keyof TEvents> = EventParams<TEvents, K> extends [...infer _Rest, infer Last] ? Last extends (arg: infer R, ...rest: any[]) => void ? R : never : never;
+interface VSSocketConnectionReturn {
+    /** True when the socket has an active, confirmed connection. */
+    isConnected: boolean;
+    /**
+     * True while a connection or reconnection attempt is in progress.
+     * Resets to false when `connect` or `connect_error` fires.
+     */
+    isConnecting: boolean;
+    /** The socket ID assigned by the server. Undefined when disconnected. */
+    socketId: string | undefined;
+    /** The error from the last failed connection attempt. Null on success or before any attempt. */
+    error: Error | null;
+    /**
+     * Initiates a connection. No-op if already connected.
+     * Sets `isConnecting: true` until `connect` or `connect_error` fires.
+     */
+    connect: () => void;
+    /** Gracefully closes the connection and stops all reconnection attempts. */
+    disconnect: () => void;
+}
+/**
+ * Creates three type-safe Socket.IO hooks bound to a specific socket instance.
+ *
+ * Call once at module level — the returned hooks close over the socket and both
+ * event-map generics, so no type parameters are needed at individual call sites.
+ *
+ * Requires socket.io-client ≥4.6.0 (for native `socket.emitWithAck` support).
+ *
+ * @example
+ * // socket-hooks.ts  (create once, export and use everywhere)
+ * import { createSocketHooks } from '@void-snippets/react';
+ * import { io } from 'socket.io-client';
+ *
+ * const socket = io(process.env.SOCKET_URL, { autoConnect: false });
+ *
+ * export const { useSocketEmit, useSocketListener, useSocketConnection } =
+ *   createSocketHooks<IClientToServerEvents, IServerToClientEvents>(socket);
+ */
+declare function createSocketHooks<TClientEvents extends Record<string, (...args: any[]) => void>, TServerEvents extends Record<string, (...args: any[]) => void>>(socket: Socket<TServerEvents, TClientEvents>): {
+    useSocketEmit: () => {
+        emit: <K extends keyof TClientEvents>(event: K, ...args: NoAckArgs<TClientEvents, K>) => void;
+        emitWithAck: <K extends AckEventKeys<TClientEvents>>(event: K, ...args: NoAckArgs<TClientEvents, K>) => Promise<AckResponseType<TClientEvents, K>>;
     };
-    useInfinite: (params?: TQueryParams) => _tanstack_react_query.UseInfiniteQueryResult<_tanstack_react_query.InfiniteData<ResourceListResult<Base<S>>, unknown>, Error>;
+    useSocketListener: <K extends keyof TServerEvents>(event: K, handler: TServerEvents[K], options?: {
+        enabled?: boolean;
+    }) => void;
+    useSocketConnection: () => VSSocketConnectionReturn;
+};
+
+/**
+ * Recursively extracts named path parameters from a route path string using
+ * TypeScript template literal inference. Handles both required and optional
+ * segments, and composes correctly across nested slashes.
+ *
+ *   '/users/:userId/posts/:postId' → { userId: string | number; postId: string | number }
+ *   '/files/:path?'               → { path?: string | number }
+ */
+type ExtractRouteParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? (Param extends `${infer P}?` ? {
+    [K in P]?: string | number;
+} : {
+    [K in Param]: string | number;
+}) & ExtractRouteParams<`/${Rest}`> : T extends `${infer _Start}:${infer Param}` ? Param extends `${infer P}?` ? {
+    [K in P]?: string | number;
+} : {
+    [K in Param]: string | number;
+} : {};
+/** Collapses intersection types into a single object for cleaner IDE tooltips. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** All named path parameters for a given route path literal. */
+type RouteParams<Path extends string> = Prettify<ExtractRouteParams<Path>>;
+/** True when the path string contains at least one named parameter. */
+type HasParams<Path extends string> = keyof RouteParams<Path> extends never ? false : true;
+/**
+ * True when Search is the `never` type — meaning no search params were
+ * declared on this route. Array wrapping avoids distributive evaluation.
+ */
+type SearchIsAbsent<Search> = [Search] extends [never] ? true : false;
+/**
+ * True when Search has at least one required (non-optional) key.
+ *   { page: number; sort?: string } → true  (page is required)
+ *   { sort?: string }               → false (all optional)
+ *   never                           → false
+ */
+type HasRequiredSearchKeys<Search> = [
+    Search
+] extends [never] ? false : {} extends Search ? false : true;
+/** Params portion of the build() argument. Empty object when path has no params. */
+type ParamsPart<Path extends string> = HasParams<Path> extends true ? {
+    params: RouteParams<Path>;
+} : {};
+/**
+ * Search portion of the build() argument.
+ * Absent when Search is never.
+ * Required when Search has at least one required key.
+ * Optional when all Search keys are optional.
+ */
+type SearchPart<Search> = SearchIsAbsent<Search> extends true ? {} : HasRequiredSearchKeys<Search> extends true ? {
+    search: Search;
+} : {
+    search?: Search;
+};
+/** Full combined build() options, flattened for IDE readability. */
+type BuildArgs<Path extends string, Search> = Prettify<ParamsPart<Path> & SearchPart<Search>>;
+/**
+ * True when build() can be called with zero arguments:
+ * no path params AND (no search OR all search keys are optional).
+ */
+type ArgIsOptional<Path extends string, Search> = HasParams<Path> extends true ? false : SearchIsAbsent<Search> extends true ? true : HasRequiredSearchKeys<Search> extends true ? false : true;
+/**
+ * True when BuildArgs produces an empty object — meaning build()
+ * takes no arguments whatsoever (no params, no search).
+ */
+type BuildArgIsEmpty<Path extends string, Search> = HasParams<Path> extends false ? SearchIsAbsent<Search> extends true ? true : false : false;
+/**
+ * The fully conditioned build() function signature.
+ *
+ * Four cases:
+ *   no params + no search            → () => string
+ *   no params + all-optional search  → (options?: { search?: S }) => string
+ *   params (+ optional search)       → (options: { params: P; search?: S }) => string
+ *   required search key              → (options: { search: S }) => string
+ */
+type BuildFn<Path extends string, Search> = BuildArgIsEmpty<Path, Search> extends true ? () => string : ArgIsOptional<Path, Search> extends true ? (options?: BuildArgs<Path, Search>) => string : (options: BuildArgs<Path, Search>) => string;
+/** Optional metadata that can be attached to any route definition. */
+interface RouteMetadata {
+    /**
+     * Permission identifiers required to access this route.
+     * Read via the `handle` property in your React Router config.
+     *
+     * @example
+     * permissions: ['ADMIN', 'SUPER_ADMIN']
+     */
+    permissions?: string[];
+    /**
+     * Human-readable label used for breadcrumb navigation.
+     * Read via the `handle` property in your React Router config.
+     */
+    breadcrumb?: string;
+    /**
+     * Document title for the page.
+     * Read via the `handle` property in your React Router config.
+     */
+    title?: string;
+    /**
+     * Arbitrary custom metadata — analytics tags, loader IDs, feature flags, etc.
+     * Read via the `handle` property in your React Router config.
+     *
+     * @example
+     * meta: { analyticsId: 'user-detail-view', loaderKey: 'userLoader' }
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * The intermediate type returned by `defineRoute()`.
+ * Consumed directly by `createRouteContract()` — you do not use this type
+ * directly in application code.
+ *
+ * @internal
+ */
+type RouteDefinition<Path extends string = string, Search = never> = RouteMetadata & {
+    /** The absolute path string for this route. */
+    readonly path: Path;
+    /**
+     * Phantom type anchor — carries the Search type for downstream inference.
+     * Always `undefined` at runtime. Do not read or write this directly.
+     * @internal
+     */
+    readonly _search: Search;
+    /**
+     * Declares typed search parameters for this route. Chain immediately after
+     * `defineRoute()`. The generic type argument is the only input — no value
+     * needs to be passed.
+     *
+     * @example
+     * defineRoute('/users').search<{ page: number; sort?: 'asc' | 'desc' }>()
+     */
+    search<S>(): RouteDefinition<Path, S>;
+};
+/**
+ * A fully processed route node produced by `createRouteContract()`.
+ * This is the type you interact with throughout the application.
+ */
+type ProcessedRoute<Path extends string = string, Search = never> = RouteMetadata & {
+    /** The absolute path string — use this in `createBrowserRouter`. */
+    readonly path: Path;
+    /**
+     * Phantom type anchor — used by `useTypedSearchParams` to infer `Search`.
+     * Always `undefined` at runtime. Do not read or write this directly.
+     * @internal
+     */
+    readonly _search: Search;
+    /**
+     * Builds a fully qualified URL for this route.
+     *
+     * TypeScript enforces at compile time that:
+     * - `params` is provided and fully satisfied when the path has dynamic segments.
+     * - `search` matches the exact shape declared via `.search<T>()`.
+     * - No argument is needed for routes with neither params nor required search.
+     */
+    readonly build: BuildFn<Path, Search>;
+};
+/** The input shape `createRouteContract` accepts. */
+type RouteTree = {
+    [K: string]: RouteDefinition<string, any> | RouteTree;
+};
+/** Maps a RouteTree recursively to a tree of ProcessedRoutes. */
+type ProcessedTree<T> = {
+    [K in keyof T]: T[K] extends RouteDefinition<infer Path, infer Search> ? ProcessedRoute<Path, Search> : T[K] extends RouteTree ? ProcessedTree<T[K]> : never;
+};
+/**
+ * Defines a single route. Pass directly to `createRouteContract()`.
+ *
+ * The second argument is purely metadata — permissions, breadcrumbs, titles.
+ * Chain `.search<SearchType>()` to declare typed search parameters for the route.
+ *
+ * **Use absolute paths.** Concatenating parent/child paths via template literals
+ * causes TypeScript server slowdowns on large apps. Be explicit.
+ *
+ * @example
+ * // Plain route — no params, no search
+ * defineRoute('/dashboard', { breadcrumb: 'Home', title: 'Dashboard' })
+ *
+ * // Route with typed search params
+ * defineRoute('/users', { permissions: ['ADMIN'] })
+ *   .search<{ page: number; sort?: 'asc' | 'desc' }>()
+ *
+ * // Route with path params and optional search
+ * defineRoute('/users/:userId', { breadcrumb: 'User Detail' })
+ *   .search<{ tab?: 'profile' | 'settings' }>()
+ *
+ * // Route with path params, no search
+ * defineRoute('/users/:userId/posts/:postId')
+ */
+declare function defineRoute<Path extends string>(path: Path, config?: RouteMetadata): RouteDefinition<Path, never>;
+/**
+ * Processes a tree of `defineRoute()` definitions into a fully typed contract.
+ *
+ * Every route leaf gains a `build()` function whose signature is automatically
+ * conditioned on the presence of path params and search params. Nested groups
+ * are preserved as plain objects. All metadata (`path`, `permissions`,
+ * `breadcrumb`, `title`, `meta`) flows through to the output unchanged.
+ *
+ * Call once at module level and export. Import `AppRoutes` wherever you need
+ * to build a URL, wire up the router, or access route metadata.
+ *
+ * @example
+ * // routes.ts
+ * export const AppRoutes = createRouteContract({
+ *   auth: {
+ *     login:    defineRoute('/auth/login').search<{ redirect?: string }>(),
+ *     register: defineRoute('/auth/register'),
+ *   },
+ *   dashboard: {
+ *     root: defineRoute('/dashboard', { breadcrumb: 'Home', title: 'Dashboard' }),
+ *     users: {
+ *       list: defineRoute('/dashboard/users', {
+ *         permissions: ['ADMIN'],
+ *         breadcrumb:  'Users',
+ *       }).search<{ page: number; sort?: 'asc' | 'desc' }>(),
+ *       detail: defineRoute('/dashboard/users/:userId', {
+ *         permissions: ['ADMIN'],
+ *         breadcrumb:  'User Detail',
+ *       }).search<{ tab?: 'profile' | 'settings' }>(),
+ *     },
+ *   },
+ * });
+ */
+declare function createRouteContract<T extends RouteTree>(tree: T): ProcessedTree<T>;
+/**
+ * Returns the current URL search params typed to the shape declared on the
+ * route, plus a type-safe setter and a clear function.
+ *
+ * Pass any processed route that was created with `.search<T>()`. TypeScript
+ * infers `T` automatically — no generics needed at the call site.
+ *
+ * **`setSearch` merges** — it does not replace the entire query string.
+ * Pass only the keys you want to change; everything else is preserved.
+ * Set a key to `undefined` or `null` to remove it from the URL.
+ *
+ * ⚠️  **Runtime coercion note:** React Router's `useSearchParams` returns all
+ * values as strings. If you declare `page: number`, `search.page` will be
+ * the string `"1"` at runtime even though TypeScript types it as `number`.
+ * Coerce where needed: `Number(search.page)`. This is a deliberate trade-off
+ * that avoids requiring a runtime schema library.
+ *
+ * @example
+ * // Inside the /dashboard/users page component
+ * const { search, setSearch, clearSearch } =
+ *   useTypedSearchParams(AppRoutes.dashboard.users.list);
+ *
+ * // search.page is typed as `number | undefined`
+ * // but is a string at runtime — coerce explicitly:
+ * const page = Number(search.page ?? 1);
+ *
+ * setSearch({ page: 2 })              // keeps sort, q; updates page
+ * setSearch({ page: 1, sort: 'asc' }) // updates page and sort; keeps q
+ * setSearch({ sort: undefined })      // removes sort from the URL
+ * clearSearch()                        // wipes all search params
+ */
+declare function useTypedSearchParams<P extends string, S>(_route: ProcessedRoute<P, S>): {
+    /** Current search params, typed as a partial of the declared search shape. */
+    readonly search: Readonly<Partial<S>>;
+    /**
+     * Merges the given partial update into the current search params and
+     * pushes a new URL entry. Set a key to `undefined` to remove it.
+     */
+    setSearch: (update: Partial<S>) => void;
+    /** Removes all search parameters from the URL. */
+    clearSearch: () => void;
+};
+
+type VSAlertVariant = "success" | "info" | "error";
+interface VSAlertState {
+    message: ReactNode | string;
+    type: VSAlertVariant;
+    isVisible: boolean;
+}
+/**
+ * Manages alert/toast message state with optional auto-hide.
+ *
+ * @param autoHideDuration - ms before alert hides automatically. Pass 0 to disable. Default: 3000
+ *
+ * @example
+ * const { alert, showAlert, hideAlert } = useAlertMessage();
+ * showAlert('Saved successfully!', 'success');
+ * showAlert(<b>Something went wrong</b>, 'error');
+ */
+declare function useAlertMessage(autoHideDuration?: number): {
+    alert: VSAlertState;
+    showAlert: (message: ReactNode | string, type?: VSAlertVariant) => void;
+    hideAlert: () => void;
 };
 
-export { type CreateResourceHooksOptions, type UseListReturn, createResourceHooks };
+type VSAsyncStatus = "idle" | "pending" | "success" | "error";
+interface VSAsyncState<T> {
+    data: T | null;
+    status: VSAsyncStatus;
+    error: Error | null;
+}
+interface VSUseAsyncStateReturn<T> extends VSAsyncState<T> {
+    isLoading: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    setData: (data: T | null) => void;
+    setError: (error: Error | null) => void;
+    reset: () => void;
+    /**
+     * Executes an async function, updates state, and returns a [err, data] tuple.
+     * Allows immediate result handling without try/catch.
+     *
+     * @example
+     * const [err, data] = await execute(() => ContactsApis.create(payload));
+     * if (err) return showAlert(err.message, 'error');
+     * showAlert('Created!', 'success');
+     */
+    execute: (asyncFn: () => Promise<T>, options?: {
+        onSuccess?: (data: T) => void;
+        onError?: (error: Error) => void;
+    }) => Promise<[Error, null] | [null, T]>;
+}
+/**
+ * Generic async state machine — tracks data, status, and error for any async operation.
+ * Pair with any async function: API calls, file reads, timers, etc.
+ *
+ * @param initialData - Optional initial data value. Default: null
+ *
+ * @example
+ * const { data, isLoading, isError, execute } = useAsyncState<User>();
+ *
+ * const handleSubmit = async () => {
+ *   const [err, user] = await execute(() => fetchUser(id));
+ *   if (err) return;
+ *   console.log(user.name);
+ * };
+ */
+declare function useAsyncState<T>(initialData?: T | null): VSUseAsyncStateReturn<T>;
+
+/**
+ * Tracks elapsed time from a given start timestamp — useful for call durations,
+ * countdowns, or any elapsed-time display.
+ *
+ * @param startedAt - Unix timestamp in ms (e.g. Date.now()). Pass null/undefined to reset.
+ * @returns Formatted duration string "MM:SS"
+ *
+ * @example
+ * const duration = useCallTimer(call.startedAt);
+ * // duration → "02:45"
+ *
+ * // Reset when no active call
+ * const duration = useCallTimer(activeCall ? activeCall.startedAt : null);
+ */
+declare function useCallTimer(startedAt?: number | null): string;
+
+interface VSModalReturn<T> {
+    isOpen: boolean;
+    data: T | null;
+    isLoading: boolean;
+    openCreateModal: () => void;
+    openEditModal: (editData: T) => void;
+    setLoading: (loading: boolean) => void;
+    closeModal: () => void;
+    setModal: (open: boolean, editData?: T | null) => void;
+}
+/**
+ * Manages modal open/close state with optional data payload and loading state.
+ * Works for both create and edit modals — pass data to distinguish the mode.
+ *
+ * @typeParam T - The type of data the modal operates on (e.g. a Contact, User, etc.)
+ *
+ * @example
+ * const modal = useModal<Contact.Base>();
+ *
+ * modal.openCreateModal();      // data → null (create mode)
+ * modal.openEditModal(contact); // data → contact (edit mode)
+ *
+ * if (modal.data) {
+ *   // Edit mode — modal.data is Contact.Base
+ * } else {
+ *   // Create mode
+ * }
+ */
+declare function useModal<T = unknown>(): VSModalReturn<T>;
+
+interface VSPaginationReturn {
+    page: number;
+    limit: number;
+    onPaginationChange: (newPage: number, newLimit: number) => void;
+    resetPagination: () => void;
+    setPage: (page: number) => void;
+    setLimit: (limit: number) => void;
+    /** Ready-to-use query params object — pass directly to useList() */
+    queryParams: VSQueryParams;
+}
+/**
+ * Manages pagination state and produces a ready-to-use queryParams object
+ * compatible with createResourceHooks' useList() and useInfinite().
+ *
+ * @param initialPage  - Starting page. Default: 1
+ * @param initialLimit - Items per page. Default: 10
+ *
+ * @example
+ * const { queryParams, onPaginationChange } = usePagination(1, 20);
+ *
+ * const { list, isLoading } = contactHooks.useList(queryParams);
+ *
+ * <Pagination onChange={onPaginationChange} total={pagination.totalDocuments} />
+ */
+declare function usePagination(initialPage?: number, initialLimit?: number): VSPaginationReturn;
+
+export { type ProcessedRoute, type RouteDefinition, type RouteMetadata, type VSAlertState, type VSAlertVariant, type VSAsyncStatus, type VSModalReturn, type VSOptimisticHandlers, type VSOptimisticOperation, type VSPaginationReturn, type VSResourceHooksOptions, type VSSocketConnectionReturn, type VSUseAsyncStateReturn, type VSUseGetReturn, type VSUseListReturn, createResourceHooks, createRouteContract, createSocketHooks, defineRoute, useAlertMessage, useAsyncState, useCallTimer, useModal, usePagination, useTypedSearchParams };