@fetchkit/ffetch 5.3.0 → 5.4.1

package/README.md

@@ -66,6 +66,7 @@ ffetch uses a plugin architecture for optional features, so you only include wha
 - **Bulkhead plugin (optional, prebuilt)** – cap concurrency and queue depth per client instance
 - **Circuit breaker plugin (optional, prebuilt)** – automatic failure protection
 - **Hedge plugin (optional, prebuilt)** – race parallel attempts to reduce tail latency
+- **Context ID plugin (optional, prebuilt)** – inject a stable context ID header across retries/hedges for correlation
 - **Deduplication plugin (optional, prebuilt)** – automatic deduping of in-flight identical requests
 - **Request shortcuts plugin (optional, prebuilt)** – call `client.get(url)` / `.post()` / `.put()` / `.patch()` / `.delete()` directly on the client
 - **Response shortcuts plugin (optional, prebuilt)** – call `client(url).json()` / `.text()` / `.blob()` directly on the request promise
@@ -81,6 +82,7 @@ All plugins are tree-shakeable — import only what you use.
 - **bulkheadPlugin (optional)**: cap in-flight concurrency with optional queue backpressure.
 - **hedgePlugin (optional)**: race multiple attempts and cancel losers when a winner is found.
 - **circuitPlugin (optional)**: fail fast after repeated failures.
+- **contextIdPlugin (optional)**: inject a stable request context ID (for example in `x-context-id`) across retries and hedges.
 - **requestShortcutsPlugin (optional)**: HTTP method shortcuts on the client (`.get()` / `.post()` / `.put()` / `.patch()` / `.delete()` / `.head()` / `.options()`).
 - **responseShortcutsPlugin (optional)**: use `client(url).json()` / `.text()` / `.blob()` style parsing.
 - **downloadProgressPlugin (optional)**: stream download progress via `onProgress(progress, chunk)` callback.
@@ -137,6 +139,7 @@ const users = (await response.json()) as User[]
 import { createClient } from '@fetchkit/ffetch'
 import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
 import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+import { contextIdPlugin } from '@fetchkit/ffetch/plugins/context-id'
 import { requestShortcutsPlugin } from '@fetchkit/ffetch/plugins/request-shortcuts'
 import { responseShortcutsPlugin } from '@fetchkit/ffetch/plugins/response-shortcuts'
 
@@ -148,9 +151,11 @@ const api = createClient({
     dedupePlugin({ ttl: 30_000, sweepInterval: 5_000 }),
     // 2) Optional: open the circuit after repeated failures
     circuitPlugin({ threshold: 5, reset: 30_000 }),
-    // 3) Optional: enable request-promise parsing shortcuts
+    // 3) Optional: inject stable correlation context IDs
+    contextIdPlugin(),
+    // 4) Optional: enable request-promise parsing shortcuts
     responseShortcutsPlugin(),
-    // 4) Optional: enable client HTTP method shortcuts
+    // 5) Optional: enable client HTTP method shortcuts
     requestShortcutsPlugin(),
   ],
 })
@@ -169,6 +174,7 @@ What this setup gives you:
 - **Operational safety**: retries with timeout defaults.
 - **Lower duplicate traffic (optional)**: concurrent identical requests share one in-flight call.
 - **Faster failure recovery (optional)**: circuit breaker blocks repeated failing calls.
+- **Better observability correlation (optional)**: stable request context IDs across retries and hedges.
 - **Cleaner request ergonomics (optional)**: `client.get(url)` / `.post(url, init)` style shortcuts.
 - **Cleaner parsing (optional)**: `client(url).json()` style shortcuts.
 

package/dist/plugins/context-id.cjs

@@ -0,0 +1,74 @@
+"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/plugins/context-id.ts
+var context_id_exports = {};
+__export(context_id_exports, {
+  contextIdPlugin: () => contextIdPlugin
+});
+module.exports = __toCommonJS(context_id_exports);
+var CONTEXT_ID_STATE_KEY = "__contextId";
+function defaultGenerateContextId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function defaultInjectContextId(id, request) {
+  request.headers.set("x-context-id", id);
+}
+function resolveContextId(ctx, generate) {
+  const existing = ctx.request.headers.get("x-context-id");
+  if (existing) {
+    ctx.state[CONTEXT_ID_STATE_KEY] = existing;
+    return existing;
+  }
+  const fromState = ctx.state[CONTEXT_ID_STATE_KEY];
+  if (typeof fromState === "string" && fromState.length > 0) {
+    return fromState;
+  }
+  const generated = generate();
+  ctx.state[CONTEXT_ID_STATE_KEY] = generated;
+  return generated;
+}
+function contextIdPlugin(options = {}) {
+  const {
+    generate = defaultGenerateContextId,
+    inject = defaultInjectContextId,
+    order = 1
+  } = options;
+  return {
+    name: "context-id",
+    order,
+    preRequest: (ctx) => {
+      const id = resolveContextId(ctx, generate);
+      inject(id, ctx.request);
+    },
+    wrapDispatch: (next) => async (ctx) => {
+      const id = resolveContextId(ctx, generate);
+      inject(id, ctx.request);
+      return next(ctx);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  contextIdPlugin
+});
+//# sourceMappingURL=context-id.cjs.map

package/dist/plugins/context-id.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugins/context-id.ts"],"sourcesContent":["import type { ClientPlugin } from '../plugins.js'\n\nconst CONTEXT_ID_STATE_KEY = '__contextId'\n\nexport type ContextIdPluginOptions = {\n  generate?: () => string\n  inject?: (id: string, request: Request) => void\n  order?: number\n}\n\nfunction defaultGenerateContextId(): string {\n  if (\n    typeof crypto !== 'undefined' &&\n    typeof crypto.randomUUID === 'function'\n  ) {\n    return crypto.randomUUID()\n  }\n\n  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`\n}\n\nfunction defaultInjectContextId(id: string, request: Request): void {\n  request.headers.set('x-context-id', id)\n}\n\nfunction resolveContextId(\n  ctx: Parameters<NonNullable<ClientPlugin['preRequest']>>[0],\n  generate: () => string\n): string {\n  const existing = ctx.request.headers.get('x-context-id')\n  if (existing) {\n    ctx.state[CONTEXT_ID_STATE_KEY] = existing\n    return existing\n  }\n\n  const fromState = ctx.state[CONTEXT_ID_STATE_KEY]\n  if (typeof fromState === 'string' && fromState.length > 0) {\n    return fromState\n  }\n\n  const generated = generate()\n  ctx.state[CONTEXT_ID_STATE_KEY] = generated\n  return generated\n}\n\nexport function contextIdPlugin(\n  options: ContextIdPluginOptions = {}\n): ClientPlugin {\n  const {\n    generate = defaultGenerateContextId,\n    inject = defaultInjectContextId,\n    order = 1,\n  } = options\n\n  return {\n    name: 'context-id',\n    order,\n    preRequest: (ctx) => {\n      const id = resolveContextId(ctx, generate)\n      inject(id, ctx.request)\n    },\n    wrapDispatch: (next) => async (ctx) => {\n      const id = resolveContextId(ctx, generate)\n      inject(id, ctx.request)\n      return next(ctx)\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,IAAM,uBAAuB;AAQ7B,SAAS,2BAAmC;AAC1C,MACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,YAC7B;AACA,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO,GAAG,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AAC1E;AAEA,SAAS,uBAAuB,IAAY,SAAwB;AAClE,UAAQ,QAAQ,IAAI,gBAAgB,EAAE;AACxC;AAEA,SAAS,iBACP,KACA,UACQ;AACR,QAAM,WAAW,IAAI,QAAQ,QAAQ,IAAI,cAAc;AACvD,MAAI,UAAU;AACZ,QAAI,MAAM,oBAAoB,IAAI;AAClC,WAAO;AAAA,EACT;AAEA,QAAM,YAAY,IAAI,MAAM,oBAAoB;AAChD,MAAI,OAAO,cAAc,YAAY,UAAU,SAAS,GAAG;AACzD,WAAO;AAAA,EACT;AAEA,QAAM,YAAY,SAAS;AAC3B,MAAI,MAAM,oBAAoB,IAAI;AAClC,SAAO;AACT;AAEO,SAAS,gBACd,UAAkC,CAAC,GACrB;AACd,QAAM;AAAA,IACJ,WAAW;AAAA,IACX,SAAS;AAAA,IACT,QAAQ;AAAA,EACV,IAAI;AAEJ,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IACA,YAAY,CAAC,QAAQ;AACnB,YAAM,KAAK,iBAAiB,KAAK,QAAQ;AACzC,aAAO,IAAI,IAAI,OAAO;AAAA,IACxB;AAAA,IACA,cAAc,CAAC,SAAS,OAAO,QAAQ;AACrC,YAAM,KAAK,iBAAiB,KAAK,QAAQ;AACzC,aAAO,IAAI,IAAI,OAAO;AACtB,aAAO,KAAK,GAAG;AAAA,IACjB;AAAA,EACF;AACF;","names":[]}

package/dist/plugins/context-id.d.cts

@@ -0,0 +1,10 @@
+import { C as ClientPlugin } from '../plugins-DqBQVM4I.cjs';
+
+type ContextIdPluginOptions = {
+    generate?: () => string;
+    inject?: (id: string, request: Request) => void;
+    order?: number;
+};
+declare function contextIdPlugin(options?: ContextIdPluginOptions): ClientPlugin;
+
+export { type ContextIdPluginOptions, contextIdPlugin };

package/dist/plugins/context-id.d.ts

@@ -0,0 +1,10 @@
+import { C as ClientPlugin } from '../plugins-DqBQVM4I.js';
+
+type ContextIdPluginOptions = {
+    generate?: () => string;
+    inject?: (id: string, request: Request) => void;
+    order?: number;
+};
+declare function contextIdPlugin(options?: ContextIdPluginOptions): ClientPlugin;
+
+export { type ContextIdPluginOptions, contextIdPlugin };

package/dist/plugins/context-id.js

@@ -0,0 +1,49 @@
+// src/plugins/context-id.ts
+var CONTEXT_ID_STATE_KEY = "__contextId";
+function defaultGenerateContextId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function defaultInjectContextId(id, request) {
+  request.headers.set("x-context-id", id);
+}
+function resolveContextId(ctx, generate) {
+  const existing = ctx.request.headers.get("x-context-id");
+  if (existing) {
+    ctx.state[CONTEXT_ID_STATE_KEY] = existing;
+    return existing;
+  }
+  const fromState = ctx.state[CONTEXT_ID_STATE_KEY];
+  if (typeof fromState === "string" && fromState.length > 0) {
+    return fromState;
+  }
+  const generated = generate();
+  ctx.state[CONTEXT_ID_STATE_KEY] = generated;
+  return generated;
+}
+function contextIdPlugin(options = {}) {
+  const {
+    generate = defaultGenerateContextId,
+    inject = defaultInjectContextId,
+    order = 1
+  } = options;
+  return {
+    name: "context-id",
+    order,
+    preRequest: (ctx) => {
+      const id = resolveContextId(ctx, generate);
+      inject(id, ctx.request);
+    },
+    wrapDispatch: (next) => async (ctx) => {
+      const id = resolveContextId(ctx, generate);
+      inject(id, ctx.request);
+      return next(ctx);
+    }
+  };
+}
+export {
+  contextIdPlugin
+};
+//# sourceMappingURL=context-id.js.map

package/dist/plugins/context-id.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/plugins/context-id.ts"],"sourcesContent":["import type { ClientPlugin } from '../plugins.js'\n\nconst CONTEXT_ID_STATE_KEY = '__contextId'\n\nexport type ContextIdPluginOptions = {\n  generate?: () => string\n  inject?: (id: string, request: Request) => void\n  order?: number\n}\n\nfunction defaultGenerateContextId(): string {\n  if (\n    typeof crypto !== 'undefined' &&\n    typeof crypto.randomUUID === 'function'\n  ) {\n    return crypto.randomUUID()\n  }\n\n  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`\n}\n\nfunction defaultInjectContextId(id: string, request: Request): void {\n  request.headers.set('x-context-id', id)\n}\n\nfunction resolveContextId(\n  ctx: Parameters<NonNullable<ClientPlugin['preRequest']>>[0],\n  generate: () => string\n): string {\n  const existing = ctx.request.headers.get('x-context-id')\n  if (existing) {\n    ctx.state[CONTEXT_ID_STATE_KEY] = existing\n    return existing\n  }\n\n  const fromState = ctx.state[CONTEXT_ID_STATE_KEY]\n  if (typeof fromState === 'string' && fromState.length > 0) {\n    return fromState\n  }\n\n  const generated = generate()\n  ctx.state[CONTEXT_ID_STATE_KEY] = generated\n  return generated\n}\n\nexport function contextIdPlugin(\n  options: ContextIdPluginOptions = {}\n): ClientPlugin {\n  const {\n    generate = defaultGenerateContextId,\n    inject = defaultInjectContextId,\n    order = 1,\n  } = options\n\n  return {\n    name: 'context-id',\n    order,\n    preRequest: (ctx) => {\n      const id = resolveContextId(ctx, generate)\n      inject(id, ctx.request)\n    },\n    wrapDispatch: (next) => async (ctx) => {\n      const id = resolveContextId(ctx, generate)\n      inject(id, ctx.request)\n      return next(ctx)\n    },\n  }\n}\n"],"mappings":";AAEA,IAAM,uBAAuB;AAQ7B,SAAS,2BAAmC;AAC1C,MACE,OAAO,WAAW,eAClB,OAAO,OAAO,eAAe,YAC7B;AACA,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO,GAAG,KAAK,IAAI,EAAE,SAAS,EAAE,CAAC,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AAC1E;AAEA,SAAS,uBAAuB,IAAY,SAAwB;AAClE,UAAQ,QAAQ,IAAI,gBAAgB,EAAE;AACxC;AAEA,SAAS,iBACP,KACA,UACQ;AACR,QAAM,WAAW,IAAI,QAAQ,QAAQ,IAAI,cAAc;AACvD,MAAI,UAAU;AACZ,QAAI,MAAM,oBAAoB,IAAI;AAClC,WAAO;AAAA,EACT;AAEA,QAAM,YAAY,IAAI,MAAM,oBAAoB;AAChD,MAAI,OAAO,cAAc,YAAY,UAAU,SAAS,GAAG;AACzD,WAAO;AAAA,EACT;AAEA,QAAM,YAAY,SAAS;AAC3B,MAAI,MAAM,oBAAoB,IAAI;AAClC,SAAO;AACT;AAEO,SAAS,gBACd,UAAkC,CAAC,GACrB;AACd,QAAM;AAAA,IACJ,WAAW;AAAA,IACX,SAAS;AAAA,IACT,QAAQ;AAAA,EACV,IAAI;AAEJ,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IACA,YAAY,CAAC,QAAQ;AACnB,YAAM,KAAK,iBAAiB,KAAK,QAAQ;AACzC,aAAO,IAAI,IAAI,OAAO;AAAA,IACxB;AAAA,IACA,cAAc,CAAC,SAAS,OAAO,QAAQ;AACrC,YAAM,KAAK,iBAAiB,KAAK,QAAQ;AACzC,aAAO,IAAI,IAAI,OAAO;AACtB,aAAO,KAAK,GAAG;AAAA,IACjB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fetchkit/ffetch",
-  "version": "5.3.0",
+  "version": "5.4.1",
   "description": "Fetch wrapper with configurable timeouts, retries, and TypeScript-first DX",
   "keywords": [
     "fetch",
@@ -61,6 +61,11 @@
       "types": "./dist/plugins/download-progress.d.ts",
       "import": "./dist/plugins/download-progress.js",
       "require": "./dist/plugins/download-progress.cjs"
+    },
+    "./plugins/context-id": {
+      "types": "./dist/plugins/context-id.d.ts",
+      "import": "./dist/plugins/context-id.js",
+      "require": "./dist/plugins/context-id.cjs"
     }
   },
   "files": [