@spoosh/core 0.12.1 → 0.13.0

package/dist/index.d.mts

@@ -172,11 +172,6 @@ interface BuiltInEvents {
     invalidate: string[];
     refetchAll: void;
 }
-/**
- * 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.
@@ -192,7 +187,8 @@ type EventEmitter = {
      * eventEmitter.on<MyPayload>("my-event", (payload) => { ... });
      * ```
      */
-    on<E extends string>(event: E, callback: EventCallback<EventPayload<E>>): () => void;
+    on<E extends keyof BuiltInEvents>(event: E, callback: EventCallback<BuiltInEvents[E]>): () => void;
+    on<T = unknown>(event: string, callback: EventCallback<T>): () => void;
     /**
      * Emit an event. Built-in events have type-safe payloads.
      *
@@ -205,7 +201,8 @@ type EventEmitter = {
      * eventEmitter.emit("my-event", myPayload);
      * ```
      */
-    emit<E extends string>(event: E, payload: EventPayload<E>): void;
+    emit<E extends keyof BuiltInEvents>(event: E, payload: BuiltInEvents[E]): void;
+    emit<T = unknown>(event: string, payload: T): void;
     off: (event: string, callback: EventCallback) => void;
     clear: () => void;
 };
@@ -247,6 +244,190 @@ type StateManager = {
 };
 declare function createStateManager(): StateManager;
 
+/**
+ * Devtool-related types for tracing and debugging.
+ * These types are used by the devtool plugin and plugins that emit trace events.
+ */
+
+/**
+ * Stage of plugin execution for tracing.
+ */
+type TraceStage = "return" | "log" | "skip" | "fetch";
+/**
+ * Color hint for devtools visualization.
+ */
+type TraceColor = "success" | "warning" | "error" | "info" | "muted";
+/**
+ * Structured trace event emitted by plugins.
+ * Plugins self-report what they did and why.
+ */
+type TraceEvent = {
+    /** Plugin name */
+    plugin: string;
+    /** Execution stage */
+    stage: TraceStage;
+    /** Human-readable explanation of what happened */
+    reason?: string;
+    /** Color hint for devtools (success=green, warning=yellow, error=red, info=blue) */
+    color?: TraceColor;
+    /** Before/after diff with optional label */
+    diff?: {
+        before: unknown;
+        after: unknown;
+        label?: string;
+    };
+    /** Structured information to display (e.g., invalidated tags, cache keys) */
+    info?: Array<{
+        label?: string;
+        value: unknown;
+    }>;
+};
+/**
+ * Trace API available to plugins via ctx.trace.
+ * Plugins emit structured events; devtools renders them.
+ *
+ * @example
+ * ```ts
+ * middleware: async (ctx, next) => {
+ *   const cached = getCache(ctx.queryKey);
+ *   if (cached) {
+ *     ctx.trace?.step({
+ *       plugin: "cache",
+ *       stage: "skip",
+ *       meta: { reason: "Cache hit (TTL valid)" }
+ *     });
+ *     return cached;
+ *   }
+ *
+ *   ctx.trace?.step({
+ *     plugin: "cache",
+ *     stage: "before",
+ *     intent: "read",
+ *   });
+ *
+ *   const result = await next();
+ *
+ *   ctx.trace?.step({
+ *     plugin: "cache",
+ *     stage: "after",
+ *     meta: {
+ *       reason: "Stored in cache",
+ *       diff: { before: null, after: result.data }
+ *     }
+ *   });
+ *
+ *   return result;
+ * }
+ * ```
+ */
+type Trace = {
+    /**
+     * Emit a trace event. Lazy evaluation - only computed when devtools is active.
+     *
+     * @param event - Trace event or function that returns trace event (for lazy evaluation)
+     */
+    step: (event: TraceEvent | (() => TraceEvent)) => void;
+};
+/**
+ * Listener for trace events emitted by plugins.
+ */
+type TraceListener = (event: TraceEvent & {
+    queryKey: string;
+    timestamp: number;
+}) => void;
+/**
+ * Standalone event not tied to a request lifecycle.
+ * Used for polling, debounce, gc, and other background activities.
+ */
+type StandaloneEvent = {
+    /** Plugin name */
+    plugin: string;
+    /** Human-readable message */
+    message: string;
+    /** Color hint for devtools */
+    color?: TraceColor;
+    /** Related query key (for filtering) */
+    queryKey?: string;
+    /** Additional metadata */
+    meta?: Record<string, unknown>;
+    /** Timestamp when event occurred */
+    timestamp: number;
+};
+type EventListener = (event: StandaloneEvent) => void;
+type TraceInfo = {
+    label?: string;
+    value: unknown;
+};
+type TraceOptions = {
+    color?: TraceColor;
+    diff?: {
+        before: unknown;
+        after: unknown;
+        label?: string;
+    };
+    info?: TraceInfo[];
+};
+type EventOptions = {
+    color?: TraceColor;
+    /** Query key this event relates to (for filtering) */
+    queryKey?: string;
+    /** Additional metadata to display */
+    meta?: Record<string, unknown>;
+};
+/**
+ * Request-bound tracer API for plugins.
+ * Created via `context.tracer?.(pluginName)`.
+ * Automatically bound to the request's queryKey for accurate devtool tracing.
+ *
+ * @example
+ * ```ts
+ * const t = context.tracer?.("my-plugin");
+ * t?.return("Cache hit", { color: "success" });
+ * t?.log("Transformed", { color: "info", diff: { before, after } });
+ * t?.skip("Nothing to do", { color: "muted" });
+ * ```
+ */
+interface RequestTracer {
+    /** Returned early without calling next() */
+    return(msg: string, options?: TraceOptions): void;
+    /** Did something (any activity worth noting) */
+    log(msg: string, options?: TraceOptions): void;
+    /** Nothing to do, passed through */
+    skip(msg: string, options?: TraceOptions): void;
+}
+/**
+ * Event emitted after all afterResponse hooks complete.
+ * Used by devtools to capture meta snapshots.
+ */
+interface RequestCompleteEvent {
+    context: PluginContext;
+    queryKey: string;
+}
+/**
+ * Internal events used by core and devtools. Not for public use.
+ * @internal
+ */
+interface DevtoolEvents {
+    "spoosh:devtool-event": StandaloneEvent;
+    "spoosh:request-complete": RequestCompleteEvent;
+}
+/**
+ * Event tracer API for standalone events not tied to a request lifecycle.
+ * Created via `context.eventTracer?.(pluginName)`.
+ * Use for async callbacks like polling, debounce completion, gc, etc.
+ *
+ * @example
+ * ```ts
+ * const et = context.eventTracer?.("my-plugin");
+ * et?.emit("Poll triggered", { queryKey, color: "success" });
+ * et?.emit("GC cleaned 5 entries", { color: "info", meta: { count: 5 } });
+ * ```
+ */
+interface EventTracer {
+    /** Emit a standalone event not tied to a request */
+    emit(msg: string, options?: EventOptions): void;
+}
+
 type OperationType = "read" | "write" | "infiniteRead";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
@@ -269,7 +450,23 @@ type CacheEntry<TData = unknown, TError = unknown> = {
 type PluginRequestOptions = Omit<AnyRequestOptions, "headers" | "cache"> & {
     headers: Record<string, string>;
 };
-type PluginContext = {
+/**
+ * Registry for extending PluginContext with custom properties.
+ * Third-party plugins can extend this interface via declaration merging.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types file:
+ * declare module '@spoosh/core' {
+ *   interface PluginContextExtensions {
+ *     myCustomProperty?: MyCustomType;
+ *   }
+ * }
+ * ```
+ */
+interface PluginContextExtensions {
+}
+type PluginContextBase = {
     readonly operationType: OperationType;
     readonly path: string;
     readonly method: HttpMethod;
@@ -292,9 +489,40 @@ type PluginContext = {
     pluginOptions?: unknown;
     /** Force a network request even if cached data exists. Used by plugins to communicate intent. */
     forceRefetch?: boolean;
+    /**
+     * Creates a request-bound tracer for devtools debugging.
+     * Automatically bound to this request's queryKey.
+     * Only available when devtools plugin is active.
+     *
+     * @example
+     * ```ts
+     * const t = ctx.tracer?.("my-plugin");
+     * t?.return("Cache hit", { color: "success" });
+     * t?.log("Processing", { color: "info" });
+     * t?.skip("Nothing to do", { color: "muted" });
+     * ```
+     */
+    tracer?: (plugin: string) => RequestTracer;
+    /**
+     * Creates an event tracer for standalone events not tied to a request lifecycle.
+     * Use for async callbacks like polling, debounce completion, gc, etc.
+     * Only available when devtools plugin is active.
+     *
+     * @example
+     * ```ts
+     * const et = ctx.eventTracer?.("my-plugin");
+     * et?.emit("Poll triggered", { queryKey, color: "success" });
+     * ```
+     */
+    eventTracer?: (plugin: string) => EventTracer;
 };
+/**
+ * Plugin context with extensions from third-party plugins.
+ * Plugins can extend this via PluginContextExtensions declaration merging.
+ */
+type PluginContext = PluginContextBase & PluginContextExtensions;
 /** Input type for creating PluginContext (without injected properties) */
-type PluginContextInput = Omit<PluginContext, "plugins">;
+type PluginContextInput = Omit<PluginContext, "plugins" | "tracer" | "eventTracer">;
 /**
  * Middleware function that wraps the fetch flow.
  * Plugins use this for full control over request/response handling.
@@ -419,9 +647,36 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     lifecycle?: PluginLifecycle;
     /** Expose functions/variables for other plugins to access via `context.plugins.get(name)` */
     exports?: (context: PluginContext) => object;
+    /**
+     * One-time initialization when the Spoosh instance is created.
+     * Use for setting up timers, event listeners, or other side effects.
+     * Runs before instanceApi is called.
+     *
+     * @example
+     * ```ts
+     * setup: ({ stateManager, eventEmitter, pluginExecutor }) => {
+     *   // Set up interval timer
+     *   const intervalId = setInterval(() => {
+     *     // periodic cleanup
+     *   }, 60000);
+     *
+     *   // Register context enhancer
+     *   pluginExecutor.registerContextEnhancer((context) => {
+     *     context.myProperty = myValue;
+     *   });
+     *
+     *   // Set up event listener
+     *   eventEmitter.on("invalidate", (tags) => {
+     *     // handle invalidation
+     *   });
+     * }
+     * ```
+     */
+    setup?: (context: SetupContext) => void;
     /**
      * Expose functions/properties on the framework adapter return value (e.g., create).
      * Unlike `exports`, these are accessible directly from the instance, not just within plugin context.
+     * Should be pure - use `setup` for side effects like timers or event listeners.
      *
      * @example
      * ```ts
@@ -625,6 +880,12 @@ type RefetchEvent = {
 type InstancePluginExecutor = {
     executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext, coreFetch: () => Promise<SpooshResponse<any, any>>) => Promise<SpooshResponse<TData, TError>>;
     createContext: (input: PluginContextInput) => PluginContext;
+    getPlugins: () => readonly SpooshPlugin[];
+    /**
+     * Register a function to enhance every PluginContext during creation.
+     * Call this during plugin setup to inject properties into all request contexts.
+     */
+    registerContextEnhancer: (enhancer: (context: PluginContext) => void) => void;
 };
 /**
  * Context provided to plugin's instanceApi function.
@@ -635,6 +896,25 @@ type InstanceApiContext<TApi = unknown> = {
     stateManager: StateManager;
     eventEmitter: EventEmitter;
     pluginExecutor: InstancePluginExecutor;
+    /**
+     * Creates an event tracer for standalone events.
+     * Only available when devtools plugin is active.
+     */
+    eventTracer?: (plugin: string) => EventTracer;
+};
+/**
+ * Context provided to plugin's setup function.
+ * Used for one-time initialization when the Spoosh instance is created.
+ */
+type SetupContext = {
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: InstancePluginExecutor;
+    /**
+     * Creates an event tracer for standalone events.
+     * Only available when devtools plugin is active.
+     */
+    eventTracer?: (plugin: string) => EventTracer;
 };
 
 type PluginExecutor = {
@@ -644,8 +924,13 @@ type PluginExecutor = {
     executeUpdateLifecycle: (operationType: OperationType, context: PluginContext, previousContext: PluginContext) => Promise<void>;
     executeMiddleware: (operationType: OperationType, context: PluginContext, coreFetch: () => Promise<SpooshResponse<any, any>>) => Promise<SpooshResponse<any, any>>;
     getPlugins: () => readonly SpooshPlugin[];
-    /** Creates a full PluginContext with plugins accessor injected */
+    /** Creates a full PluginContext with plugins accessor */
     createContext: (input: PluginContextInput) => PluginContext;
+    /**
+     * Register a function to enhance every PluginContext during creation.
+     * Call this during plugin setup to inject properties into all request contexts.
+     */
+    registerContextEnhancer: (enhancer: (context: PluginContext) => void) => void;
 };
 declare function createPluginExecutor(initialPlugins?: SpooshPlugin[]): PluginExecutor;
 
@@ -1156,7 +1441,7 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
  * @example Basic usage
  * ```ts
  * const spoosh = new Spoosh<ApiSchema, Error>('/api')
- *   .use([cachePlugin(), debugPlugin()]);
+ *   .use([cachePlugin(), devtool()]);
  *
  * const { api } = client;
  * const response = await api("posts").GET();
@@ -1217,12 +1502,12 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
     /**
      * Adds plugins to the Spoosh instance.
      *
-     * Returns a **new** Spoosh instance with updated plugin types (immutable pattern).
-     * Each call to `.use()` replaces the previous plugins rather than adding to them.
+     * Returns a configured Spoosh instance with the specified plugins.
+     * Can only be called once - the returned instance does not have `.use()`.
      *
      * @template TNewPlugins - The const tuple type of the new plugins array
      * @param plugins - Array of plugin instances to use
-     * @returns A new Spoosh instance with the specified plugins
+     * @returns A configured Spoosh instance (without `.use()` method)
      *
      * ```ts
      * const spoosh = new Spoosh<Schema, Error>('/api').use([
@@ -1232,7 +1517,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * ]);
      * ```
      */
-    use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Spoosh<TSchema, TError, TNewPlugins>;
+    use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Omit<Spoosh<TSchema, TError, TNewPlugins>, "use">;
     /**
      * Cached instance of the underlying SpooshInstance.
      * Created lazily on first property access.
@@ -1446,6 +1731,22 @@ declare function resolvePath(path: string[], params: Record<string, string | num
 declare const isNetworkError: (err: unknown) => boolean;
 declare const isAbortError: (err: unknown) => boolean;
 
+declare function clone<T>(value: T, seen?: WeakMap<WeakKey, any>): T;
+
+/**
+ * Creates a request-bound tracer for a plugin.
+ * Use for middleware, afterResponse, and lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * const t = createTracer("spoosh:cache", context.trace);
+ * t.return("Cache hit", { color: "success" });
+ * t.log("Cached response", { color: "info", diff: { before, after } });
+ * t.skip("No query params", { color: "muted" });
+ * ```
+ */
+declare function createTracer(plugin: string, trace: Trace | undefined): RequestTracer;
+
 type ProxyHandlerConfig<TOptions = SpooshOptions> = {
     baseUrl: string;
     defaultOptions: TOptions;
@@ -1680,4 +1981,4 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
 };
 declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
 
-export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type EventEmitter, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, 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 MethodOptionsMap, 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 PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestOptions$1 as RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StateManager, type StripPrefix, type TagMode, type TagOptions, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, __DEV__, buildUrl, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };
+export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, 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 MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };