@flow-conductor/adapter-axios 1.0.0

package/README.md

@@ -0,0 +1,527 @@
+# @flow-conductor/adapter-axios
+
+Axios adapter for flow-conductor. This adapter uses Axios for making HTTP requests, providing features like request/response interceptors, automatic JSON parsing, and better error handling.
+
+## Installation
+
+```bash
+npm install @flow-conductor/adapter-axios @flow-conductor/core axios
+```
+
+**Note**: Both `@flow-conductor/core` and `axios` are peer dependencies and must be installed alongside this package.
+
+## Quick Start
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+console.log(result.data); // Axios automatically parses JSON
+console.log(result.status); // HTTP status code
+console.log(result.headers); // Response headers
+```
+
+## Usage
+
+### Basic GET Request
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+const user = result.data; // Already parsed JSON
+console.log(user);
+```
+
+### POST Request with Data
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: {
+        name: "John Doe",
+        email: "john@example.com",
+      },
+    },
+  },
+  adapter
+).execute();
+
+const newUser = result.data;
+console.log(newUser);
+```
+
+### Request with Custom Headers
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      headers: {
+        Authorization: "Bearer your-token-here",
+        "X-Custom-Header": "value",
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+### Chained Requests
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+)
+  .next({
+    config: (previousResult) => {
+      const user = previousResult.data;
+      return {
+        url: `https://api.example.com/users/${user.id}/posts`,
+        method: "GET",
+      };
+    },
+  })
+  .execute();
+
+const posts = result.data;
+console.log(posts);
+```
+
+## Configuration
+
+The `AxiosRequestAdapter` accepts `IRequestConfig` objects and extends them with Axios-specific options. The adapter automatically:
+
+- Parses JSON responses (available in `result.data`)
+- Handles request data serialization
+- Supports all Axios configuration options
+
+### Request Config Interface
+
+```typescript
+interface AxiosRequestConfigType extends IRequestConfig {
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+  data?: any; // Automatically serialized by Axios
+  headers?: Record<string, string>;
+  // ... other Axios options (params, timeout, auth, etc.)
+}
+```
+
+### Supported Axios Options
+
+All standard Axios configuration options are supported:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      headers: {
+        Authorization: "Bearer token",
+      },
+      params: {
+        page: 1,
+        limit: 10,
+      },
+      timeout: 5000,
+      auth: {
+        username: "user",
+        password: "pass",
+      },
+      // ... any other AxiosRequestConfig options
+    },
+  },
+  adapter
+).execute();
+```
+
+### Query Parameters
+
+Axios handles query parameters separately from the URL:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      params: {
+        page: 1,
+        limit: 10,
+        sort: "name",
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+### Data Handling
+
+Axios automatically handles data serialization:
+
+- **Objects**: Automatically JSON stringified
+- **FormData**: Sent as multipart/form-data
+- **URLSearchParams**: Sent as application/x-www-form-urlencoded
+- **Strings**: Sent as-is
+
+```typescript
+// POST with JSON data
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "POST",
+      data: { name: "John", email: "john@example.com" },
+      // Content-Type: application/json is automatically set
+    },
+  },
+  adapter
+).execute();
+
+// POST with FormData
+const formData = new FormData();
+formData.append("file", fileBlob);
+
+const uploadResult = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: formData,
+      // Content-Type: multipart/form-data is automatically set
+    },
+  },
+  adapter
+).execute();
+```
+
+### Custom Axios Instance
+
+You can create a custom Axios instance with default configuration:
+
+```typescript
+import axios from "axios";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+// Create a custom axios instance
+const axiosInstance = axios.create({
+  baseURL: "https://api.example.com",
+  timeout: 5000,
+  headers: {
+    "X-Custom-Header": "value",
+  },
+});
+
+// Note: The adapter uses the default axios instance
+// For custom instances, you may need to extend the adapter
+```
+
+## Response Handling
+
+The adapter returns an `AxiosResponse` object with the following properties:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// Response properties
+console.log(result.data); // Response data (automatically parsed JSON)
+console.log(result.status); // HTTP status code
+console.log(result.statusText); // HTTP status text
+console.log(result.headers); // Response headers
+console.log(result.config); // Request configuration
+```
+
+### Automatic JSON Parsing
+
+Unlike the Fetch API, Axios automatically parses JSON responses:
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users/1",
+      method: "GET",
+    },
+  },
+  adapter
+).execute();
+
+// No need to call .json() - data is already parsed
+const user = result.data; // Already a JavaScript object
+console.log(user.name);
+```
+
+## Error Handling
+
+Axios throws errors for HTTP error statuses (4xx, 5xx), making error handling more straightforward:
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+import { AxiosError } from "axios";
+
+const adapter = new AxiosRequestAdapter();
+
+try {
+  const result = await begin(
+    {
+      config: {
+        url: "https://api.example.com/users",
+        method: "GET",
+      },
+    },
+    adapter
+  )
+    .withErrorHandler((error) => {
+      if (error instanceof AxiosError) {
+        console.error("Request failed:", error.message);
+        console.error("Status:", error.response?.status);
+        console.error("Data:", error.response?.data);
+      }
+    })
+    .execute();
+
+  const data = result.data;
+  console.log(data);
+} catch (error) {
+  if (error instanceof AxiosError) {
+    // Handle Axios-specific errors
+    console.error("Axios error:", error.response?.data);
+  } else {
+    console.error("Error:", error);
+  }
+}
+```
+
+### Error Response Access
+
+Axios provides detailed error information:
+
+```typescript
+try {
+  await begin(
+    {
+      config: {
+        url: "https://api.example.com/users",
+        method: "GET",
+      },
+    },
+    adapter
+  ).execute();
+} catch (error) {
+  if (error instanceof AxiosError) {
+    if (error.response) {
+      // Server responded with error status
+      console.error("Status:", error.response.status);
+      console.error("Data:", error.response.data);
+      console.error("Headers:", error.response.headers);
+    } else if (error.request) {
+      // Request made but no response received
+      console.error("No response:", error.request);
+    } else {
+      // Error setting up request
+      console.error("Error:", error.message);
+    }
+  }
+}
+```
+
+## Examples
+
+### Authentication Flow
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+// Login and use token
+const userData = await begin(
+  {
+    config: {
+      url: "https://api.example.com/auth/login",
+      method: "POST",
+      data: { username: "user", password: "pass" },
+    },
+  },
+  adapter
+)
+  .next({
+    config: (previousResult) => {
+      const auth = previousResult.data;
+      return {
+        url: "https://api.example.com/user/profile",
+        method: "GET",
+        headers: { Authorization: `Bearer ${auth.token}` },
+      };
+    },
+  })
+  .execute();
+
+const profile = userData.data;
+console.log(profile);
+```
+
+### File Upload
+
+```typescript
+import { begin } from "@flow-conductor/core";
+import { AxiosRequestAdapter } from "@flow-conductor/adapter-axios";
+
+const adapter = new AxiosRequestAdapter();
+
+const formData = new FormData();
+formData.append("file", fileBlob);
+formData.append("name", "document.pdf");
+
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/upload",
+      method: "POST",
+      data: formData,
+      headers: {
+        "Content-Type": "multipart/form-data",
+      },
+    },
+  },
+  adapter
+).execute();
+
+console.log(result.data);
+```
+
+### Request with Timeout
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      timeout: 5000, // 5 seconds
+    },
+  },
+  adapter
+).execute();
+```
+
+### Request with Authentication
+
+```typescript
+const result = await begin(
+  {
+    config: {
+      url: "https://api.example.com/users",
+      method: "GET",
+      auth: {
+        username: "user",
+        password: "pass",
+      },
+    },
+  },
+  adapter
+).execute();
+```
+
+## API Reference
+
+### AxiosRequestAdapter
+
+```typescript
+class AxiosRequestAdapter extends RequestAdapter<AxiosResponse, AxiosRequestConfigType> {
+  createRequest(requestConfig: AxiosRequestConfigType): Promise<AxiosResponse>;
+}
+```
+
+### AxiosRequestConfigType
+
+```typescript
+type AxiosRequestConfigType = IRequestConfig & Partial<AxiosRequestConfig>;
+```
+
+Extends `IRequestConfig` with all Axios configuration options.
+
+## Advantages over Fetch Adapter
+
+- **Automatic JSON parsing**: No need to call `.json()` on responses
+- **Better error handling**: Throws errors for HTTP error statuses
+- **Request/Response interceptors**: Can be configured globally
+- **Request cancellation**: Built-in support for canceling requests
+- **Automatic request body serialization**: Handles FormData, URLSearchParams, etc.
+- **Request/Response transformation**: Built-in support for transforming data
+- **Progress tracking**: Support for upload/download progress
+
+## Requirements
+
+- `@flow-conductor/core` (peer dependency)
+- `axios` ^1.0.0 (peer dependency)
+- Node.js 18+
+- TypeScript 5.0+
+
+## License
+
+MIT
+

package/build/index.d.ts

@@ -0,0 +1,39 @@
+import { RequestAdapter, IRequestConfig, UrlValidationOptions } from '@flow-conductor/core';
+import { AxiosResponse, AxiosRequestConfig } from 'axios';
+
+/**
+ * Extended request configuration type that combines IRequestConfig with Axios-specific options.
+ * Allows using all Axios configuration options while maintaining compatibility with flow-conductor.
+ */
+type AxiosRequestConfigType = IRequestConfig & Partial<AxiosRequestConfig>;
+/**
+ * Request adapter implementation using Axios as the underlying HTTP client.
+ * Provides seamless integration between flow-conductor and Axios.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new AxiosRequestAdapter();
+ * const chain = begin(
+ *   { config: { url: 'https://api.example.com/users', method: 'GET' } },
+ *   adapter
+ * );
+ * ```
+ */
+declare class AxiosRequestAdapter extends RequestAdapter<AxiosResponse, AxiosRequestConfigType> {
+    /**
+     * Creates a new AxiosRequestAdapter instance.
+     *
+     * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+     */
+    constructor(urlValidationOptions?: UrlValidationOptions);
+    /**
+     * Creates and executes an HTTP request using Axios.
+     * Converts flow-conductor request configuration to Axios format.
+     *
+     * @param requestConfig - The request configuration object
+     * @returns A promise that resolves to an AxiosResponse
+     */
+    createRequest(requestConfig: AxiosRequestConfigType): Promise<AxiosResponse>;
+}
+
+export { type AxiosRequestConfigType, AxiosRequestAdapter as default };

package/build/index.js

@@ -0,0 +1,35 @@
+import { RequestAdapter } from '@flow-conductor/core';
+import axios from 'axios';
+
+// src/axios-request-adapter.ts
+var AxiosRequestAdapter = class extends RequestAdapter {
+  /**
+   * Creates a new AxiosRequestAdapter instance.
+   *
+   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks
+   */
+  constructor(urlValidationOptions) {
+    super(urlValidationOptions);
+  }
+  /**
+   * Creates and executes an HTTP request using Axios.
+   * Converts flow-conductor request configuration to Axios format.
+   *
+   * @param requestConfig - The request configuration object
+   * @returns A promise that resolves to an AxiosResponse
+   */
+  async createRequest(requestConfig) {
+    const { url, method, data, ...rest } = requestConfig;
+    const axiosConfig = {
+      url,
+      method: method.toLowerCase(),
+      data,
+      ...rest
+    };
+    return axios(axiosConfig);
+  }
+};
+
+export { AxiosRequestAdapter as default };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/axios-request-adapter.ts"],"names":[],"mappings":";;;;AA2BA,IAAqB,mBAAA,GAArB,cAAiD,cAAA,CAG/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,oBAAA,EAA6C;AACvD,IAAA,KAAA,CAAM,oBAAoB,CAAA;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAAa,cACX,aAAA,EACwB;AACxB,IAAA,MAAM,EAAE,GAAA,EAAK,MAAA,EAAQ,IAAA,EAAM,GAAG,MAAK,GAAI,aAAA;AAEvC,IAAA,MAAM,WAAA,GAAkC;AAAA,MACtC,GAAA;AAAA,MACA,MAAA,EAAQ,OAAO,WAAA,EAAY;AAAA,MAC3B,IAAA;AAAA,MACA,GAAG;AAAA,KACL;AAEA,IAAA,OAAO,MAAM,WAAW,CAAA;AAAA,EAC1B;AACF","file":"index.js","sourcesContent":["import { RequestAdapter } from \"@flow-conductor/core\";\nimport type {\n  IRequestConfig,\n  UrlValidationOptions,\n} from \"@flow-conductor/core\";\nimport axios, { type AxiosRequestConfig, type AxiosResponse } from \"axios\";\n\n/**\n * Extended request configuration type that combines IRequestConfig with Axios-specific options.\n * Allows using all Axios configuration options while maintaining compatibility with flow-conductor.\n */\nexport type AxiosRequestConfigType = IRequestConfig &\n  Partial<AxiosRequestConfig>;\n\n/**\n * Request adapter implementation using Axios as the underlying HTTP client.\n * Provides seamless integration between flow-conductor and Axios.\n *\n * @example\n * ```typescript\n * const adapter = new AxiosRequestAdapter();\n * const chain = begin(\n *   { config: { url: 'https://api.example.com/users', method: 'GET' } },\n *   adapter\n * );\n * ```\n */\nexport default class AxiosRequestAdapter extends RequestAdapter<\n  AxiosResponse,\n  AxiosRequestConfigType\n> {\n  /**\n   * Creates a new AxiosRequestAdapter instance.\n   *\n   * @param urlValidationOptions - Optional URL validation options to prevent SSRF attacks\n   */\n  constructor(urlValidationOptions?: UrlValidationOptions) {\n    super(urlValidationOptions);\n  }\n\n  /**\n   * Creates and executes an HTTP request using Axios.\n   * Converts flow-conductor request configuration to Axios format.\n   *\n   * @param requestConfig - The request configuration object\n   * @returns A promise that resolves to an AxiosResponse\n   */\n  public async createRequest(\n    requestConfig: AxiosRequestConfigType\n  ): Promise<AxiosResponse> {\n    const { url, method, data, ...rest } = requestConfig;\n\n    const axiosConfig: AxiosRequestConfig = {\n      url,\n      method: method.toLowerCase() as AxiosRequestConfig[\"method\"],\n      data,\n      ...rest,\n    };\n\n    return axios(axiosConfig);\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@flow-conductor/adapter-axios",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Axios adapter for flow-conductor",
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js"
+    }
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "build/**/*.js.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "flow-conductor",
+    "request",
+    "adapter",
+    "axios",
+    "http",
+    "typescript"
+  ],
+  "scripts": {
+    "test": "node --test --import tsx/esm 'src/__test__/**/*.test.ts'",
+    "test:watch": "node --test --import tsx/esm --watch 'src/__test__/**/*.test.ts'",
+    "build": "tsup",
+    "clean": "rm -rf build",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run lint && npm run type-check && npm run build"
+  },
+  "author": "Dawid Hermann",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dawidhermann/flow-conductor.git",
+    "directory": "packages/adapter-axios"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@flow-conductor/core": "^1.0.0",
+    "axios": "^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@flow-conductor/core": "*",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "axios": "^1.7.9",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "^3.7.4",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
+  }
+}