TypeScript SDK Integration

LimitYourAPI TypeScript SDK with full type definitions for Node.js and edge runtimes.

TypeScript SDK Reference Guide

The LimitYourAPI TypeScript SDK provides complete static type definitions and structural interfaces for building robust, type-safe rate limiting mechanisms. For a quickstart focus with Express middleware examples, see the [JavaScript SDK](/sdk/javascript).

1. Installation

`bash

npm install limityourapi

`

2. Types & Interfaces

The SDK exports strong type contracts for both input options and output decisions.

`typescript

export interface LimitOptions {

apiKey: string;

timeout?: number; // Socket timeout in milliseconds (default: 1000)

failOpen?: boolean; // When true, allows traffic if Redis/API is offline (default: true)

maxRetries?: number; // Automatic retry attempts for network failures (default: 3)

}

export interface CheckParams {

key: string; // Rate limit identifier (e.g. user ID, IP, or token hash)

route: string; // The path or action being rated (e.g., "GET /items")

cost?: number; // Weight of the request (default: 1)

}

export interface CheckResult {

allowed: boolean; // Rate decision

limit: number; // Maximum quota limit

remaining: number; // Remaining requests in window

reset: number; // Unix timestamp when rate limit resets

retryAfter: number; // Time in seconds to wait before retrying (0 if allowed)

}

`

3. Advanced Configuration

Initialize the client with complete type validation and configuration tuning:

`typescript

import { LimitYourAPIClient, LimitOptions, CheckParams, CheckResult } from 'limityourapi';

const config: LimitOptions = {

apiKey: process.env.LIMIT_YOUR_API_KEY || '',

timeout: 500, // Fast timeout budget of 500ms

failOpen: true, // Fail-open for user experience resiliency

maxRetries: 2

};

const limiter = new LimitYourAPIClient(config);

async function handleRequest(userId: string, path: string): Promise {

const params: CheckParams = {

key: userId,

route: path,

cost: 1

};

const decision: CheckResult = await limiter.check(params);

if (!decision.allowed) {

throw new Error(Rate limit hit. Retry in ${decision.retryAfter} seconds.);

}

}

`

4. Production Checklist

• Always pass a secure API key (rl_...) loaded via environment variables.
• Enable failOpen: true in production to prevent caching layer outages from dropping client requests.
• Configure socket timeouts (timeout: 1000) to maintain low latency bounds.
• Set custom key identifiers to trace limits by authenticated User ID rather than shared client IPs.