@spoosh/core 0.1.0-beta.0 → 0.2.0

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   HTTP_METHODS: () => HTTP_METHODS2,
+  Spoosh: () => Spoosh,
   applyMiddlewares: () => applyMiddlewares,
   buildUrl: () => buildUrl,
   composeMiddlewares: () => composeMiddlewares,
@@ -34,7 +35,6 @@ __export(src_exports, {
   createPluginRegistry: () => createPluginRegistry,
   createProxyHandler: () => createProxyHandler,
   createSelectorProxy: () => createSelectorProxy,
-  createSpoosh: () => createSpoosh,
   createStateManager: () => createStateManager,
   executeFetch: () => executeFetch,
   extractMethodFromSelector: () => extractMethodFromSelector,
@@ -848,33 +848,218 @@ function createPluginRegistry(plugins) {
   };
 }
 
-// src/createSpoosh.ts
-function createSpoosh(config) {
-  const {
-    baseUrl,
-    defaultOptions = {},
-    plugins = []
-  } = config;
-  const api = createProxyHandler({ baseUrl, defaultOptions });
-  const stateManager = createStateManager();
-  const eventEmitter = createEventEmitter();
-  const pluginExecutor = createPluginExecutor([...plugins]);
-  return {
-    api,
-    stateManager,
-    eventEmitter,
-    pluginExecutor,
-    config: {
-      baseUrl,
-      defaultOptions
-    },
-    _types: {
-      schema: void 0,
-      defaultError: void 0,
+// src/Spoosh.ts
+var Spoosh = class _Spoosh {
+  baseUrl;
+  defaultOptions;
+  _plugins;
+  /**
+   * Creates a new Spoosh instance.
+   *
+   * @param baseUrl - The base URL for all API requests (e.g., '/api' or 'https://api.example.com')
+   * @param defaultOptions - Optional default options applied to all requests (headers, credentials, etc.)
+   * @param plugins - Internal parameter used by the `.use()` method. Do not pass directly.
+   *
+   * @example
+   * ```ts
+   * // Simple usage
+   * const client = new Spoosh<ApiSchema, Error>('/api');
+   *
+   * // With default headers
+   * const client = new Spoosh<ApiSchema, Error>('/api', {
+   *   headers: { 'X-API-Key': 'secret' }
+   * });
+   * ```
+   */
+  constructor(baseUrl, defaultOptions, plugins) {
+    this.baseUrl = baseUrl;
+    this.defaultOptions = defaultOptions || {};
+    this._plugins = plugins || [];
+  }
+  /**
+   * 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.
+   *
+   * @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
+   *
+   * @example Single use() call
+   * ```ts
+   * const client = new Spoosh<Schema, Error>('/api')
+   *   .use([cachePlugin(), retryPlugin(), debouncePlugin()]);
+   * ```
+   *
+   * @example Chaining use() calls (replaces plugins)
+   * ```ts
+   * const client1 = new Spoosh<Schema, Error>('/api')
+   *   .use([cachePlugin()]);
+   *
+   * // This replaces cachePlugin with retryPlugin
+   * const client2 = client1.use([retryPlugin()]);
+   * ```
+   *
+   * @example With plugin configuration
+   * ```ts
+   * const client = new Spoosh<Schema, Error>('/api').use([
+   *   cachePlugin({ staleTime: 5000 }),
+   *   retryPlugin({ retries: 3, retryDelay: 1000 }),
+   *   prefetchPlugin(),
+   * ]);
+   * ```
+   */
+  use(plugins) {
+    return new _Spoosh(
+      this.baseUrl,
+      this.defaultOptions,
       plugins
+    );
+  }
+  /**
+   * Cached instance of the underlying SpooshInstance.
+   * Created lazily on first property access.
+   * @private
+   */
+  _instance;
+  /**
+   * Gets or creates the underlying SpooshInstance.
+   * Uses lazy initialization for optimal performance.
+   * @private
+   */
+  getInstance() {
+    if (!this._instance) {
+      const api = createProxyHandler({
+        baseUrl: this.baseUrl,
+        defaultOptions: this.defaultOptions
+      });
+      const stateManager = createStateManager();
+      const eventEmitter = createEventEmitter();
+      const pluginExecutor = createPluginExecutor([...this._plugins]);
+      this._instance = {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor,
+        config: {
+          baseUrl: this.baseUrl,
+          defaultOptions: this.defaultOptions
+        },
+        _types: {
+          schema: void 0,
+          defaultError: void 0,
+          plugins: this._plugins
+        }
+      };
     }
-  };
-}
+    return this._instance;
+  }
+  /**
+   * The type-safe API client for making requests.
+   *
+   * Provides a proxy-based interface for accessing endpoints defined in your schema.
+   *
+   * @example
+   * ```ts
+   * const client = new Spoosh<ApiSchema, Error>('/api').use([...]);
+   * const { api } = client;
+   *
+   * // GET request
+   * const { data } = await api.posts.$get();
+   *
+   * // POST request with body
+   * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
+   *
+   * // Dynamic path parameters
+   * const { data } = await api.posts[postId].$get();
+   * ```
+   */
+  get api() {
+    return this.getInstance().api;
+  }
+  /**
+   * State manager for cache and state operations.
+   *
+   * Provides methods for managing cached data, invalidating entries, and retrieving state.
+   *
+   * @example
+   * ```ts
+   * const { stateManager } = client;
+   *
+   * // Get cached data
+   * const cache = stateManager.getCache('posts.$get');
+   *
+   * // Invalidate cache by tag
+   * stateManager.invalidate(['posts']);
+   *
+   * // Clear all cache
+   * stateManager.clearCache();
+   * ```
+   */
+  get stateManager() {
+    return this.getInstance().stateManager;
+  }
+  /**
+   * Event emitter for subscribing to refetch and invalidation events.
+   *
+   * Used internally by plugins and hooks to trigger re-fetches.
+   *
+   * @example
+   * ```ts
+   * const { eventEmitter } = client;
+   *
+   * // Subscribe to refetch events
+   * eventEmitter.on('refetch', ({ queryKey, reason }) => {
+   *   console.log(`Refetching ${queryKey} due to ${reason}`);
+   * });
+   * ```
+   */
+  get eventEmitter() {
+    return this.getInstance().eventEmitter;
+  }
+  /**
+   * Plugin executor that manages plugin lifecycle and middleware.
+   *
+   * Provides access to registered plugins and their execution context.
+   *
+   * @example
+   * ```ts
+   * const { pluginExecutor } = client;
+   *
+   * // Get all registered plugins
+   * const plugins = pluginExecutor.getPlugins();
+   *
+   * // Check if a plugin is registered
+   * const hasCache = plugins.some(p => p.name === 'cache');
+   * ```
+   */
+  get pluginExecutor() {
+    return this.getInstance().pluginExecutor;
+  }
+  /**
+   * Configuration object containing baseUrl and defaultOptions.
+   *
+   * @example
+   * ```ts
+   * const { config } = client;
+   * console.log(config.baseUrl); // '/api'
+   * console.log(config.defaultOptions); // { headers: {...} }
+   * ```
+   */
+  get config() {
+    return this.getInstance().config;
+  }
+  /**
+   * Type information carrier for generic type inference.
+   * Used internally by TypeScript for type resolution.
+   *
+   * @internal
+   */
+  get _types() {
+    return this.getInstance()._types;
+  }
+};
 
 // src/createClient.ts
 function createClient(config) {

package/dist/index.mjs

@@ -794,33 +794,218 @@ function createPluginRegistry(plugins) {
   };
 }
 
-// src/createSpoosh.ts
-function createSpoosh(config) {
-  const {
-    baseUrl,
-    defaultOptions = {},
-    plugins = []
-  } = config;
-  const api = createProxyHandler({ baseUrl, defaultOptions });
-  const stateManager = createStateManager();
-  const eventEmitter = createEventEmitter();
-  const pluginExecutor = createPluginExecutor([...plugins]);
-  return {
-    api,
-    stateManager,
-    eventEmitter,
-    pluginExecutor,
-    config: {
-      baseUrl,
-      defaultOptions
-    },
-    _types: {
-      schema: void 0,
-      defaultError: void 0,
+// src/Spoosh.ts
+var Spoosh = class _Spoosh {
+  baseUrl;
+  defaultOptions;
+  _plugins;
+  /**
+   * Creates a new Spoosh instance.
+   *
+   * @param baseUrl - The base URL for all API requests (e.g., '/api' or 'https://api.example.com')
+   * @param defaultOptions - Optional default options applied to all requests (headers, credentials, etc.)
+   * @param plugins - Internal parameter used by the `.use()` method. Do not pass directly.
+   *
+   * @example
+   * ```ts
+   * // Simple usage
+   * const client = new Spoosh<ApiSchema, Error>('/api');
+   *
+   * // With default headers
+   * const client = new Spoosh<ApiSchema, Error>('/api', {
+   *   headers: { 'X-API-Key': 'secret' }
+   * });
+   * ```
+   */
+  constructor(baseUrl, defaultOptions, plugins) {
+    this.baseUrl = baseUrl;
+    this.defaultOptions = defaultOptions || {};
+    this._plugins = plugins || [];
+  }
+  /**
+   * 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.
+   *
+   * @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
+   *
+   * @example Single use() call
+   * ```ts
+   * const client = new Spoosh<Schema, Error>('/api')
+   *   .use([cachePlugin(), retryPlugin(), debouncePlugin()]);
+   * ```
+   *
+   * @example Chaining use() calls (replaces plugins)
+   * ```ts
+   * const client1 = new Spoosh<Schema, Error>('/api')
+   *   .use([cachePlugin()]);
+   *
+   * // This replaces cachePlugin with retryPlugin
+   * const client2 = client1.use([retryPlugin()]);
+   * ```
+   *
+   * @example With plugin configuration
+   * ```ts
+   * const client = new Spoosh<Schema, Error>('/api').use([
+   *   cachePlugin({ staleTime: 5000 }),
+   *   retryPlugin({ retries: 3, retryDelay: 1000 }),
+   *   prefetchPlugin(),
+   * ]);
+   * ```
+   */
+  use(plugins) {
+    return new _Spoosh(
+      this.baseUrl,
+      this.defaultOptions,
       plugins
+    );
+  }
+  /**
+   * Cached instance of the underlying SpooshInstance.
+   * Created lazily on first property access.
+   * @private
+   */
+  _instance;
+  /**
+   * Gets or creates the underlying SpooshInstance.
+   * Uses lazy initialization for optimal performance.
+   * @private
+   */
+  getInstance() {
+    if (!this._instance) {
+      const api = createProxyHandler({
+        baseUrl: this.baseUrl,
+        defaultOptions: this.defaultOptions
+      });
+      const stateManager = createStateManager();
+      const eventEmitter = createEventEmitter();
+      const pluginExecutor = createPluginExecutor([...this._plugins]);
+      this._instance = {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor,
+        config: {
+          baseUrl: this.baseUrl,
+          defaultOptions: this.defaultOptions
+        },
+        _types: {
+          schema: void 0,
+          defaultError: void 0,
+          plugins: this._plugins
+        }
+      };
     }
-  };
-}
+    return this._instance;
+  }
+  /**
+   * The type-safe API client for making requests.
+   *
+   * Provides a proxy-based interface for accessing endpoints defined in your schema.
+   *
+   * @example
+   * ```ts
+   * const client = new Spoosh<ApiSchema, Error>('/api').use([...]);
+   * const { api } = client;
+   *
+   * // GET request
+   * const { data } = await api.posts.$get();
+   *
+   * // POST request with body
+   * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
+   *
+   * // Dynamic path parameters
+   * const { data } = await api.posts[postId].$get();
+   * ```
+   */
+  get api() {
+    return this.getInstance().api;
+  }
+  /**
+   * State manager for cache and state operations.
+   *
+   * Provides methods for managing cached data, invalidating entries, and retrieving state.
+   *
+   * @example
+   * ```ts
+   * const { stateManager } = client;
+   *
+   * // Get cached data
+   * const cache = stateManager.getCache('posts.$get');
+   *
+   * // Invalidate cache by tag
+   * stateManager.invalidate(['posts']);
+   *
+   * // Clear all cache
+   * stateManager.clearCache();
+   * ```
+   */
+  get stateManager() {
+    return this.getInstance().stateManager;
+  }
+  /**
+   * Event emitter for subscribing to refetch and invalidation events.
+   *
+   * Used internally by plugins and hooks to trigger re-fetches.
+   *
+   * @example
+   * ```ts
+   * const { eventEmitter } = client;
+   *
+   * // Subscribe to refetch events
+   * eventEmitter.on('refetch', ({ queryKey, reason }) => {
+   *   console.log(`Refetching ${queryKey} due to ${reason}`);
+   * });
+   * ```
+   */
+  get eventEmitter() {
+    return this.getInstance().eventEmitter;
+  }
+  /**
+   * Plugin executor that manages plugin lifecycle and middleware.
+   *
+   * Provides access to registered plugins and their execution context.
+   *
+   * @example
+   * ```ts
+   * const { pluginExecutor } = client;
+   *
+   * // Get all registered plugins
+   * const plugins = pluginExecutor.getPlugins();
+   *
+   * // Check if a plugin is registered
+   * const hasCache = plugins.some(p => p.name === 'cache');
+   * ```
+   */
+  get pluginExecutor() {
+    return this.getInstance().pluginExecutor;
+  }
+  /**
+   * Configuration object containing baseUrl and defaultOptions.
+   *
+   * @example
+   * ```ts
+   * const { config } = client;
+   * console.log(config.baseUrl); // '/api'
+   * console.log(config.defaultOptions); // { headers: {...} }
+   * ```
+   */
+  get config() {
+    return this.getInstance().config;
+  }
+  /**
+   * Type information carrier for generic type inference.
+   * Used internally by TypeScript for type resolution.
+   *
+   * @internal
+   */
+  get _types() {
+    return this.getInstance()._types;
+  }
+};
 
 // src/createClient.ts
 function createClient(config) {
@@ -1387,6 +1572,7 @@ function createInfiniteReadController(options) {
 }
 export {
   HTTP_METHODS2 as HTTP_METHODS,
+  Spoosh,
   applyMiddlewares,
   buildUrl,
   composeMiddlewares,
@@ -1400,7 +1586,6 @@ export {
   createPluginRegistry,
   createProxyHandler,
   createSelectorProxy,
-  createSpoosh,
   createStateManager,
   executeFetch,
   extractMethodFromSelector,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/core",
-  "version": "0.1.0-beta.0",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Type-safe API client with plugin middleware system",
   "keywords": [