@spoosh/plugin-prefetch 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @spoosh/plugin-prefetch
+
+Prefetch plugin for Spoosh - preload data before it's needed.
+
+**[Documentation](https://spoosh.dev/docs/plugins/prefetch)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`
+
+## Installation
+
+```bash
+npm install @spoosh/plugin-prefetch
+```
+
+## Usage
+
+```typescript
+import { prefetchPlugin } from "@spoosh/plugin-prefetch";
+
+// Setup - prefetch is returned from createReactSpoosh
+const plugins = [prefetchPlugin(), cachePlugin(), retryPlugin()];
+const spoosh = createSpoosh<ApiSchema, Error, typeof plugins>({ baseUrl: "/api", plugins });
+const { useRead, useWrite, prefetch } = createReactSpoosh(spoosh);
+
+// Basic prefetch
+await prefetch((api) => api.posts.$get());
+
+// Prefetch with query options
+await prefetch((api) => api.posts.$get({ query: { page: 1, limit: 10 } }));
+
+// Prefetch with plugin options (staleTime, retries, etc.)
+await prefetch(
+  (api) => api.users[userId].$get(),
+  {
+    staleTime: 60000,
+    retries: 3,
+  }
+);
+
+// Prefetch on hover
+<Link
+  href="/posts/1"
+  onMouseEnter={() => prefetch((api) => api.posts[1].$get())}
+>
+  View Post
+</Link>
+```
+
+## Options
+
+### Plugin Config
+
+| Option           | Type     | Default | Description                                                       |
+| ---------------- | -------- | ------- | ----------------------------------------------------------------- |
+| `staleTime` | `number` | -       | Default stale time for prefetched data (ms)                       |
+| `timeout`   | `number` | `30000` | Timeout to auto-clear stale promises (ms). Prevents memory leaks. |
+
+### Prefetch Options
+
+The second argument to `prefetch()` accepts any plugin options (staleTime, retries, dedupe, etc.) plus:
+
+| Option           | Type       | Description               |
+| ---------------- | ---------- | ------------------------- |
+| `tags`           | `string[]` | Custom cache tags         |
+| `additionalTags` | `string[]` | Additional tags to append |
+
+## Features
+
+### In-Flight Deduplication (Built-in)
+
+Multiple calls to prefetch the same data will return the same promise, avoiding duplicate requests. This is built into the prefetch plugin - no deduplication plugin required.
+
+```typescript
+// These will only make ONE network request
+prefetch((api) => api.posts.$get());
+prefetch((api) => api.posts.$get());
+prefetch((api) => api.posts.$get());
+```
+
+### Memory Leak Prevention
+
+Prefetch automatically clears promise references after completion or after `promiseTimeout` (default 30s). This prevents memory leaks from requests that never settle.

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+import { QuerySchemaHelper, SpooshResponse, TagOptions, SpooshPlugin } from '@spoosh/core';
+
+interface PrefetchPluginConfig {
+    /** Default stale time for prefetched data in milliseconds */
+    staleTime?: number;
+    /**
+     * Timeout in milliseconds after which stale promises are automatically cleared.
+     * Prevents memory leaks from requests that never settle.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+interface PrefetchOptions extends TagOptions {
+    /** Additional plugin options (staleTime, retries, dedupe, etc.) */
+    [key: string]: unknown;
+}
+type PrefetchCallbackFn<TSchema> = (api: QuerySchemaHelper<TSchema>) => Promise<SpooshResponse<unknown, unknown>>;
+type PrefetchFn<TSchema, TPluginOptions = object> = <TData = unknown, TError = unknown>(selector: PrefetchCallbackFn<TSchema>, options?: PrefetchOptions & TPluginOptions) => Promise<SpooshResponse<TData, TError>>;
+interface PrefetchInstanceApi {
+    prefetch: PrefetchFn<unknown>;
+}
+declare module "@spoosh/core" {
+    interface InstanceApiResolvers<TSchema> {
+        prefetch: PrefetchFn<TSchema>;
+    }
+}
+
+/**
+ * Provides prefetching capabilities to load data before it's needed.
+ *
+ * The prefetch function runs through the full plugin middleware chain,
+ * so features like caching, retry, and deduplication work automatically.
+ *
+ * @param config - Configuration options (reserved for future use)
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/prefetch | Prefetch Plugin Documentation}
+ *
+ * @returns Prefetch plugin instance
+ *
+ * @example
+ * ```ts
+ * // Setup
+ * const plugins = [prefetchPlugin(), cachePlugin(), retryPlugin()];
+ * const { prefetch } = createReactSpoosh(spoosh);
+ *
+ * // Basic prefetch
+ * await prefetch((api) => api.posts.$get());
+ *
+ * // Prefetch with query options
+ * await prefetch((api) => api.posts.$get({ query: { page: 1, limit: 10 } }));
+ *
+ * // Prefetch with plugin options (staleTime, retries, etc.)
+ * await prefetch((api) => api.users[userId].$get(), {
+ *   staleTime: 60000,
+ *   retries: 3,
+ * });
+ *
+ * // Prefetch on hover
+ * <Link
+ *   href="/posts/1"
+ *   onMouseEnter={() => prefetch((api) => api.posts[1].$get())}
+ * >
+ *   View Post
+ * </Link>
+ * ```
+ */
+declare function prefetchPlugin(config?: PrefetchPluginConfig): SpooshPlugin<{
+    instanceApi: PrefetchInstanceApi;
+}>;
+
+export { type PrefetchFn, type PrefetchInstanceApi, type PrefetchOptions, type PrefetchPluginConfig, prefetchPlugin };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { QuerySchemaHelper, SpooshResponse, TagOptions, SpooshPlugin } from '@spoosh/core';
+
+interface PrefetchPluginConfig {
+    /** Default stale time for prefetched data in milliseconds */
+    staleTime?: number;
+    /**
+     * Timeout in milliseconds after which stale promises are automatically cleared.
+     * Prevents memory leaks from requests that never settle.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+interface PrefetchOptions extends TagOptions {
+    /** Additional plugin options (staleTime, retries, dedupe, etc.) */
+    [key: string]: unknown;
+}
+type PrefetchCallbackFn<TSchema> = (api: QuerySchemaHelper<TSchema>) => Promise<SpooshResponse<unknown, unknown>>;
+type PrefetchFn<TSchema, TPluginOptions = object> = <TData = unknown, TError = unknown>(selector: PrefetchCallbackFn<TSchema>, options?: PrefetchOptions & TPluginOptions) => Promise<SpooshResponse<TData, TError>>;
+interface PrefetchInstanceApi {
+    prefetch: PrefetchFn<unknown>;
+}
+declare module "@spoosh/core" {
+    interface InstanceApiResolvers<TSchema> {
+        prefetch: PrefetchFn<TSchema>;
+    }
+}
+
+/**
+ * Provides prefetching capabilities to load data before it's needed.
+ *
+ * The prefetch function runs through the full plugin middleware chain,
+ * so features like caching, retry, and deduplication work automatically.
+ *
+ * @param config - Configuration options (reserved for future use)
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/prefetch | Prefetch Plugin Documentation}
+ *
+ * @returns Prefetch plugin instance
+ *
+ * @example
+ * ```ts
+ * // Setup
+ * const plugins = [prefetchPlugin(), cachePlugin(), retryPlugin()];
+ * const { prefetch } = createReactSpoosh(spoosh);
+ *
+ * // Basic prefetch
+ * await prefetch((api) => api.posts.$get());
+ *
+ * // Prefetch with query options
+ * await prefetch((api) => api.posts.$get({ query: { page: 1, limit: 10 } }));
+ *
+ * // Prefetch with plugin options (staleTime, retries, etc.)
+ * await prefetch((api) => api.users[userId].$get(), {
+ *   staleTime: 60000,
+ *   retries: 3,
+ * });
+ *
+ * // Prefetch on hover
+ * <Link
+ *   href="/posts/1"
+ *   onMouseEnter={() => prefetch((api) => api.posts[1].$get())}
+ * >
+ *   View Post
+ * </Link>
+ * ```
+ */
+declare function prefetchPlugin(config?: PrefetchPluginConfig): SpooshPlugin<{
+    instanceApi: PrefetchInstanceApi;
+}>;
+
+export { type PrefetchFn, type PrefetchInstanceApi, type PrefetchOptions, type PrefetchPluginConfig, prefetchPlugin };

package/dist/index.js

@@ -0,0 +1,179 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  prefetchPlugin: () => prefetchPlugin
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/plugin.ts
+var import_core = require("@spoosh/core");
+
+// src/promise-cache.ts
+var DEFAULT_PROMISE_TIMEOUT = 3e4;
+function storePromiseInCache(promise, options) {
+  const { stateManager, queryKey, timeout = DEFAULT_PROMISE_TIMEOUT } = options;
+  let promiseCleared = false;
+  const clearPromise = () => {
+    if (promiseCleared) return;
+    promiseCleared = true;
+    stateManager.setPendingPromise(queryKey, void 0);
+  };
+  stateManager.setPendingPromise(queryKey, promise);
+  const timeoutId = setTimeout(() => {
+    clearPromise();
+  }, timeout);
+  promise.finally(() => {
+    clearTimeout(timeoutId);
+    clearPromise();
+  });
+  return { clearPromise };
+}
+
+// src/plugin.ts
+function prefetchPlugin(config = {}) {
+  const { timeout } = config;
+  return {
+    name: "spoosh:prefetch",
+    operations: [],
+    instanceApi(context) {
+      const { api, stateManager, eventEmitter, pluginExecutor } = context;
+      const prefetch = async (selector, options = {}) => {
+        const { tags, additionalTags } = options;
+        let callPath = [];
+        let callMethod = "";
+        let callOptions = void 0;
+        const selectorProxy = (0, import_core.createSelectorProxy)((result) => {
+          if (result.call) {
+            callPath = result.call.path;
+            callMethod = result.call.method;
+            callOptions = result.call.options;
+          } else if (result.selector) {
+            callPath = result.selector.path;
+            callMethod = result.selector.method;
+          }
+        });
+        selector(selectorProxy);
+        if (!callMethod) {
+          throw new Error(
+            "prefetch requires selecting a $get method. Example: prefetch((api) => api.posts.$get())"
+          );
+        }
+        const resolvedPath = (0, import_core.resolvePath)(callPath, void 0);
+        const resolvedTags = (0, import_core.resolveTags)(
+          { tags, additionalTags },
+          resolvedPath
+        );
+        const queryKey = stateManager.createQueryKey({
+          path: callPath,
+          method: callMethod,
+          options: callOptions
+        });
+        const initialState = (0, import_core.createInitialState)();
+        const abortController = new AbortController();
+        const pluginContext = pluginExecutor.createContext({
+          operationType: "read",
+          path: callPath,
+          method: callMethod,
+          queryKey,
+          tags: resolvedTags,
+          requestTimestamp: Date.now(),
+          requestOptions: callOptions ?? {},
+          state: initialState,
+          metadata: /* @__PURE__ */ new Map(),
+          pluginOptions: options,
+          abort: () => abortController.abort(),
+          stateManager,
+          eventEmitter
+        });
+        const coreFetch = async () => {
+          pluginContext.requestOptions.signal = abortController.signal;
+          const updateState = (updater) => {
+            const cached = stateManager.getCache(queryKey);
+            if (cached) {
+              stateManager.setCache(queryKey, {
+                state: { ...cached.state, ...updater }
+              });
+            } else {
+              stateManager.setCache(queryKey, {
+                state: { ...initialState, ...updater },
+                tags: resolvedTags
+              });
+            }
+          };
+          try {
+            let current = api;
+            for (const segment of resolvedPath) {
+              current = current[segment];
+            }
+            const method = current[callMethod];
+            const mergedOptions = {
+              ...callOptions,
+              ...pluginContext.requestOptions
+            };
+            const response = await method(mergedOptions);
+            pluginContext.response = response;
+            if (response.data !== void 0 && !response.error) {
+              updateState({
+                data: response.data,
+                error: void 0,
+                timestamp: Date.now()
+              });
+            }
+            return response;
+          } catch (err) {
+            if (abortController.signal.aborted) {
+              return {
+                status: 0,
+                data: void 0,
+                error: void 0,
+                aborted: true
+              };
+            }
+            const errorResponse = {
+              status: 0,
+              error: err,
+              data: void 0
+            };
+            pluginContext.response = errorResponse;
+            return errorResponse;
+          }
+        };
+        const existingPromise = stateManager.getPendingPromise(queryKey);
+        if (existingPromise) {
+          return existingPromise;
+        }
+        const fetchPromise = pluginExecutor.executeMiddleware(
+          "read",
+          pluginContext,
+          coreFetch
+        );
+        storePromiseInCache(fetchPromise, {
+          stateManager,
+          queryKey,
+          timeout
+        });
+        return fetchPromise;
+      };
+      return { prefetch };
+    }
+  };
+}

package/dist/index.mjs

@@ -0,0 +1,161 @@
+// src/plugin.ts
+import {
+  createSelectorProxy,
+  resolvePath,
+  resolveTags,
+  createInitialState
+} from "@spoosh/core";
+
+// src/promise-cache.ts
+var DEFAULT_PROMISE_TIMEOUT = 3e4;
+function storePromiseInCache(promise, options) {
+  const { stateManager, queryKey, timeout = DEFAULT_PROMISE_TIMEOUT } = options;
+  let promiseCleared = false;
+  const clearPromise = () => {
+    if (promiseCleared) return;
+    promiseCleared = true;
+    stateManager.setPendingPromise(queryKey, void 0);
+  };
+  stateManager.setPendingPromise(queryKey, promise);
+  const timeoutId = setTimeout(() => {
+    clearPromise();
+  }, timeout);
+  promise.finally(() => {
+    clearTimeout(timeoutId);
+    clearPromise();
+  });
+  return { clearPromise };
+}
+
+// src/plugin.ts
+function prefetchPlugin(config = {}) {
+  const { timeout } = config;
+  return {
+    name: "spoosh:prefetch",
+    operations: [],
+    instanceApi(context) {
+      const { api, stateManager, eventEmitter, pluginExecutor } = context;
+      const prefetch = async (selector, options = {}) => {
+        const { tags, additionalTags } = options;
+        let callPath = [];
+        let callMethod = "";
+        let callOptions = void 0;
+        const selectorProxy = createSelectorProxy((result) => {
+          if (result.call) {
+            callPath = result.call.path;
+            callMethod = result.call.method;
+            callOptions = result.call.options;
+          } else if (result.selector) {
+            callPath = result.selector.path;
+            callMethod = result.selector.method;
+          }
+        });
+        selector(selectorProxy);
+        if (!callMethod) {
+          throw new Error(
+            "prefetch requires selecting a $get method. Example: prefetch((api) => api.posts.$get())"
+          );
+        }
+        const resolvedPath = resolvePath(callPath, void 0);
+        const resolvedTags = resolveTags(
+          { tags, additionalTags },
+          resolvedPath
+        );
+        const queryKey = stateManager.createQueryKey({
+          path: callPath,
+          method: callMethod,
+          options: callOptions
+        });
+        const initialState = createInitialState();
+        const abortController = new AbortController();
+        const pluginContext = pluginExecutor.createContext({
+          operationType: "read",
+          path: callPath,
+          method: callMethod,
+          queryKey,
+          tags: resolvedTags,
+          requestTimestamp: Date.now(),
+          requestOptions: callOptions ?? {},
+          state: initialState,
+          metadata: /* @__PURE__ */ new Map(),
+          pluginOptions: options,
+          abort: () => abortController.abort(),
+          stateManager,
+          eventEmitter
+        });
+        const coreFetch = async () => {
+          pluginContext.requestOptions.signal = abortController.signal;
+          const updateState = (updater) => {
+            const cached = stateManager.getCache(queryKey);
+            if (cached) {
+              stateManager.setCache(queryKey, {
+                state: { ...cached.state, ...updater }
+              });
+            } else {
+              stateManager.setCache(queryKey, {
+                state: { ...initialState, ...updater },
+                tags: resolvedTags
+              });
+            }
+          };
+          try {
+            let current = api;
+            for (const segment of resolvedPath) {
+              current = current[segment];
+            }
+            const method = current[callMethod];
+            const mergedOptions = {
+              ...callOptions,
+              ...pluginContext.requestOptions
+            };
+            const response = await method(mergedOptions);
+            pluginContext.response = response;
+            if (response.data !== void 0 && !response.error) {
+              updateState({
+                data: response.data,
+                error: void 0,
+                timestamp: Date.now()
+              });
+            }
+            return response;
+          } catch (err) {
+            if (abortController.signal.aborted) {
+              return {
+                status: 0,
+                data: void 0,
+                error: void 0,
+                aborted: true
+              };
+            }
+            const errorResponse = {
+              status: 0,
+              error: err,
+              data: void 0
+            };
+            pluginContext.response = errorResponse;
+            return errorResponse;
+          }
+        };
+        const existingPromise = stateManager.getPendingPromise(queryKey);
+        if (existingPromise) {
+          return existingPromise;
+        }
+        const fetchPromise = pluginExecutor.executeMiddleware(
+          "read",
+          pluginContext,
+          coreFetch
+        );
+        storePromiseInCache(fetchPromise, {
+          stateManager,
+          queryKey,
+          timeout
+        });
+        return fetchPromise;
+      };
+      return { prefetch };
+    }
+  };
+}
+export {
+  prefetchPlugin
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@spoosh/plugin-prefetch",
+  "version": "0.1.0-beta.0",
+  "description": "Prefetch plugin for Spoosh - preload data before it's needed",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-prefetch"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/prefetch",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "prefetch",
+    "api-client",
+    "preload"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@spoosh/core": "0.1.0-beta.0",
+    "@spoosh/test-utils": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}