Kinetex Universal HTTP Client

0.0.2 verified Thu Apr 23 auth: no javascript

Kinetex is an early-stage universal HTTP client designed for a wide range of JavaScript runtimes, including Node.js (v18+), browsers, Deno, Bun, and Cloudflare Workers. Currently at version `0.0.2`, it aims to provide a comprehensive solution with built-in support for advanced features such as HTTP/2 and HTTP/3, schema validation (via Zod or Valibot), a flexible middleware system, and integrated utilities for caching, request deduplication, retries, HAR recording, Server-Sent Events (SSE), and GraphQL. Its key differentiators include its broad runtime compatibility, modern HTTP protocol support, and extensive feature set that often requires multiple separate libraries in other HTTP clients. The project is in active, rapid development, and API stability cannot be guaranteed at this early stage.

Common errors

error Error: Cannot find module 'zod' or its corresponding type declarations. ↓

cause The `zod` peer dependency is not installed, but Kinetex attempts to use it for schema validation.

fix

Install Zod as a direct dependency: npm install zod.

error ERR_REQUIRE_ESM: require() of ES Module .../node_modules/kinetex/dist/index.js from ... not supported. ↓

cause Attempting to import Kinetex, an ESM-only package, using CommonJS `require()` in a non-ESM context.

fix

Configure your project for ESM by adding "type": "module" to your package.json, ensure your Node.js version is >=18, and use import statements.

error TypeError: Cannot read properties of undefined (reading 'get') ↓

cause Incorrect import of the default Kinetex client instance. Forgetting `import kinetex from 'kinetex';` and trying to use `kinetex` as if it were globally available, or importing it incorrectly as a named export (`import { kinetex } from 'kinetex';`) where `kinetex` itself is the default export.

fix

Ensure you correctly import the default Kinetex instance: import kinetex from 'kinetex';

Warnings

breaking Kinetex is currently in a very early development stage (v0.0.2). Expect frequent and potentially breaking API changes between minor and even patch versions as the project stabilizes. Avoid using in production without thorough testing and readiness for rapid updates. ↓

fix Review the changelog and GitHub issues for each update. Pin exact versions for production use and dedicate time for migration when updating.

gotcha Kinetex relies on specific peer dependencies for core functionality like schema validation (Zod, Valibot) and Node.js HTTP client (Undici). These must be installed manually by the user, as Kinetex does not bundle them. Failure to install them will result in runtime errors. ↓

fix Install required peer dependencies alongside Kinetex: `npm install kinetex zod undici valibot socks-proxy-agent` (install only those relevant to your use case).

gotcha Kinetex targets modern JavaScript environments and explicitly requires Node.js version 18 or higher. It is an ESM-only package and does not support CommonJS `require()` syntax. Attempting to use it in older Node.js versions or CommonJS modules will lead to import errors. ↓

fix Ensure your project runs on Node.js 18+ and is configured as an ESM module (e.g., by adding `"type": "module"` to your `package.json` or using `.mjs` file extensions).

Install

npm install kinetex

yarn add kinetex

pnpm add kinetex

Imports

kinetex
wrong
```
import { kinetex } from 'kinetex';
const kinetex = require('kinetex');
```
correct
```
import kinetex from 'kinetex';
```
The default export is a pre-configured instance of the Kinetex client, ready for immediate use. Kinetex is ESM-only; CommonJS `require()` is not supported.
Kinetex
wrong
```
import Kinetex from 'kinetex';
const { Kinetex } = require('kinetex');
```
correct
```
import { Kinetex } from 'kinetex';
```
Use the named export `Kinetex` to instantiate a custom client with specific configurations (e.g., custom base URL, middleware). Kinetex is ESM-only.
defineMiddleware
wrong
```
import defineMiddleware from 'kinetex';
const { defineMiddleware } = require('kinetex');
```
correct
```
import { defineMiddleware } from 'kinetex';
```
Helper function for defining type-safe middleware. This ensures correct type inference and adherence to the middleware interface. Kinetex is ESM-only.

Quickstart

Demonstrates importing the default `kinetex` instance, defining a custom middleware, and performing a GET request with Zod schema validation for the response body. It also includes basic error handling for validation and network issues.

import kinetex, { defineMiddleware } from 'kinetex';
import { z } from 'zod'; // Assuming Zod is installed: npm install zod

const authMiddleware = defineMiddleware(async (ctx, next) => {
  console.log(`Requesting: ${ctx.url}`);
  ctx.request.headers.set('Authorization', `Bearer ${process.env.API_TOKEN ?? 'your-secret-token'}`);
  const response = await next(ctx);
  console.log(`Response status: ${response.status}`);
  return response;
});

const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

async function fetchUserData() {
  try {
    const response = await kinetex
      .use(authMiddleware)
      .get('https://jsonplaceholder.typicode.com/users/1')
      .response(userSchema);

    console.log('Fetched User Data:', response.data);
  } catch (error) {
    if (error instanceof z.ZodError) {
      console.error('Validation Error:', error.errors);
    } else {
      console.error('Fetch Error:', error.message);
    }
  }
}

fetchUserData();