@mxpicture/redis-client

Typed Node.js client for the docker-redis HTTP API. Thin wrapper over fetch that injects X-Api-Key auth and parses responses.

Install

npm install @mxpicture/redis-client

Requires Node.js 20+ (uses built-in fetch).

Usage

import { RedisApiClient, RedisApiError } from '@mxpicture/redis-client';

const client = new RedisApiClient({
  baseUrl: 'http://localhost:3000',
  apiKey: process.env.API_KEY!,
});

// Health (no auth)
const health = await client.health();
// → { status: 'ok', redis: 'connected' }

// Write
await client.setKey('foo', 'bar');
await client.setKey('session', 'abc', { ttl: 60 });

// Read
const entry = await client.getKey('foo');
// → { key: 'foo', value: 'bar', ttl: null }

// Errors
try {
  await client.getKey('missing');
} catch (err) {
  if (err instanceof RedisApiError) {
    console.error(err.statusCode, err.message, err.body);
  }
}

API

new RedisApiClient(options)

| Option | Type | Required | Description | |----------|-------------------------------|----------|------------------------------------------------------------------| | baseUrl| string | Yes | Base URL of the API (no trailing slash required). | | apiKey | string | Yes | Value sent as the X-Api-Key header on authenticated requests. | | fetch | typeof globalThis.fetch | No | Inject a custom fetch (defaults to the global one). |

Methods

| Method | Returns | Throws | |------------------------------------------------|--------------------------|---------------------------------| | health() | Promise<HealthResponse>| RedisApiError on non-2xx | | getKey(key) | Promise<KeyValue> | RedisApiError (404 if absent) | | setKey(key, value, { ttl? }) | Promise<KeyValue> | RedisApiError on non-2xx |

RedisApiError

Thrown for non-2xx HTTP responses. Network errors propagate from fetch untouched.

class RedisApiError extends Error {
  readonly statusCode: number;
  readonly body: unknown;
}

Notes

• No retries, no automatic timeout. Wrap calls with AbortSignal yourself if you need either.
• The client does not validate response shapes at runtime — it trusts the API contract.