@backendkit-labs/http-client 0.1.0

package/dist/nestjs/index.js

@@ -0,0 +1,76 @@
+import { __decorateClass, HttpClient } from '../chunk-5RHNUUOY.js';
+import { Module, Inject } from '@nestjs/common';
+
+var HTTP_CLIENT_MODULE_OPTIONS = "HTTP_CLIENT_MODULE_OPTIONS";
+var HttpClientModule = class {
+  static forRoot(options) {
+    const providers = options.clients.map(
+      ({ token, config }) => HttpClientModule._clientProvider(token, config)
+    );
+    return {
+      module: HttpClientModule,
+      providers,
+      exports: providers,
+      global: true
+    };
+  }
+  static forRootAsync(options) {
+    const asyncProvider = HttpClientModule._asyncOptionsProvider(options);
+    const clientsProvider = {
+      provide: "HTTP_CLIENT_INSTANCES",
+      useFactory: (opts) => {
+        return opts.clients.map(({ token, config }) => ({
+          token,
+          instance: new HttpClient(config)
+        }));
+      },
+      inject: [HTTP_CLIENT_MODULE_OPTIONS]
+    };
+    const allProviders = [
+      asyncProvider,
+      clientsProvider
+    ];
+    return {
+      module: HttpClientModule,
+      imports: options.imports ?? [],
+      providers: allProviders,
+      exports: allProviders,
+      global: true
+    };
+  }
+  static _clientProvider(token, config) {
+    return {
+      provide: token.symbol,
+      useFactory: () => new HttpClient(config)
+    };
+  }
+  static _asyncOptionsProvider(options) {
+    if (options.useFactory) {
+      return {
+        provide: HTTP_CLIENT_MODULE_OPTIONS,
+        useFactory: options.useFactory,
+        inject: options.inject ?? []
+      };
+    }
+    const cls = options.useExisting ?? options.useClass;
+    if (cls) {
+      return {
+        provide: HTTP_CLIENT_MODULE_OPTIONS,
+        useFactory: (factory) => factory.createHttpClientOptions(),
+        inject: [cls]
+      };
+    }
+    return {
+      provide: HTTP_CLIENT_MODULE_OPTIONS,
+      useValue: { clients: [] }
+    };
+  }
+};
+HttpClientModule = __decorateClass([
+  Module({})
+], HttpClientModule);
+var InjectHttpClient = (token) => Inject(token.symbol);
+
+export { HttpClientModule, InjectHttpClient };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/nestjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/nestjs/http-client.module.ts","../../src/nestjs/http-client.decorator.ts"],"names":[],"mappings":";;;AAUA,IAAM,0BAAA,GAA6B,4BAAA;AAG5B,IAAM,mBAAN,MAAuB;AAAA,EAC5B,OAAO,QAAQ,OAAA,EAAiD;AAC9D,IAAA,MAAM,SAAA,GAAwB,QAAQ,OAAA,CAAQ,GAAA;AAAA,MAAI,CAAC,EAAE,KAAA,EAAO,MAAA,OAC1D,gBAAA,CAAiB,eAAA,CAAgB,OAAO,MAAM;AAAA,KAChD;AAEA,IAAA,OAAO;AAAA,MACL,MAAA,EAAU,gBAAA;AAAA,MACV,SAAA;AAAA,MACA,OAAA,EAAU,SAAA;AAAA,MACV,MAAA,EAAU;AAAA,KACZ;AAAA,EACF;AAAA,EAEA,OAAO,aAAa,OAAA,EAAsD;AACxE,IAAA,MAAM,aAAA,GAAgB,gBAAA,CAAiB,qBAAA,CAAsB,OAAO,CAAA;AAEpE,IAAA,MAAM,eAAA,GAA4B;AAAA,MAChC,OAAA,EAAY,uBAAA;AAAA,MACZ,UAAA,EAAY,CAAC,IAAA,KAAkC;AAC7C,QAAA,OAAO,KAAK,OAAA,CAAQ,GAAA,CAAI,CAAC,EAAE,KAAA,EAAO,QAAO,MAAO;AAAA,UAC9C,KAAA;AAAA,UACA,QAAA,EAAU,IAAI,UAAA,CAAW,MAAM;AAAA,SACjC,CAAE,CAAA;AAAA,MACJ,CAAA;AAAA,MACA,MAAA,EAAQ,CAAC,0BAA0B;AAAA,KACrC;AAEA,IAAA,MAAM,YAAA,GAA2B;AAAA,MAC/B,aAAA;AAAA,MACA;AAAA,KACF;AAEA,IAAA,OAAO;AAAA,MACL,MAAA,EAAU,gBAAA;AAAA,MACV,OAAA,EAAU,OAAA,CAAQ,OAAA,IAAW,EAAC;AAAA,MAC9B,SAAA,EAAW,YAAA;AAAA,MACX,OAAA,EAAU,YAAA;AAAA,MACV,MAAA,EAAU;AAAA,KACZ;AAAA,EACF;AAAA,EAEA,OAAe,eAAA,CAAgB,KAAA,EAAwB,MAAA,EAAoC;AACzF,IAAA,OAAO;AAAA,MACL,SAAY,KAAA,CAAM,MAAA;AAAA,MAClB,UAAA,EAAY,MAAM,IAAI,UAAA,CAAW,MAAM;AAAA,KACzC;AAAA,EACF;AAAA,EAEA,OAAe,sBAAsB,OAAA,EAAiD;AACpF,IAAA,IAAI,QAAQ,UAAA,EAAY;AACtB,MAAA,OAAO;AAAA,QACL,OAAA,EAAY,0BAAA;AAAA,QACZ,YAAY,OAAA,CAAQ,UAAA;AAAA,QACpB,MAAA,EAAa,OAAA,CAAQ,MAAA,IAAU;AAAC,OAClC;AAAA,IACF;AAEA,IAAA,MAAM,GAAA,GAAM,OAAA,CAAQ,WAAA,IAAe,OAAA,CAAQ,QAAA;AAC3C,IAAA,IAAI,GAAA,EAAK;AACP,MAAA,OAAO;AAAA,QACL,OAAA,EAAY,0BAAA;AAAA,QACZ,UAAA,EAAY,CAAC,OAAA,KAAsC,OAAA,CAAQ,uBAAA,EAAwB;AAAA,QACnF,MAAA,EAAY,CAAC,GAAqC;AAAA,OACpD;AAAA,IACF;AAEA,IAAA,OAAO;AAAA,MACL,OAAA,EAAU,0BAAA;AAAA,MACV,QAAA,EAAU,EAAE,OAAA,EAAS,EAAC;AAAE,KAC1B;AAAA,EACF;AACF;AAxEa,gBAAA,GAAN,eAAA,CAAA;AAAA,EADN,MAAA,CAAO,EAAE;AAAA,CAAA,EACG,gBAAA,CAAA;ACVN,IAAM,gBAAA,GAAmB,CAC9B,KAAA,KAC8B,MAAA,CAAO,MAAM,MAAM","file":"index.js","sourcesContent":["import { Module, DynamicModule, Provider } from '@nestjs/common';\nimport type { Type, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';\nimport { HttpClient } from '../core/http-client.js';\nimport type { HttpClientConfig, HttpClientToken } from '../core/types.js';\nimport type {\n  HttpClientModuleOptions,\n  HttpClientModuleAsyncOptions,\n  HttpClientOptionsFactory,\n} from './http-client.options.js';\n\nconst HTTP_CLIENT_MODULE_OPTIONS = 'HTTP_CLIENT_MODULE_OPTIONS';\n\n@Module({})\nexport class HttpClientModule {\n  static forRoot(options: HttpClientModuleOptions): DynamicModule {\n    const providers: Provider[] = options.clients.map(({ token, config }) =>\n      HttpClientModule._clientProvider(token, config),\n    );\n\n    return {\n      module:   HttpClientModule,\n      providers,\n      exports:  providers,\n      global:   true,\n    };\n  }\n\n  static forRootAsync(options: HttpClientModuleAsyncOptions): DynamicModule {\n    const asyncProvider = HttpClientModule._asyncOptionsProvider(options);\n\n    const clientsProvider: Provider = {\n      provide:    'HTTP_CLIENT_INSTANCES',\n      useFactory: (opts: HttpClientModuleOptions) => {\n        return opts.clients.map(({ token, config }) => ({\n          token,\n          instance: new HttpClient(config),\n        }));\n      },\n      inject: [HTTP_CLIENT_MODULE_OPTIONS],\n    };\n\n    const allProviders: Provider[] = [\n      asyncProvider,\n      clientsProvider,\n    ];\n\n    return {\n      module:   HttpClientModule,\n      imports:  options.imports ?? [],\n      providers: allProviders,\n      exports:  allProviders,\n      global:   true,\n    };\n  }\n\n  private static _clientProvider(token: HttpClientToken, config: HttpClientConfig): Provider {\n    return {\n      provide:    token.symbol,\n      useFactory: () => new HttpClient(config),\n    };\n  }\n\n  private static _asyncOptionsProvider(options: HttpClientModuleAsyncOptions): Provider {\n    if (options.useFactory) {\n      return {\n        provide:    HTTP_CLIENT_MODULE_OPTIONS,\n        useFactory: options.useFactory as (...args: unknown[]) => HttpClientModuleOptions | Promise<HttpClientModuleOptions>,\n        inject:     (options.inject ?? []) as (InjectionToken | OptionalFactoryDependency)[],\n      };\n    }\n\n    const cls = options.useExisting ?? options.useClass;\n    if (cls) {\n      return {\n        provide:    HTTP_CLIENT_MODULE_OPTIONS,\n        useFactory: (factory: HttpClientOptionsFactory) => factory.createHttpClientOptions(),\n        inject:     [cls as Type<HttpClientOptionsFactory>],\n      };\n    }\n\n    return {\n      provide:  HTTP_CLIENT_MODULE_OPTIONS,\n      useValue: { clients: [] } satisfies HttpClientModuleOptions,\n    };\n  }\n}\n","import { Inject } from '@nestjs/common';\nimport type { HttpClientToken } from '../core/types.js';\n\nexport const InjectHttpClient = (\n  token: HttpClientToken,\n): ReturnType<typeof Inject> => Inject(token.symbol);\n"]}

package/dist/types-x0zPV-KD.d.cts

@@ -0,0 +1,71 @@
+import { PipelineStep } from '@backendkit-labs/pipeline';
+import { CircuitBreakerOptions } from '@backendkit-labs/circuit-breaker';
+
+type HttpErrorType = 'http' | 'network' | 'cancelled' | 'circuit-open' | 'timeout';
+interface HttpClientError {
+    type: HttpErrorType;
+    message: string;
+    status?: number;
+    data?: unknown;
+    cause?: unknown;
+}
+interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+/** Mutable context passed through the pre-request pipeline steps. */
+interface HttpCtx {
+    url: string;
+    method: string;
+    data?: unknown;
+    headers: Record<string, string>;
+    params?: Record<string, unknown>;
+    timeout?: number;
+    cancelKey?: string;
+    correlationId?: string;
+}
+interface RequestConfig {
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+    timeout?: number;
+    /** Key used to identify and cancel this request programmatically. */
+    cancelKey?: string;
+    correlationId?: string;
+}
+interface RetryConfig {
+    /** Number of retry attempts after the first failure. */
+    attempts: number;
+    delayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    /** Return false to stop retrying on a specific error. */
+    shouldRetry?: (error: HttpClientError, attempt: number) => boolean;
+}
+interface HttpClientConfig {
+    baseURL?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    circuitBreaker?: CircuitBreakerOptions;
+    retry?: RetryConfig;
+    /** Pre-request pipeline steps. Receive and transform the HttpCtx before the call is made. */
+    steps?: PipelineStep<HttpCtx, HttpClientError>[];
+}
+interface HttpMetrics {
+    requests: number;
+    success: number;
+    failed: number;
+    cancelled: number;
+    circuitOpen: number;
+    retried: number;
+}
+/** Typed injection token for named HTTP clients. */
+declare class HttpClientToken {
+    readonly description: string;
+    readonly symbol: symbol;
+    readonly _phantom: never;
+    constructor(name: string);
+}
+declare function defineHttpClient(name: string): HttpClientToken;
+
+export { type HttpClientConfig as H, type RequestConfig as R, type HttpResponse as a, type HttpClientError as b, type HttpMetrics as c, HttpClientToken as d, type HttpCtx as e, type HttpErrorType as f, type RetryConfig as g, defineHttpClient as h };

package/dist/types-x0zPV-KD.d.ts

@@ -0,0 +1,71 @@
+import { PipelineStep } from '@backendkit-labs/pipeline';
+import { CircuitBreakerOptions } from '@backendkit-labs/circuit-breaker';
+
+type HttpErrorType = 'http' | 'network' | 'cancelled' | 'circuit-open' | 'timeout';
+interface HttpClientError {
+    type: HttpErrorType;
+    message: string;
+    status?: number;
+    data?: unknown;
+    cause?: unknown;
+}
+interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+/** Mutable context passed through the pre-request pipeline steps. */
+interface HttpCtx {
+    url: string;
+    method: string;
+    data?: unknown;
+    headers: Record<string, string>;
+    params?: Record<string, unknown>;
+    timeout?: number;
+    cancelKey?: string;
+    correlationId?: string;
+}
+interface RequestConfig {
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+    timeout?: number;
+    /** Key used to identify and cancel this request programmatically. */
+    cancelKey?: string;
+    correlationId?: string;
+}
+interface RetryConfig {
+    /** Number of retry attempts after the first failure. */
+    attempts: number;
+    delayMs?: number;
+    maxDelayMs?: number;
+    jitter?: boolean;
+    /** Return false to stop retrying on a specific error. */
+    shouldRetry?: (error: HttpClientError, attempt: number) => boolean;
+}
+interface HttpClientConfig {
+    baseURL?: string;
+    timeout?: number;
+    headers?: Record<string, string>;
+    circuitBreaker?: CircuitBreakerOptions;
+    retry?: RetryConfig;
+    /** Pre-request pipeline steps. Receive and transform the HttpCtx before the call is made. */
+    steps?: PipelineStep<HttpCtx, HttpClientError>[];
+}
+interface HttpMetrics {
+    requests: number;
+    success: number;
+    failed: number;
+    cancelled: number;
+    circuitOpen: number;
+    retried: number;
+}
+/** Typed injection token for named HTTP clients. */
+declare class HttpClientToken {
+    readonly description: string;
+    readonly symbol: symbol;
+    readonly _phantom: never;
+    constructor(name: string);
+}
+declare function defineHttpClient(name: string): HttpClientToken;
+
+export { type HttpClientConfig as H, type RequestConfig as R, type HttpResponse as a, type HttpClientError as b, type HttpMetrics as c, HttpClientToken as d, type HttpCtx as e, type HttpErrorType as f, type RetryConfig as g, defineHttpClient as h };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@backendkit-labs/http-client",
+  "version": "0.1.0",
+  "description": "Production-grade HTTP client for Node.js — built on axios with circuit breaker, retry with backoff, request cancellation, typed Result responses, pipeline middleware, and optional NestJS integration",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types":   "./dist/index.d.ts",
+      "import":  "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./nestjs": {
+      "types":   "./dist/nestjs/index.d.ts",
+      "import":  "./dist/nestjs/index.js",
+      "require": "./dist/nestjs/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build":          "tsup",
+    "dev":            "tsup --watch",
+    "test":           "vitest run",
+    "test:watch":     "vitest",
+    "test:coverage":  "vitest run --coverage",
+    "typecheck":      "tsc --noEmit",
+    "lint":           "eslint src/",
+    "prepublishOnly": "npm run build && npm run test && npm run lint"
+  },
+  "keywords": [
+    "http", "axios", "circuit-breaker", "retry", "result",
+    "pipeline", "cancel", "nestjs", "node", "typescript"
+  ],
+  "author": "Mairon José Cuello Martínez",
+  "license": "MIT",
+  "homepage": "https://github.com/backendkit-dev/backendkit-monorepo/tree/master/packages/http-client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backendkit-dev/backendkit-monorepo.git",
+    "directory": "packages/http-client"
+  },
+  "bugs": { "url": "https://github.com/backendkit-dev/backendkit-monorepo/issues" },
+  "publishConfig": { "access": "public" },
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@backendkit-labs/circuit-breaker": "*",
+    "@backendkit-labs/pipeline":        "*",
+    "@backendkit-labs/result":          "*"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core":   ">=10.0.0",
+    "axios":          ">=1.0.0",
+    "rxjs":           ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": { "optional": true },
+    "@nestjs/core":   { "optional": true },
+    "rxjs":           { "optional": true }
+  },
+  "devDependencies": {
+    "@eslint/js":        "^9.39.4",
+    "@nestjs/common":    "^10.0.0",
+    "@nestjs/core":      "^10.0.0",
+    "@types/node":       "^22.0.0",
+    "axios":             "^1.7.0",
+    "axios-mock-adapter": "^2.1.0",
+    "eslint":            "^9.0.0",
+    "reflect-metadata":  "^0.2.0",
+    "rxjs":              "^7.8.0",
+    "tsup":              "^8.0.0",
+    "typescript":        "^5.5.0",
+    "typescript-eslint": "^8.59.3",
+    "vitest":            "^2.0.0"
+  }
+}