Feat: Create / Add Axios Large Response Interceptor

.gitignore

@@ -24,6 +24,7 @@ yarn-error.log*
 .DS_Store
 *.pem
 test-report.xml
-**/lib/
+**/large-response-middleware/lib/
+**/dist/
 stats.html
 *.tgz

.vscode/settings.json

@@ -1,7 +1,8 @@
 {
   "editor.defaultFormatter": "biomejs.biome",
   "editor.codeActionsOnSave": {
-    "source.organizeImports": "always"
+    "source.organizeImports": "always",
+    "source.fixAll": "always"
   },
   "[json]": {
     "editor.defaultFormatter": "biomejs.biome"

README.md

@@ -9,7 +9,9 @@ This repository is designed to host a collection of useful AWS Lambda Utilities
 
 ## Middlewares
 
-- [Large Response Middleware](./packages/large-response-middleware/): AWS Lambda has a known limitation regarding the payload size of responses, which is currently set at 6MB. This middleware allows a service to log and save large responses to an S3 bucket, enabling developers to investigate the causes of such large responses. Furthermore, this middleware accepts a special header that allows the rewriting of the response with a $ref pointing to the large payload stored in S3, enabling clients to recover gracefully.
+- [Large Response Middleware](./packages/large-response-middleware/): AWS Lambda has a known limitation regarding the payload size of responses, which is currently set at 6MB. This middleware allows a service to log and save large responses to an S3 bucket, enabling developers to investigate the causes of such large responses. Furthermore, this middleware accepts a special header that allows the rewriting of the response with a $ref pointing to the large payload stored in S3, enabling clients to recover gracefully. 
+
+  - If you are using `axios` in the client, feel free to try our interceptor [Axios Large Response](./packages/axios-large-response/) allowing you to intercept large responses and easily fetch them from S3 with minimal effort.
 
 - [Lambda Server-Timing Middleware (ext)](https://github.com/NishuGoel/lambda-server-timing/tree/main/src): Enables Lambdas to return responses with Server-Timing Header allowing to to pass request-specific timings from the backend to the browser. Allows a server to communicate performance metrics about the request-response cycle to the user agent. It also standardizes a JavaScript interface to enable applications to collect, process, and act on these metrics to optimize application delivery.
 

packages/axios-large-response/README.md

@@ -0,0 +1,99 @@
+# Axios Large Response
+
+An Axios interceptor designed to handle large responses. By default, it assumes that your backend uses `@epilot/large-response-middleware`, as described in the [large-response-middleware README](https://github.com/epilot-dev/aws-lambda-utility-middlewares/blob/main/packages/large-response-middleware/README.md). However, it also supports custom callback function to fetch large payloads from a reference data, customizable reference property names, headers, and other options. See below for details.
+
+It supports per-request options, so you can enable/disable the interceptor for a specific request (the axios config namespace is `axios-large-response` - please check the [Usage](#usage) section for more details). For now, it is enabled by default, however we can do some combinations based on the use cases, for example, we can disable it globally and enable it per-request if needed.
+
+The interceptor is **disabled by default**, so you need to explicitly enable it.
+
+## Installation
+
+```bash
+pnpm add @epilot/axios-large-response
+npm install @epilot/axios-large-response
+yarn add @epilot/axios-large-response
+```
+
+## Usage
+
+```ts
+import { axiosLargeResponse } from '@epilot/axios-large-response';
+import axios from 'axios';
+
+// Axios instance
+const axiosInstance = axios.create();
+
+// Example 1: disable interceptor globally so we enable it per-request
+axiosLargeResponse(axiosInstance, {
+  // enabled: false, -> disabled by default
+  // ... other global options
+});
+...
+const response = await axiosInstance.get('https://api.example.com/data', {
+  'axios-large-response': {
+    enabled: true,
+    headerFlag: 'application/custom-large-response.vnd+json',
+    refProperty: '$customRef',
+    debug: true,
+    onFetchLargePayloadFromRef: async (refUrl) => {
+      // Custom handling for this specific request
+      const response = await axios.get(refUrl);
+      return response.data;
+    }
+  }
+});
+
+// Example 2: enable interceptor globally so we disable it per-request
+axiosLargeResponse(axiosInstance, {
+  enabled: true,
+  // ... other global options
+});
+...
+const response =  await axiosInstance.get('https://api.example.com/data', {
+  'axios-large-response': {
+    enabled: false
+  }
+});
+```
+
+## Options
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| enabled | Boolean | false | Enable/disable the interceptor |
+| headerFlag | String | 'application/large-response.vnd+json' | Content type header indicating a large payload reference response |
+| refProperty | String | '$payloadRef' | Property name containing the reference URL in the response |
+| debug | Boolean | false | Enable debug logging |
+| logger | Object | console | Logger object with debug() and error() methods |
+| onFetchLargePayloadFromRef | Function | Fetches the reference URL and returns the full payload | Callback function to fetch the full payload from the reference URL |
+| errorPayload | Unknown/Any | undefined | Error payload to return if the reference URL is not found or something goes wrong - this will be returned in the response data instead of throwing an error |
+| disableWarnings | Boolean | false | Disable warnings, only available globally in the options |
+
+For debug purposes, you can also set the `AXIOS_INTERCEPTOR_LARGE_RESPONSE_DEBUG` environment variable to `true` or `1` to enable debug logging.
+
+## How it works
+
+1. Adds the appropriate Accept header to requests to indicate large payload support;
+2. Detects responses with the configured header content type;
+3. If the response contains a reference in the specified refProperty, automatically fetches the full payload;
+4. Returns the complete data in the response.
+
+Example server response for a large payload:
+
+```json
+{
+  "$payloadRef": "https://api.example.com/large-payloads/123"
+}
+```
+
+After interceptor processing, the response becomes:
+
+```json
+{
+  "huge": "data",
+  "nested": {
+    "complex": "structure"
+  }
+}
+```
+

packages/axios-large-response/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@epilot/axios-large-response",
+  "version": "0.0.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/epilot-dev/aws-lambda-utility-middlewares.git#main",
+    "directory": "packages/axios-large-response"
+  },
+  "description": "Axios plugin to intercept large responses",
+  "keywords": ["axios-large-response", "large-response-middleware", "interceptor", "axios", "large-response", "plugin"],
+  "contributors": ["Alexandre Marques(https://github.com/alexmarqs)"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest",
+    "lint": "biome check --write .",
+    "prepublishOnly": "pnpm lint && pnpm build",
+    "typecheck": "tsc --noEmit",
+    "local:publish": "yalc publish"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "module": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": ["dist/**", "README.md"],
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "3.0.5",
+    "axios": "^1.6.2",
+    "tsup": "6.7.0"
+  },
+  "peerDependencies": {
+    "axios": ">=0.25.0"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

packages/axios-large-response/src/index.ts

@@ -0,0 +1,2 @@
+export { axiosLargeResponse } from './interceptor/axios-interceptor';
+export * from './types';