kinetex

library0.0.2jsnpmunverified

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.

http-networking serialization web-framework

npm install kinetex

github ↗package ↗

INSTALL

IMPORT

SIG · KINETEX

kinetex

http-networkingjavascriptv0.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

kinetex

✓ import kinetex from 'kinetex';

✗ import { kinetex } from 'kinetex'; const kinetex = require('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

✓ import { Kinetex } from 'kinetex';

✗ import Kinetex from 'kinetex'; const { Kinetex } = require('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

✓ import { defineMiddleware } from 'kinetex';

✗ import defineMiddleware from 'kinetex'; const { defineMiddleware } = require('kinetex');

Helper function for defining type-safe middleware. This ensures correct type inference and adherence to the middleware interface. Kinetex is ESM-only.

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();

Debug

Known issues

breakingKinetex 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.

affects: >=0.0.1

gotchaKinetex 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).

affects: >=0.0.1

gotchaKinetex 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).

affects: >=0.0.1

Errors

Common errors & fixes

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

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`.

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

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.

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

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';`

Upgrade

Version history

0.0.2latest on npm

Audit

Dependencies

zodoptionalPeer dependency for schema validation.

undicioptionalPeer dependency for high-performance HTTP/1.1 and HTTP/2 client in Node.js environments.

valibotoptionalPeer dependency for an alternative, lightweight schema validation library.

socks-proxy-agentoptionalPeer dependency for SOCKS proxy support.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/kinetexjs/kinetex ↗

packagehttps://www.npmjs.com/package/kinetex ↗