@spoosh/core 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,1318 @@
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type SchemaMethod = "$get" | "$post" | "$put" | "$patch" | "$delete";
+
+type MiddlewarePhase = "before" | "after";
+type MiddlewareContext<TData = unknown, TError = unknown> = {
+    baseUrl: string;
+    path: string[];
+    method: HttpMethod;
+    defaultOptions: SpooshOptions & SpooshOptionsExtra;
+    requestOptions?: AnyRequestOptions;
+    fetchInit?: RequestInit;
+    response?: SpooshResponse<TData, TError>;
+    metadata: Record<string, unknown>;
+};
+type MiddlewareHandler<TData = unknown, TError = unknown> = (context: MiddlewareContext<TData, TError>) => MiddlewareContext<TData, TError> | Promise<MiddlewareContext<TData, TError>>;
+type SpooshMiddleware<TData = unknown, TError = unknown> = {
+    name: string;
+    phase: MiddlewarePhase;
+    handler: MiddlewareHandler<TData, TError>;
+};
+
+type QueryField<TQuery> = [TQuery] extends [never] ? object : {
+    query: TQuery;
+};
+type BodyField<TBody> = [TBody] extends [never] ? object : {
+    body: TBody;
+};
+type FormDataField<TFormData> = [TFormData] extends [never] ? object : {
+    formData: TFormData;
+};
+type UrlEncodedField<TUrlEncoded> = [TUrlEncoded] extends [never] ? object : {
+    urlEncoded: TUrlEncoded;
+};
+type ParamsField<TParamNames extends string> = [TParamNames] extends [never] ? object : {
+    params: Record<TParamNames, string | number>;
+};
+type InputFields<TQuery, TBody, TFormData, TUrlEncoded, TParamNames extends string> = QueryField<TQuery> & BodyField<TBody> & FormDataField<TFormData> & UrlEncodedField<TUrlEncoded> & ParamsField<TParamNames>;
+type InputFieldWrapper<TQuery, TBody, TFormData, TUrlEncoded, TParamNames extends string> = [TQuery, TBody, TFormData, TUrlEncoded, TParamNames] extends [
+    never,
+    never,
+    never,
+    never,
+    never
+] ? object : {
+    input: InputFields<TQuery, TBody, TFormData, TUrlEncoded, TParamNames>;
+};
+type SpooshResponse<TData, TError, TRequestOptions = unknown, TQuery = never, TBody = never, TFormData = never, TUrlEncoded = never, TParamNames extends string = never> = ({
+    status: number;
+    data: TData;
+    headers?: Headers;
+    error?: undefined;
+    aborted?: false;
+    readonly __requestOptions?: TRequestOptions;
+} & InputFieldWrapper<TQuery, TBody, TFormData, TUrlEncoded, TParamNames>) | ({
+    status: number;
+    data?: undefined;
+    headers?: Headers;
+    error: TError;
+    aborted?: boolean;
+    readonly __requestOptions?: TRequestOptions;
+} & InputFieldWrapper<TQuery, TBody, TFormData, TUrlEncoded, TParamNames>);
+type SpooshOptionsExtra<TData = unknown, TError = unknown> = {
+    middlewares?: SpooshMiddleware<TData, TError>[];
+};
+
+type RetryConfig = {
+    retries?: number | false;
+    retryDelay?: number;
+};
+type HeadersInitOrGetter = HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+type SpooshOptions = Omit<RequestInit, "method" | "body" | "headers"> & {
+    headers?: HeadersInitOrGetter;
+};
+type BaseRequestOptions = {
+    headers?: HeadersInitOrGetter;
+    cache?: RequestCache;
+    signal?: AbortSignal;
+};
+type BodyOption<TBody> = [TBody] extends [never] ? object : {
+    body: TBody;
+};
+type QueryOption<TQuery> = [TQuery] extends [never] ? object : {
+    query: TQuery;
+};
+type FormDataOption<TFormData> = [TFormData] extends [never] ? object : {
+    formData: TFormData;
+};
+type UrlEncodedOption<TUrlEncoded> = [TUrlEncoded] extends [never] ? object : {
+    urlEncoded: TUrlEncoded;
+};
+type RequestOptions<TBody = never, TQuery = never, TFormData = never, TUrlEncoded = never> = BaseRequestOptions & BodyOption<TBody> & QueryOption<TQuery> & FormDataOption<TFormData> & UrlEncodedOption<TUrlEncoded>;
+type AnyRequestOptions = BaseRequestOptions & {
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    formData?: Record<string, unknown>;
+    urlEncoded?: Record<string, unknown>;
+    params?: Record<string, string | number>;
+    signal?: AbortSignal;
+} & Partial<RetryConfig>;
+type DynamicParamsOption = {
+    params?: Record<string, string | number>;
+};
+type CoreRequestOptionsBase = {
+    __hasDynamicParams?: DynamicParamsOption;
+};
+type MethodOptionsMap<TQueryOptions = object, TMutationOptions = object> = {
+    $get: TQueryOptions;
+    $post: TMutationOptions;
+    $put: TMutationOptions;
+    $patch: TMutationOptions;
+    $delete: TMutationOptions;
+};
+type ExtractMethodOptions<TOptionsMap, TMethod extends SchemaMethod> = TOptionsMap extends MethodOptionsMap<infer TQuery, infer TMutation> ? TMethod extends "$get" ? TQuery : TMutation : TOptionsMap;
+type FetchExecutor<TOptions = SpooshOptions, TRequestOptions = AnyRequestOptions> = <TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: TOptions, requestOptions?: TRequestOptions, nextTags?: boolean) => Promise<SpooshResponse<TData, TError>>;
+type TypedParamsOption<TParamNames extends string> = [TParamNames] extends [
+    never
+] ? object : {
+    params?: Record<TParamNames, string | number>;
+};
+type ComputeRequestOptions<TRequestOptionsBase, TParamNames extends string> = "__hasDynamicParams" extends keyof TRequestOptionsBase ? [TParamNames] extends [never] ? Omit<TRequestOptionsBase, "__hasDynamicParams"> : Omit<TRequestOptionsBase, "__hasDynamicParams"> & TypedParamsOption<TParamNames> : TRequestOptionsBase & TypedParamsOption<TParamNames>;
+
+type EventCallback<T = unknown> = (payload: T) => void;
+/**
+ * Built-in event map. Maps event names to their payload types.
+ *
+ * Third-party plugins can extend this via declaration merging:
+ * @example
+ * ```ts
+ * declare module '@spoosh/core' {
+ *   interface BuiltInEvents {
+ *     "my-custom-event": MyPayloadType;
+ *   }
+ * }
+ * ```
+ */
+interface BuiltInEvents {
+    refetch: RefetchEvent;
+    invalidate: string[];
+}
+/**
+ * Resolves event payload type. Built-in events get their specific type,
+ * custom events get `unknown` (or explicit type parameter).
+ */
+type EventPayload<E extends string> = E extends keyof BuiltInEvents ? BuiltInEvents[E] : unknown;
+type EventEmitter = {
+    /**
+     * Subscribe to an event. Built-in events have type-safe payloads.
+     *
+     * @example
+     * ```ts
+     * // Built-in event - payload is typed as RefetchEvent
+     * eventEmitter.on("refetch", (event) => {
+     *   console.log(event.queryKey, event.reason);
+     * });
+     *
+     * // Custom event - specify type explicitly
+     * eventEmitter.on<MyPayload>("my-event", (payload) => { ... });
+     * ```
+     */
+    on<E extends string>(event: E, callback: EventCallback<EventPayload<E>>): () => void;
+    /**
+     * Emit an event. Built-in events have type-safe payloads.
+     *
+     * @example
+     * ```ts
+     * // Built-in event - payload is type-checked
+     * eventEmitter.emit("refetch", { queryKey: "...", reason: "focus" });
+     *
+     * // Custom event
+     * eventEmitter.emit("my-event", myPayload);
+     * ```
+     */
+    emit<E extends string>(event: E, payload: EventPayload<E>): void;
+    off: (event: string, callback: EventCallback) => void;
+    clear: () => void;
+};
+declare function createEventEmitter(): EventEmitter;
+
+type OperationType = "read" | "write" | "infiniteRead";
+type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
+type OperationState<TData = unknown, TError = unknown> = {
+    data: TData | undefined;
+    error: TError | undefined;
+    timestamp: number;
+};
+type CacheEntry<TData = unknown, TError = unknown> = {
+    state: OperationState<TData, TError>;
+    tags: string[];
+    /** Plugin-contributed result data (e.g., isOptimistic, isStale). Merged into hook result. */
+    pluginResult: Map<string, unknown>;
+    /** The original path-derived tag (e.g., "posts/1/comments"). Used for exact matching in cache */
+    selfTag?: string;
+    previousData?: TData;
+    /** Cache was invalidated while no subscriber was listening. Triggers refetch on next mount. */
+    stale?: boolean;
+};
+type PluginContext<TData = unknown, TError = unknown> = {
+    readonly operationType: OperationType;
+    readonly path: string[];
+    readonly method: HttpMethod;
+    readonly queryKey: string;
+    readonly tags: string[];
+    /** Timestamp when this request was initiated. Useful for tracing and debugging. */
+    readonly requestTimestamp: number;
+    /** Unique identifier for the hook instance. Persists across queryKey changes within the same hook. */
+    readonly hookId?: string;
+    requestOptions: AnyRequestOptions;
+    state: OperationState<TData, TError>;
+    response?: SpooshResponse<TData, TError>;
+    metadata: Map<string, unknown>;
+    abort: () => void;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    /** Resolved headers as a plain object. Modify via setHeaders(). */
+    headers: Record<string, string>;
+    /** Add/update headers. Merges with existing headers. */
+    setHeaders: (headers: Record<string, string>) => void;
+    /** Access other plugins' exported APIs */
+    plugins: PluginAccessor;
+    /** Plugin-specific options passed from hooks (useRead/useWrite/useInfiniteRead) */
+    pluginOptions?: unknown;
+    /** Force a network request even if cached data exists. Used by plugins to communicate intent. */
+    forceRefetch?: boolean;
+};
+/** Input type for creating PluginContext (without injected properties) */
+type PluginContextInput<TData = unknown, TError = unknown> = Omit<PluginContext<TData, TError>, "plugins" | "setHeaders" | "headers">;
+/**
+ * Middleware function that wraps the fetch flow.
+ * Plugins use this for full control over request/response handling.
+ *
+ * @param context - The plugin context with request info and utilities
+ * @param next - Call this to continue to the next middleware or actual fetch
+ * @returns The response (either from next() or early return)
+ *
+ * @example
+ * ```ts
+ * // Cache middleware - return cached data or continue
+ * middleware: async (context, next) => {
+ *   const cached = context.stateManager.getCache(context.queryKey);
+ *   if (cached?.state?.data && !isStale(cached)) {
+ *     return { data: cached.state.data, status: 200 };
+ *   }
+ *   return next();
+ * }
+ *
+ * // Retry middleware - wrap and retry on error
+ * middleware: async (context, next) => {
+ *   for (let i = 0; i < 3; i++) {
+ *     const result = await next();
+ *     if (!result.error) return result;
+ *   }
+ *   return next();
+ * }
+ * ```
+ */
+type PluginMiddleware<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, next: () => Promise<SpooshResponse<TData, TError>>) => Promise<SpooshResponse<TData, TError>>;
+type PluginHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>) => void | Promise<void>;
+type PluginUpdateHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => void | Promise<void>;
+/**
+ * Handler called after every response, regardless of early returns from middleware.
+ * Use this for post-response logic like scheduling polls or emitting events.
+ */
+type PluginResponseHandler<TData = unknown, TError = unknown> = (context: PluginContext<TData, TError>, response: SpooshResponse<TData, TError>) => void | Promise<void>;
+type PluginLifecycle<TData = unknown, TError = unknown> = {
+    /** Called on component mount */
+    onMount?: PluginHandler<TData, TError>;
+    /** Called when options/query changes. Receives both new and previous context. */
+    onUpdate?: PluginUpdateHandler<TData, TError>;
+    /** Called on component unmount */
+    onUnmount?: PluginHandler<TData, TError>;
+};
+/**
+ * Configuration object for plugin type definitions.
+ * Use this to specify which options and results your plugin provides.
+ *
+ * @example
+ * ```ts
+ * // Plugin with read options only
+ * SpooshPlugin<{ readOptions: MyReadOptions }>
+ *
+ * // Plugin with read/write options and results
+ * SpooshPlugin<{
+ *   readOptions: MyReadOptions;
+ *   writeOptions: MyWriteOptions;
+ *   readResult: MyReadResult;
+ * }>
+ *
+ * // Plugin with instance-level API
+ * SpooshPlugin<{
+ *   instanceApi: { prefetch: (selector: Selector) => Promise<void> };
+ * }>
+ * ```
+ */
+type PluginTypeConfig = {
+    readOptions?: object;
+    writeOptions?: object;
+    infiniteReadOptions?: object;
+    readResult?: object;
+    writeResult?: object;
+    instanceApi?: object;
+};
+/**
+ * Base interface for Spoosh plugins.
+ *
+ * Plugins can implement:
+ * - `middleware`: Wraps the fetch flow for full control (intercept, retry, transform)
+ * - `onResponse`: Called after every response, regardless of early returns
+ * - `lifecycle`: Component lifecycle hooks (onMount, onUpdate, onUnmount)
+ * - `exports`: Functions/variables accessible to other plugins
+ *
+ * @typeParam T - Plugin type configuration object. Specify only the types your plugin needs.
+ *
+ * @example
+ * ```ts
+ * function myPlugin(): SpooshPlugin<{
+ *   readOptions: { cacheTime: number };
+ *   readResult: { isFromCache: boolean };
+ * }> {
+ *   return {
+ *     name: "my-plugin",
+ *     operations: ["read"],
+ *     middleware: async (context, next) => {
+ *       // Full control over fetch flow
+ *       const result = await next();
+ *       return result;
+ *     },
+ *     onResponse(context, response) {
+ *       // Always runs after response
+ *     },
+ *     lifecycle: {
+ *       onMount(context) { },
+ *       onUpdate(context, previousContext) { },
+ *       onUnmount(context) { },
+ *     },
+ *   };
+ * }
+ * ```
+ */
+interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
+    name: string;
+    operations: OperationType[];
+    /** Middleware for controlling the fetch flow. Called in plugin order, composing a chain. */
+    middleware?: PluginMiddleware;
+    /** Called after every response, regardless of early returns from middleware. */
+    onResponse?: PluginResponseHandler;
+    /** Component lifecycle hooks (setup, cleanup, option changes) */
+    lifecycle?: PluginLifecycle;
+    /** Expose functions/variables for other plugins to access via `context.plugins.get(name)` */
+    exports?: (context: PluginContext) => object;
+    /**
+     * Expose functions/properties on the framework adapter return value (e.g., createReactSpoosh).
+     * Unlike `exports`, these are accessible directly from the instance, not just within plugin context.
+     *
+     * @example
+     * ```ts
+     * instanceApi: ({ api, stateManager }) => ({
+     *   prefetch: async (selector) => { ... },
+     *   invalidateAll: () => { ... },
+     * })
+     * ```
+     */
+    instanceApi?: (context: InstanceApiContext) => T extends {
+        instanceApi: infer A;
+    } ? A : object;
+    /** Declare plugin dependencies. These plugins must be registered before this one. */
+    dependencies?: string[];
+    /** @internal Type carrier for inference - do not use directly */
+    readonly _types?: T;
+}
+/**
+ * Helper type for creating plugin factory functions.
+ *
+ * @typeParam TConfig - Configuration object type (use `void` for no config)
+ * @typeParam TTypes - Plugin type configuration object
+ *
+ * @example
+ * ```ts
+ * // Factory with no config
+ * const myPlugin: PluginFactory<void, { readOptions: MyOpts }> = () => ({ ... });
+ *
+ * // Factory with config
+ * const myPlugin: PluginFactory<MyConfig, { readOptions: MyOpts }> = (config) => ({ ... });
+ * ```
+ */
+type PluginFactory<TConfig = void, TTypes extends PluginTypeConfig = PluginTypeConfig> = TConfig extends void ? () => SpooshPlugin<TTypes> : (config?: TConfig) => SpooshPlugin<TTypes>;
+/**
+ * Marker type for callbacks that need TData/TError from useRead/useWrite.
+ * Third-party plugins should use this for data-aware callback options.
+ *
+ * @example
+ * ```ts
+ * interface MyPluginReadOptions {
+ *   onDataChange?: DataAwareCallback<boolean>;  // (data, error) => boolean
+ *   transform?: DataAwareTransform;             // (data, error) => data
+ * }
+ * ```
+ */
+type DataAwareCallback<TReturn = void, TData = unknown, TError = unknown> = (data: TData | undefined, error: TError | undefined) => TReturn;
+/**
+ * Marker type for transform functions that receive and return TData.
+ */
+type DataAwareTransform<TData = unknown, TError = unknown> = (data: TData | undefined, error: TError | undefined) => TData | undefined;
+/**
+ * Context object containing all type information available for resolution.
+ * 3rd party plugins can access any combination of these types.
+ */
+type ResolverContext<TSchema = unknown, TData = unknown, TError = unknown, TQuery = unknown, TBody = unknown, TParams = unknown, TFormData = unknown, TUrlEncoded = unknown> = {
+    schema: TSchema;
+    data: TData;
+    error: TError;
+    input: {
+        query: TQuery;
+        body: TBody;
+        params: TParams;
+        formData: TFormData;
+        urlEncoded: TUrlEncoded;
+    };
+};
+/**
+ * Unified resolver registry for plugin type resolution.
+ *
+ * 3rd party plugins can extend this interface via TypeScript declaration
+ * merging to register their own type-aware options:
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types file:
+ * declare module '@spoosh/core' {
+ *   interface PluginResolvers<TContext> {
+ *     // Access schema
+ *     mySchemaCallback: MyFn<TContext['schema']> | undefined;
+ *
+ *     // Access data/error
+ *     myDataTransform: (data: TContext['data']) => TContext['data'];
+ *
+ *     // Access request input
+ *     myDebounce: (prev: { prevQuery: TContext['input']['query'] }) => number;
+ *
+ *     // Access multiple contexts at once
+ *     myComplexOption: ComplexFn<TContext['schema'], TContext['data']>;
+ *   }
+ * }
+ * ```
+ */
+interface PluginResolvers<TContext extends ResolverContext> {
+}
+/**
+ * Registry for plugin result type resolution based on options.
+ * Extend via declaration merging to provide type inference for hook results.
+ *
+ * Unlike PluginResolvers which receives the full context, this receives
+ * the OPTIONS type so plugins can infer result types from what the user passes.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types file:
+ * declare module '@spoosh/core' {
+ *   interface PluginResultResolvers<TOptions> {
+ *     transformedData: TOptions extends { transform: { response: (...args: never[]) => infer R } }
+ *       ? Awaited<R> | undefined
+ *       : never;
+ *   }
+ * }
+ * ```
+ */
+interface PluginResultResolvers<TOptions> {
+}
+/**
+ * Registry for plugin exports. Extend via declaration merging for type-safe access.
+ *
+ * Plugins can expose functions and variables that other plugins can access
+ * via `context.plugins.get("plugin-name")`.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types file:
+ * declare module '@spoosh/core' {
+ *   interface PluginExportsRegistry {
+ *     "my-plugin": { myMethod: () => void }
+ *   }
+ * }
+ * ```
+ */
+interface PluginExportsRegistry {
+}
+/**
+ * Registry for instance API type resolution. Extend via declaration merging.
+ *
+ * Plugins that expose schema-aware instance APIs should extend this interface
+ * to get proper type inference when the API is used.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types file:
+ * declare module '@spoosh/core' {
+ *   interface InstanceApiResolvers<TSchema> {
+ *     myFunction: MyFn<TSchema>;
+ *   }
+ * }
+ * ```
+ */
+interface InstanceApiResolvers<TSchema> {
+}
+/**
+ * Accessor for plugin exports with type-safe lookup.
+ */
+type PluginAccessor = {
+    /** Get a plugin's exported API by name. Returns undefined if plugin not found. */
+    get<K extends keyof PluginExportsRegistry>(name: K): PluginExportsRegistry[K] | undefined;
+    get(name: string): unknown;
+};
+/**
+ * Event emitted by plugins to request a refetch.
+ * Hooks subscribe to this event and trigger controller.execute().
+ */
+type RefetchEvent = {
+    queryKey: string;
+    reason: "focus" | "reconnect" | "polling" | "invalidate";
+};
+/**
+ * Minimal PluginExecutor interface for InstanceApiContext.
+ * Avoids circular dependency with executor.ts.
+ */
+type InstancePluginExecutor = {
+    executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, coreFetch: () => Promise<SpooshResponse<TData, TError>>) => Promise<SpooshResponse<TData, TError>>;
+    createContext: <TData, TError>(input: PluginContextInput<TData, TError>) => PluginContext<TData, TError>;
+};
+/**
+ * Context provided to plugin's instanceApi function.
+ * Used for creating framework-agnostic APIs exposed on the Spoosh instance.
+ */
+type InstanceApiContext<TApi = unknown> = {
+    api: TApi;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: InstancePluginExecutor;
+};
+
+type Subscriber = () => void;
+type CacheEntryWithKey<TData = unknown, TError = unknown> = {
+    key: string;
+    entry: CacheEntry<TData, TError>;
+};
+declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
+type StateManager = {
+    createQueryKey: (params: {
+        path: string[];
+        method: string;
+        options?: unknown;
+    }) => string;
+    getCache: <TData, TError>(key: string) => CacheEntry<TData, TError> | undefined;
+    setCache: <TData, TError>(key: string, entry: Partial<CacheEntry<TData, TError>>) => void;
+    deleteCache: (key: string) => void;
+    subscribeCache: (key: string, callback: Subscriber) => () => void;
+    getCacheByTags: <TData>(tags: string[]) => CacheEntry<TData> | undefined;
+    getCacheEntriesByTags: <TData, TError>(tags: string[]) => CacheEntryWithKey<TData, TError>[];
+    getCacheEntriesBySelfTag: <TData, TError>(selfTag: string) => CacheEntryWithKey<TData, TError>[];
+    setPluginResult: (key: string, data: Record<string, unknown>) => void;
+    /** Mark all cache entries with matching tags as stale */
+    markStale: (tags: string[]) => void;
+    /** Get all cache entries */
+    getAllCacheEntries: <TData, TError>() => CacheEntryWithKey<TData, TError>[];
+    /** Get the number of cache entries */
+    getSize: () => number;
+    /** Set a pending promise for a query key (for deduplication) */
+    setPendingPromise: (key: string, promise: Promise<unknown> | undefined) => void;
+    /** Get a pending promise for a query key */
+    getPendingPromise: (key: string) => Promise<unknown> | undefined;
+    clear: () => void;
+};
+declare function createStateManager(): StateManager;
+
+type PluginExecutor = {
+    /** Execute lifecycle hooks for onMount or onUnmount */
+    executeLifecycle: <TData, TError>(phase: "onMount" | "onUnmount", operationType: OperationType, context: PluginContext<TData, TError>) => Promise<void>;
+    /** Execute onUpdate lifecycle with previous context */
+    executeUpdateLifecycle: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, previousContext: PluginContext<TData, TError>) => Promise<void>;
+    /** Execute middleware chain with a core fetch function, then run onResponse handlers */
+    executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext<TData, TError>, coreFetch: () => Promise<SpooshResponse<TData, TError>>) => Promise<SpooshResponse<TData, TError>>;
+    getPlugins: () => readonly SpooshPlugin[];
+    /** Creates a full PluginContext with plugins accessor injected */
+    createContext: <TData, TError>(input: PluginContextInput<TData, TError>) => PluginContext<TData, TError>;
+};
+declare function createPluginExecutor(initialPlugins?: SpooshPlugin[]): PluginExecutor;
+
+declare const EndpointBrand: unique symbol;
+/**
+ * Define an API endpoint with its data, request options, and error types.
+ *
+ * @example
+ * ```typescript
+ * // Simple GET endpoint
+ * $get: Endpoint<{ data: User[] }>
+ *
+ * // GET with query parameters
+ * $get: Endpoint<{ data: User[]; query: { page: number; limit: number } }>
+ *
+ * // POST with JSON body
+ * $post: Endpoint<{ data: User; body: CreateUserBody }>
+ *
+ * // POST with form data (file upload)
+ * $post: Endpoint<{ data: UploadResult; formData: { file: File; name: string } }>
+ *
+ * // POST with URL-encoded body (Stripe-style)
+ * $post: Endpoint<{ data: Payment; urlEncoded: { amount: number; currency: string } }>
+ *
+ * // With error type
+ * $get: Endpoint<{ data: User; error: ApiError }>
+ *
+ * // Complex: query + body + error
+ * $post: Endpoint<{ data: User; body: CreateUserBody; query: { notify?: boolean }; error: ApiError }>
+ * ```
+ */
+type Endpoint<T extends {
+    data: unknown;
+    body?: unknown;
+    query?: unknown;
+    formData?: unknown;
+    urlEncoded?: unknown;
+    error?: unknown;
+}> = {
+    [EndpointBrand]: true;
+} & T;
+type NormalizeEndpoint<T, TDefaultError> = T extends {
+    [EndpointBrand]: true;
+} ? {
+    data: T extends {
+        data: infer D;
+    } ? D : never;
+    error: T extends {
+        error: infer E;
+    } ? E : TDefaultError;
+    body: T extends {
+        body: infer B;
+    } ? B : never;
+    query: T extends {
+        query: infer Q;
+    } ? Q : never;
+    formData: T extends {
+        formData: infer F;
+    } ? F : never;
+    urlEncoded: T extends {
+        urlEncoded: infer U;
+    } ? U : never;
+} : {
+    data: T;
+    error: TDefaultError;
+    body: never;
+    query: never;
+    formData: never;
+    urlEncoded: never;
+};
+type ExtractMethodDef<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = TSchema extends {
+    [K in TMethod]: infer M;
+} ? NormalizeEndpoint<M, TDefaultError> : never;
+type ExtractData<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    data: infer D;
+} ? D : never;
+type ExtractError<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    error: infer E;
+} ? E : TDefaultError;
+type ExtractBody<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    body: infer B;
+} ? B : never;
+type ExtractQuery<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    query: infer Q;
+} ? Q : never;
+type ExtractFormData<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    formData: infer F;
+} ? F : never;
+type ExtractUrlEncoded<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = ExtractMethodDef<TSchema, TMethod, TDefaultError> extends {
+    urlEncoded: infer U;
+} ? U : never;
+type HasMethod<TSchema, TMethod extends SchemaMethod> = TSchema extends {
+    [K in TMethod]: unknown;
+} ? true : false;
+type HasRequiredOptions<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown> = [ExtractBody<TSchema, TMethod, TDefaultError>] extends [never] ? [ExtractFormData<TSchema, TMethod, TDefaultError>] extends [never] ? [ExtractUrlEncoded<TSchema, TMethod, TDefaultError>] extends [never] ? false : true : true : true;
+
+type ExtractParamName$1<S extends string> = S extends `:${infer P}` ? P : never;
+type MethodRequestOptions<TSchema, TMethod extends SchemaMethod, TDefaultError, TOptionsMap, TParamNames extends string, TRequired extends boolean> = TRequired extends true ? RequestOptions<ExtractBody<TSchema, TMethod, TDefaultError>, ExtractQuery<TSchema, TMethod, TDefaultError>, ExtractFormData<TSchema, TMethod, TDefaultError>, ExtractUrlEncoded<TSchema, TMethod, TDefaultError>> & ComputeRequestOptions<ExtractMethodOptions<TOptionsMap, TMethod>, TParamNames> : RequestOptions<never, ExtractQuery<TSchema, TMethod, TDefaultError>, never, never> & ComputeRequestOptions<ExtractMethodOptions<TOptionsMap, TMethod>, TParamNames>;
+type MethodFn<TSchema, TMethod extends SchemaMethod, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = HasMethod<TSchema, TMethod> extends true ? HasRequiredOptions<TSchema, TMethod, TDefaultError> extends true ? (options: MethodRequestOptions<TSchema, TMethod, TDefaultError, TOptionsMap, TParamNames, true>) => Promise<SpooshResponse<ExtractData<TSchema, TMethod, TDefaultError>, ExtractError<TSchema, TMethod, TDefaultError>, MethodRequestOptions<TSchema, TMethod, TDefaultError, TOptionsMap, TParamNames, true>, ExtractQuery<TSchema, TMethod, TDefaultError>, ExtractBody<TSchema, TMethod, TDefaultError>, ExtractFormData<TSchema, TMethod, TDefaultError>, ExtractUrlEncoded<TSchema, TMethod, TDefaultError>, TParamNames>> : (options?: MethodRequestOptions<TSchema, TMethod, TDefaultError, TOptionsMap, TParamNames, false>) => Promise<SpooshResponse<ExtractData<TSchema, TMethod, TDefaultError>, ExtractError<TSchema, TMethod, TDefaultError>, MethodRequestOptions<TSchema, TMethod, TDefaultError, TOptionsMap, TParamNames, false>, ExtractQuery<TSchema, TMethod, TDefaultError>, ExtractBody<TSchema, TMethod, TDefaultError>, ExtractFormData<TSchema, TMethod, TDefaultError>, ExtractUrlEncoded<TSchema, TMethod, TDefaultError>, TParamNames>> : never;
+type IsSpecialKey<K> = K extends SchemaMethod | "_" ? true : false;
+type StaticPathKeys<TSchema> = {
+    [K in keyof TSchema as IsSpecialKey<K> extends true ? never : K extends string ? K : never]: TSchema[K];
+};
+type ExtractDynamicSchema<TSchema> = TSchema extends {
+    _: infer D;
+} ? D : never;
+type HttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = {
+    [K in SchemaMethod as K extends keyof TSchema ? K : never]: MethodFn<TSchema, K, TDefaultError, TOptionsMap, TParamNames>;
+};
+type DynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = ExtractDynamicSchema<TSchema> extends never ? object : {
+    [key: string]: SpooshClient<ExtractDynamicSchema<TSchema>, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+    [key: number]: SpooshClient<ExtractDynamicSchema<TSchema>, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+    /**
+     * Dynamic path segment with typed param name.
+     * Use `:paramName` format to get typed params in the response.
+     *
+     * @example
+     * ```ts
+     * // Typed params: { userId: string | number }
+     * const { data, params } = await api.users(':userId').$get({ params: { userId: 123 } })
+     * ```
+     */
+    <TKey extends string>(key: TKey): SpooshClient<ExtractDynamicSchema<TSchema>, TDefaultError, TOptionsMap, TParamNames | ExtractParamName$1<TKey>, TRootSchema>;
+};
+type DynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames extends string = never, TRootSchema = TSchema> = TSchema extends {
+    _: infer D;
+} ? {
+    /**
+     * Dynamic path segment placeholder for routes like `/posts/:id`.
+     *
+     * @example
+     * ```ts
+     * // Direct client usage
+     * const { data } = await api.posts._.$get({ params: { id: 123 } })
+     * ```
+     */
+    _: SpooshClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+} : object;
+type SpooshClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = HttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & DynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & DynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & {
+    [K in keyof StaticPathKeys<TSchema> as K extends SchemaMethod ? never : K]: SpooshClient<TSchema[K], TDefaultError, TOptionsMap, TParamNames, TRootSchema>;
+};
+
+type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
+interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
+    baseUrl: string;
+    defaultOptions?: SpooshOptions;
+    plugins?: TPlugins;
+}
+type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends PluginArray = PluginArray> = {
+    api: SpooshClient<TSchema, TDefaultError, CoreRequestOptionsBase>;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: PluginExecutor;
+    config: {
+        baseUrl: string;
+        defaultOptions: SpooshOptions;
+    };
+    _types: {
+        schema: TSchema;
+        defaultError: TDefaultError;
+        plugins: TPlugins;
+    };
+};
+
+declare function createSpoosh<TSchema = unknown, TDefaultError = unknown, const TPlugins extends PluginArray = PluginArray>(config: SpooshConfig<TPlugins>): SpooshInstance<TSchema, TDefaultError, TPlugins>;
+
+type SpooshClientConfig = {
+    baseUrl: string;
+    defaultOptions?: SpooshOptions;
+    middlewares?: SpooshMiddleware[];
+};
+/**
+ * Creates a lightweight type-safe API client for vanilla JavaScript/TypeScript usage.
+ *
+ * This is a simpler alternative to `createSpoosh` for users who don't need
+ * the full plugin system, state management, or React integration.
+ *
+ * @param config - Client configuration
+ * @returns Type-safe API client
+ *
+ * @example
+ * ```ts
+ * type ApiSchema = {
+ *   posts: {
+ *     $get: Endpoint<Post[]>;
+ *     $post: Endpoint<Post, CreatePostBody>;
+ *     _: {
+ *       $get: Endpoint<Post>;
+ *       $delete: Endpoint<void>;
+ *     };
+ *   };
+ * };
+ *
+ * type ApiError = {
+ *   message: string;
+ * }
+ *
+ * const api = createClient<ApiSchema, ApiError>({
+ *   baseUrl: "/api",
+ * });
+ *
+ * // Type-safe API calls
+ * const { data } = await api.posts.$get();
+ * const { data: post } = await api.posts[123].$get();
+ * ```
+ */
+declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshClientConfig): SpooshClient<TSchema, TDefaultError>;
+
+type QueryMethod = "$get";
+type MutationMethod = "$post" | "$put" | "$patch" | "$delete";
+type HasQueryMethods<TSchema> = TSchema extends object ? "$get" extends keyof TSchema ? true : TSchema extends {
+    _: infer D;
+} ? HasQueryMethods<D> : {
+    [K in keyof TSchema]: K extends SchemaMethod | "_" ? never : HasQueryMethods<TSchema[K]>;
+}[keyof TSchema] extends never ? false : true extends {
+    [K in keyof TSchema]: K extends SchemaMethod | "_" ? never : HasQueryMethods<TSchema[K]>;
+}[keyof TSchema] ? true : false : false;
+type HasMutationMethods<TSchema> = TSchema extends object ? MutationMethod extends never ? false : Extract<keyof TSchema, MutationMethod> extends never ? TSchema extends {
+    _: infer D;
+} ? HasMutationMethods<D> : {
+    [K in keyof TSchema]: K extends SchemaMethod | "_" ? never : HasMutationMethods<TSchema[K]>;
+}[keyof TSchema] extends never ? false : true extends {
+    [K in keyof TSchema]: K extends SchemaMethod | "_" ? never : HasMutationMethods<TSchema[K]>;
+}[keyof TSchema] ? true : false : true : false;
+type QueryHttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = {
+    [K in QueryMethod as K extends keyof TSchema ? K : never]: MethodFn<TSchema, K, TDefaultError, TOptionsMap, TParamNames>;
+};
+type ExtractParamName<S extends string> = S extends `:${infer P}` ? P : never;
+type QueryDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = TSchema extends {
+    _: infer D;
+} ? HasQueryMethods<D> extends true ? {
+    [key: string]: QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+    [key: number]: QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+    <TKey extends string>(key: TKey): QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>, TRootSchema>;
+} : object : object;
+type QueryDynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames extends string = never, TRootSchema = TSchema> = TSchema extends {
+    _: infer D;
+} ? HasQueryMethods<D> extends true ? {
+    /**
+     * Dynamic path segment placeholder for routes like `/posts/:id`.
+     *
+     * @example
+     * ```ts
+     * useRead((api) => api.posts[123].$get())
+     * useRead((api) => api.posts(':id').$get({ params: { id: 123 } }))
+     * ```
+     */
+    _: QueryOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string, TRootSchema>;
+} : object : object;
+type QueryOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never, TRootSchema = TSchema> = QueryHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & QueryDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & QueryDynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames, TRootSchema> & {
+    [K in keyof StaticPathKeys<TSchema> as K extends SchemaMethod ? never : HasQueryMethods<TSchema[K]> extends true ? K : never]: QueryOnlyClient<TSchema[K], TDefaultError, TOptionsMap, TParamNames, TRootSchema>;
+};
+type MutationHttpMethods<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = {
+    [K in MutationMethod as K extends keyof TSchema ? K : never]: MethodFn<TSchema, K, TDefaultError, TOptionsMap, TParamNames>;
+};
+type MutationDynamicAccess<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = TSchema extends {
+    _: infer D;
+} ? HasMutationMethods<D> extends true ? {
+    [key: string]: MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string>;
+    [key: number]: MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string>;
+    <TKey extends string>(key: TKey): MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | ExtractParamName<TKey>>;
+} : object : object;
+type MutationDynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames extends string = never> = TSchema extends {
+    _: infer D;
+} ? HasMutationMethods<D> extends true ? {
+    /**
+     * Dynamic path segment placeholder for routes like `/posts/:id`.
+     *
+     * @example
+     * ```ts
+     * const { trigger } = useWrite((api) => api.posts(':id').$delete)
+     * trigger({ params: { id: 123 } })
+     * ```
+     */
+    _: MutationOnlyClient<D, TDefaultError, TOptionsMap, TParamNames | string>;
+} : object : object;
+type MutationOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParamNames extends string = never> = MutationHttpMethods<TSchema, TDefaultError, TOptionsMap, TParamNames> & MutationDynamicAccess<TSchema, TDefaultError, TOptionsMap, TParamNames> & MutationDynamicKey<TSchema, TDefaultError, TOptionsMap, TParamNames> & {
+    [K in keyof StaticPathKeys<TSchema> as K extends SchemaMethod ? never : HasMutationMethods<TSchema[K]> extends true ? K : never]: MutationOnlyClient<TSchema[K], TDefaultError, TOptionsMap, TParamNames>;
+};
+
+declare function buildUrl(baseUrl: string, path: string[], query?: Record<string, string | number | boolean | undefined>): string;
+
+/**
+ * Generate cache tags from URL path segments.
+ * e.g., ['posts', '1'] → ['posts', 'posts/1']
+ */
+declare function generateTags(path: string[]): string[];
+
+declare function isJsonBody(body: unknown): body is Record<string, unknown> | unknown[];
+
+/**
+ * Resolves HeadersInitOrGetter to a plain Record<string, string>.
+ * Handles functions, Headers objects, arrays, and plain objects.
+ */
+declare function resolveHeadersToRecord(headers?: HeadersInitOrGetter): Promise<Record<string, string>>;
+declare function mergeHeaders(defaultHeaders?: HeadersInitOrGetter, requestHeaders?: HeadersInitOrGetter): Promise<HeadersInit | undefined>;
+declare function setHeaders(requestOptions: {
+    headers?: HeadersInitOrGetter;
+}, newHeaders: Record<string, string>): void;
+
+declare function objectToFormData(obj: Record<string, unknown>): FormData;
+
+declare function objectToUrlEncoded(obj: Record<string, unknown>): string;
+
+declare function sortObjectKeys(obj: unknown, seen?: WeakSet<object>): unknown;
+
+/**
+ * Common tag options used across plugins and operations.
+ */
+type TagOptions = {
+    /** Custom tags to use instead of auto-generated path-based tags */
+    tags?: string[];
+    /** Additional tags to append to auto-generated or custom tags */
+    additionalTags?: string[];
+};
+declare function resolveTags(options: TagOptions | undefined, resolvedPath: string[]): string[];
+declare function resolvePath(path: string[], params: Record<string, string | number> | undefined): string[];
+
+type ProxyHandlerConfig<TOptions = SpooshOptions> = {
+    baseUrl: string;
+    defaultOptions: TOptions;
+    path?: string[];
+    fetchExecutor?: FetchExecutor<TOptions, AnyRequestOptions>;
+    nextTags?: boolean;
+};
+/**
+ * Creates the real API client proxy that executes actual HTTP requests.
+ *
+ * This proxy intercepts property access and function calls to build URL paths,
+ * then executes fetch requests when an HTTP method ($get, $post, etc.) is called.
+ *
+ * Used internally by `createClient` and `createSpoosh` to create typed API clients.
+ *
+ * @param config - Proxy handler configuration
+ *
+ * @returns A proxy object typed as TSchema that executes real HTTP requests
+ *
+ * @example
+ * ```ts
+ * const api = createProxyHandler<ApiSchema>({ baseUrl: '/api', defaultOptions: {} });
+ *
+ * // Accessing api.posts.$get() will:
+ * // 1. Build path: ['posts']
+ * // 2. Execute: GET /api/posts
+ * await api.posts.$get();
+ *
+ * // Dynamic segments via function call:
+ * // api.posts[123].$get() or api.posts('123').$get()
+ * // Executes: GET /api/posts/123
+ * await api.posts[123].$get();
+ * ```
+ */
+declare function createProxyHandler<TSchema extends object, TOptions = SpooshOptions>(config: ProxyHandlerConfig<TOptions>): TSchema;
+
+/** All supported HTTP method keys used in the API client */
+declare const HTTP_METHODS: readonly ["$get", "$post", "$put", "$patch", "$delete"];
+/** Union type of all HTTP method keys */
+type HttpMethodKey = (typeof HTTP_METHODS)[number];
+/**
+ * A function returned by `createSelectorProxy` that stores the selected path and method.
+ *
+ * Does not execute any request - only captures the API endpoint selection.
+ */
+type SelectorFunction = (() => Promise<{
+    data: undefined;
+}>) & {
+    /** The path segments leading to this endpoint (e.g., ['posts', 'comments']) */
+    __selectorPath?: string[];
+    /** The HTTP method selected (e.g., '$get', '$post') */
+    __selectorMethod?: string;
+};
+/**
+ * Represents a fully captured API call with path, method, and options.
+ *
+ * Captured when an HTTP method is invoked with options.
+ */
+type CapturedCall = {
+    /** Path segments to the endpoint (e.g., ['posts', ':id']) */
+    path: string[];
+    /** HTTP method called (e.g., '$get', '$post') */
+    method: string;
+    /** Request options passed to the method (query, body, params, etc.) */
+    options: unknown;
+};
+/**
+ * Represents the selected endpoint (path and method) without options.
+ *
+ * Captured when an HTTP method is accessed but not yet called.
+ */
+type SelectedEndpoint = {
+    /** Path segments to the endpoint */
+    path: string[];
+    /** HTTP method selected */
+    method: string;
+};
+/**
+ * Result from the selector proxy callback.
+ *
+ * Contains either:
+ * - `call`: Full call details when method is invoked with options (for useRead)
+ * - `selector`: Just path/method when method is accessed (for useWrite)
+ */
+type SelectorResult = {
+    /** Full call details when method is invoked with options */
+    call: CapturedCall | null;
+    /** Endpoint selection when method is accessed but not called */
+    selector: SelectedEndpoint | null;
+};
+/**
+ * Creates a proxy for selecting API endpoints without executing requests.
+ *
+ * Used by plugins to let users specify which cache entries to target
+ * using a type-safe API selector syntax.
+ *
+ * @returns A proxy typed as TSchema for endpoint selection
+ *
+ * @example
+ * ```ts
+ * const proxy = createSelectorProxy<ApiSchema>();
+ *
+ * // Select an endpoint
+ * const endpoint = proxy.posts.$get;
+ *
+ * // Extract path for cache operations
+ * const path = extractPathFromSelector(endpoint); // ['posts']
+ * const method = extractMethodFromSelector(endpoint); // '$get'
+ * ```
+ *
+ * @internal onCapture - Used internally by framework adapters
+ */
+declare function createSelectorProxy<TSchema>(onCapture?: (result: SelectorResult) => void): TSchema;
+/**
+ * Extracts the path segments from a SelectorFunction.
+ *
+ * @param fn - A SelectorFunction returned from `createSelectorProxy`
+ * @returns Array of path segments (e.g., ['posts', 'comments'])
+ *
+ * @example
+ * ```ts
+ * const proxy = createSelectorProxy<ApiSchema>();
+ * const path = extractPathFromSelector(proxy.posts.comments.$get);
+ * // path = ['posts', 'comments']
+ * ```
+ */
+declare function extractPathFromSelector(fn: unknown): string[];
+/**
+ * Extracts the HTTP method from a SelectorFunction.
+ *
+ * @param fn - A SelectorFunction returned from `createSelectorProxy`
+ * @returns The HTTP method string (e.g., '$get', '$post') or undefined
+ *
+ * @example
+ * ```ts
+ * const proxy = createSelectorProxy<ApiSchema>();
+ * const method = extractMethodFromSelector(proxy.posts.$post);
+ * // method = '$post'
+ * ```
+ */
+declare function extractMethodFromSelector(fn: unknown): string | undefined;
+
+declare function executeFetch<TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: SpooshOptions & SpooshOptionsExtra, requestOptions?: AnyRequestOptions, nextTags?: boolean): Promise<SpooshResponse<TData, TError>>;
+
+declare function createMiddleware<TData = unknown, TError = unknown>(name: string, phase: MiddlewarePhase, handler: SpooshMiddleware<TData, TError>["handler"]): SpooshMiddleware<TData, TError>;
+declare function applyMiddlewares<TData = unknown, TError = unknown>(context: MiddlewareContext<TData, TError>, middlewares: SpooshMiddleware<TData, TError>[], phase: MiddlewarePhase): Promise<MiddlewareContext<TData, TError>>;
+declare function composeMiddlewares<TData = unknown, TError = unknown>(...middlewareLists: (SpooshMiddleware<TData, TError>[] | undefined)[]): SpooshMiddleware<TData, TError>[];
+
+/**
+ * Resolves plugin option types based on the full context.
+ *
+ * This is the single entry point for all type resolution. It receives
+ * the full ResolverContext containing schema, data, error, and input types,
+ * and resolves each option key accordingly.
+ *
+ * Plugins extend PluginResolvers via declaration merging to add their own
+ * resolved option types.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types.ts:
+ * declare module "@spoosh/core" {
+ *   interface PluginResolvers<TContext> {
+ *     myOption: MyResolvedType<TContext["data"]> | undefined;
+ *   }
+ * }
+ *
+ * // Type resolution:
+ * type ResolvedOptions = ResolveTypes<
+ *   MergePluginOptions<TPlugins>["read"],
+ *   {
+ *     schema: ApiSchema;
+ *     data: Post[];
+ *     error: Error;
+ *     input: { query: { page: number }; body: never; params: never; formData: never };
+ *   }
+ * >;
+ * ```
+ */
+type ResolveTypes<TOptions, TContext extends ResolverContext> = {
+    [K in keyof TOptions]: K extends keyof PluginResolvers<TContext> ? PluginResolvers<TContext>[K] : TOptions[K] extends DataAwareCallback<infer R, unknown, unknown> | undefined ? DataAwareCallback<R, TContext["data"], TContext["error"]> | undefined : TOptions[K] extends DataAwareTransform<unknown, unknown> | undefined ? DataAwareTransform<TContext["data"], TContext["error"]> | undefined : TOptions[K];
+};
+/**
+ * Resolves schema-aware types in plugin options.
+ * This is a simplified resolver for write operations that only need schema context.
+ */
+type ResolveSchemaTypes<TOptions, TSchema> = ResolveTypes<TOptions, ResolverContext<TSchema>>;
+/**
+ * Resolves plugin result types based on the options passed to the hook.
+ *
+ * This allows plugins to infer result types from the options. For example,
+ * the transform plugin can infer `transformedData` type from the response
+ * transformer's return type.
+ *
+ * @example
+ * ```ts
+ * // Usage in hooks:
+ * type ResolvedResults = ResolveResultTypes<PluginResults["read"], TReadOpts>;
+ * // If TReadOpts has { transform: { response: (d) => { count: number } } }
+ * // Then transformedData will be { count: number } | undefined
+ * ```
+ */
+type ResolveResultTypes<TResults, TOptions> = TResults & PluginResultResolvers<TOptions>;
+/**
+ * Resolves instance API types with schema awareness.
+ * Maps each key in TInstanceApi to its resolved type from resolvers.
+ *
+ * Plugins extend InstanceApiResolvers via declaration merging to add their own
+ * resolved instance API types.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types.ts:
+ * declare module "@spoosh/core" {
+ *   interface InstanceApiResolvers<TSchema> {
+ *     prefetch: PrefetchFn<TSchema>;
+ *   }
+ * }
+ * ```
+ */
+type ResolveInstanceApi<TInstanceApi, TSchema, TReadOptions = object> = {
+    [K in keyof TInstanceApi]: K extends keyof InstanceApiResolvers<TSchema> ? InstanceApiResolvers<TSchema>[K] : TInstanceApi[K];
+};
+
+type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    readOptions: infer R;
+} ? R : object : object;
+type ExtractWriteOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object;
+type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    infiniteReadOptions: infer I;
+} ? I : object : object;
+type ExtractReadResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    readResult: infer R;
+} ? R : object : object;
+type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    writeResult: infer W;
+} ? W : object : object;
+type ExtractInstanceApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    instanceApi: infer A;
+} ? A : object : object;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
+    read: UnionToIntersection<ExtractReadOptions<TPlugins[number]>>;
+    write: UnionToIntersection<ExtractWriteOptions<TPlugins[number]>>;
+    infiniteRead: UnionToIntersection<ExtractInfiniteReadOptions<TPlugins[number]>>;
+};
+type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
+    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
+    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
+};
+type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
+    plugins: TPlugins;
+    _options: MergePluginOptions<TPlugins>;
+};
+declare function createPluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]>(plugins: [...TPlugins]): PluginRegistry<TPlugins>;
+
+type ExtractEndpointData<T> = T extends {
+    data: infer D;
+} ? D : T extends void ? void : T;
+type ExtractEndpointRequestOptions<T> = {
+    [K in Extract<keyof T, "query" | "body" | "params">]?: T[K];
+};
+type EndpointToMethod<T> = (options?: ExtractEndpointRequestOptions<T>) => Promise<SpooshResponse<ExtractEndpointData<T>, unknown, ExtractEndpointRequestOptions<T>>>;
+/**
+ * Schema navigation helper for plugins that need type-safe API schema access.
+ *
+ * This type transforms the API schema into a navigable structure where:
+ * - Static path segments become nested properties
+ * - Dynamic segments (`_`) become index signatures
+ * - `$get` endpoints become callable method types
+ *
+ * Use this in plugin option types that need to reference API endpoints:
+ *
+ * @example
+ * ```ts
+ * // Define your plugin's callback type
+ * type MyCallbackFn<TSchema = unknown> = (
+ *   api: QuerySchemaHelper<TSchema>
+ * ) => unknown;
+ *
+ * // Usage in plugin options
+ * interface MyPluginWriteOptions {
+ *   myCallback?: MyCallbackFn<unknown>;
+ * }
+ *
+ * // Register for schema resolution
+ * declare module '@spoosh/core' {
+ *   interface SchemaResolvers<TSchema> {
+ *     myCallback: MyCallbackFn<TSchema> | undefined;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // User's code - paths are type-checked!
+ * trigger({
+ *   myCallback: (api) => [
+ *     api.posts.$get,           // ✓ Valid
+ *     api.users[1].$get,        // ✓ Dynamic segment
+ *     api.nonexistent.$get,     // ✗ Type error
+ *   ],
+ * });
+ * ```
+ */
+type QuerySchemaHelper<TSchema> = {
+    [K in keyof TSchema as K extends SchemaMethod | "_" ? never : HasQueryMethods<TSchema[K]> extends true ? K : never]: K extends keyof TSchema ? QuerySchemaHelper<TSchema[K]> : never;
+} & {
+    [K in "$get" as K extends keyof TSchema ? K : never]: K extends keyof TSchema ? EndpointToMethod<TSchema[K]> : never;
+} & (TSchema extends {
+    _: infer D;
+} ? HasQueryMethods<D> extends true ? {
+    /**
+     * Dynamic path segment placeholder for routes like `/posts/:id`.
+     *
+     * @example
+     * ```ts
+     * // In plugin callback - reference the endpoint
+     * myCallback: (api) => api.posts._.$get
+     * ```
+     */
+    _: QuerySchemaHelper<D>;
+    [key: string]: QuerySchemaHelper<D>;
+    [key: number]: QuerySchemaHelper<D>;
+} : object : object);
+
+type ExecuteOptions = {
+    force?: boolean;
+};
+type OperationController<TData = unknown, TError = unknown> = {
+    execute: (options?: AnyRequestOptions, executeOptions?: ExecuteOptions) => Promise<SpooshResponse<TData, TError>>;
+    getState: () => OperationState<TData, TError>;
+    subscribe: (callback: () => void) => () => void;
+    abort: () => void;
+    refetch: () => Promise<SpooshResponse<TData, TError>>;
+    /** Called once when hook first mounts */
+    mount: () => void;
+    /** Called once when hook finally unmounts */
+    unmount: () => void;
+    /** Called when options/query changes. Pass previous context for cleanup. */
+    update: (previousContext: PluginContext<TData, TError>) => void;
+    /** Get current context (for passing to update as previousContext) */
+    getContext: () => PluginContext<TData, TError>;
+    setPluginOptions: (options: unknown) => void;
+    setMetadata: (key: string, value: unknown) => void;
+};
+type CreateOperationOptions<TData, TError> = {
+    operationType: OperationType;
+    path: string[];
+    method: HttpMethod;
+    tags: string[];
+    requestOptions?: AnyRequestOptions;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: PluginExecutor;
+    fetchFn: (options: AnyRequestOptions) => Promise<SpooshResponse<TData, TError>>;
+    /** Unique identifier for the hook instance. Persists across queryKey changes. */
+    hookId?: string;
+};
+declare function createOperationController<TData, TError>(options: CreateOperationOptions<TData, TError>): OperationController<TData, TError>;
+
+type InfiniteRequestOptions = {
+    query?: Record<string, unknown>;
+    params?: Record<string, string | number>;
+    body?: unknown;
+};
+type PageContext<TData, TRequest = InfiniteRequestOptions> = {
+    response: TData | undefined;
+    allResponses: TData[];
+    request: TRequest;
+};
+type FetchDirection = "next" | "prev";
+type InfiniteReadState<TData, TItem, TError> = {
+    data: TItem[] | undefined;
+    allResponses: TData[] | undefined;
+    allRequests: InfiniteRequestOptions[] | undefined;
+    canFetchNext: boolean;
+    canFetchPrev: boolean;
+    error: TError | undefined;
+};
+type InfiniteReadController<TData, TItem, TError> = {
+    getState: () => InfiniteReadState<TData, TItem, TError>;
+    getFetchingDirection: () => FetchDirection | null;
+    subscribe: (callback: () => void) => () => void;
+    fetchNext: () => Promise<void>;
+    fetchPrev: () => Promise<void>;
+    refetch: () => Promise<void>;
+    abort: () => void;
+    mount: () => void;
+    unmount: () => void;
+    update: (previousContext: PluginContext<TData, TError>) => void;
+    getContext: () => PluginContext<TData, TError>;
+    setPluginOptions: (options: unknown) => void;
+};
+type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
+    path: string[];
+    method: HttpMethod;
+    tags: string[];
+    initialRequest: InfiniteRequestOptions;
+    baseOptionsForKey: object;
+    canFetchNext: (ctx: PageContext<TData, TRequest>) => boolean;
+    canFetchPrev?: (ctx: PageContext<TData, TRequest>) => boolean;
+    nextPageRequest: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
+    prevPageRequest?: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
+    merger: (responses: TData[]) => TItem[];
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: PluginExecutor;
+    fetchFn: (options: InfiniteRequestOptions, signal: AbortSignal) => Promise<SpooshResponse<TData, TError>>;
+    /** Unique identifier for the hook instance. Persists across queryKey changes. */
+    hookId?: string;
+};
+declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
+
+export { type AnyRequestOptions, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type SpooshClientConfig as ClientConfig, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type Endpoint, type EventEmitter, type ExtractBody, type ExtractData, type ExtractError, type ExtractFormData, type ExtractMethodDef, type ExtractMethodOptions, type ExtractQuery, type ExtractUrlEncoded, type FetchDirection, type FetchExecutor, HTTP_METHODS, type HasMethod, type HasQueryMethods, type HasRequiredOptions, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodFn, type MethodOptionsMap, type MiddlewareContext, type MiddlewareHandler, type MiddlewarePhase, type MutationOnlyClient, type NormalizeEndpoint, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueryOnlyClient, type QuerySchemaHelper, type RefetchEvent, type RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type RetryConfig, type SchemaMethod, type SelectedEndpoint, type SelectorFunction, type SelectorResult, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type StateManager, type StaticPathKeys, type TagOptions, applyMiddlewares, buildUrl, composeMiddlewares, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createMiddleware, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createSpoosh, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, generateTags, isJsonBody, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveTags, setHeaders, sortObjectKeys };