@joint-ops/hitlimit-types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JointOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @joint-ops/hitlimit-types
+
+[![npm version](https://img.shields.io/npm/v/@joint-ops/hitlimit-types.svg)](https://www.npmjs.com/package/@joint-ops/hitlimit-types)
+[![GitHub](https://img.shields.io/github/license/JointOps/hitlimit-monorepo)](https://github.com/JointOps/hitlimit-monorepo)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+> TypeScript type definitions for hitlimit rate limiting libraries
+
+This package contains shared TypeScript interfaces and types used by [@joint-ops/hitlimit](https://www.npmjs.com/package/@joint-ops/hitlimit) and [@joint-ops/hitlimit-bun](https://www.npmjs.com/package/@joint-ops/hitlimit-bun).
+
+## Installation
+
+This package is automatically installed as a dependency of `hitlimit` and `hitlimit-bun`. You don't need to install it directly.
+
+```bash
+# Install hitlimit (includes types automatically)
+npm install @joint-ops/hitlimit
+
+# Or for Bun
+bun add @joint-ops/hitlimit-bun
+```
+
+## Usage
+
+Types are re-exported from the main packages:
+
+```typescript
+import type {
+  HitLimitConfig,
+  RateLimitResult,
+  Store,
+  TierConfig
+} from '@joint-ops/hitlimit'
+
+// Or from hitlimit-bun
+import type { HitLimitConfig, Store } from '@joint-ops/hitlimit-bun'
+```
+
+## Available Types
+
+### Core Types
+
+```typescript
+// Main configuration
+interface HitLimitConfig {
+  limit?: number
+  window?: string | number
+  key?: (req: Request) => string | Promise<string>
+  tiers?: Record<string, TierConfig>
+  tier?: (req: Request) => string | Promise<string>
+  response?: RateLimitResponse | ((info: RateLimitInfo) => RateLimitResponse)
+  headers?: HeadersConfig
+  store?: Store
+  skip?: (req: Request) => boolean | Promise<boolean>
+  onStoreError?: (error: Error, req: Request) => 'allow' | 'deny'
+}
+
+// Store interface for custom backends
+interface Store {
+  increment(key: string, window: number): Promise<RateLimitResult>
+  decrement?(key: string): Promise<void>
+  reset?(key: string): Promise<void>
+  close?(): Promise<void>
+}
+
+// Rate limit result
+interface RateLimitResult {
+  allowed: boolean
+  limit: number
+  remaining: number
+  resetAt: number
+}
+
+// Tier configuration
+interface TierConfig {
+  limit: number
+  window?: string | number
+}
+```
+
+### Logger Types
+
+```typescript
+interface Logger {
+  debug(message: string, meta?: Record<string, unknown>): void
+  info(message: string, meta?: Record<string, unknown>): void
+  warn(message: string, meta?: Record<string, unknown>): void
+  error(message: string, meta?: Record<string, unknown>): void
+}
+```
+
+## Related Packages
+
+- [@joint-ops/hitlimit](https://www.npmjs.com/package/@joint-ops/hitlimit) - Rate limiting for Node.js (Express, NestJS)
+- [@joint-ops/hitlimit-bun](https://www.npmjs.com/package/@joint-ops/hitlimit-bun) - Rate limiting for Bun (Bun.serve, Elysia)
+
+## License
+
+MIT
+
+## Keywords
+
+rate limit types, typescript rate limit, rate limiter types, hitlimit, api types, middleware types, typescript definitions

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+export interface HitLimitOptions<TRequest = any> {
+    limit?: number;
+    window?: string | number;
+    key?: KeyGenerator<TRequest>;
+    tiers?: Record<string, TierConfig>;
+    tier?: TierResolver<TRequest>;
+    response?: ResponseConfig | ResponseFormatter;
+    headers?: HeadersConfig;
+    store?: HitLimitStore;
+    onStoreError?: StoreErrorHandler<TRequest>;
+    skip?: SkipFunction<TRequest>;
+    logger?: HitLimitLogger;
+}
+export interface TierConfig {
+    limit: number;
+    window?: string | number;
+}
+export interface HitLimitInfo {
+    limit: number;
+    remaining: number;
+    resetIn: number;
+    resetAt: number;
+    key: string;
+    tier?: string;
+}
+export interface HitLimitResult {
+    allowed: boolean;
+    info: HitLimitInfo;
+    headers: Record<string, string>;
+    body: Record<string, any>;
+}
+export interface HitLimitStore {
+    hit(key: string, windowMs: number, limit: number): Promise<StoreResult> | StoreResult;
+    reset(key: string): Promise<void> | void;
+    shutdown?(): Promise<void> | void;
+}
+export interface StoreResult {
+    count: number;
+    resetAt: number;
+}
+export interface HitLimitLogger {
+    debug(message: string, meta?: Record<string, any>): void;
+    info(message: string, meta?: Record<string, any>): void;
+    warn(message: string, meta?: Record<string, any>): void;
+    error(message: string, meta?: Record<string, any>): void;
+}
+export declare class HitLimitError extends Error {
+    readonly code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
+}
+export declare class StoreError extends HitLimitError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class ConfigError extends HitLimitError {
+    constructor(message: string);
+}
+export type ErrorCode = 'STORE_ERROR' | 'STORE_TIMEOUT' | 'CONFIG_ERROR' | 'KEY_ERROR' | 'TIER_ERROR';
+export interface HeadersConfig {
+    standard?: boolean;
+    legacy?: boolean;
+    retryAfter?: boolean;
+}
+export interface ResolvedConfig<TRequest = any> {
+    limit: number;
+    windowMs: number;
+    key: KeyGenerator<TRequest>;
+    tiers?: Record<string, TierConfig>;
+    tier?: TierResolver<TRequest>;
+    response: ResponseConfig | ResponseFormatter;
+    headers: Required<HeadersConfig>;
+    store: HitLimitStore;
+    onStoreError: StoreErrorHandler<TRequest>;
+    skip?: SkipFunction<TRequest>;
+    logger?: HitLimitLogger;
+}
+export type KeyGenerator<TRequest = any> = (req: TRequest) => string | Promise<string>;
+export type TierResolver<TRequest = any> = (req: TRequest) => string | Promise<string>;
+export type SkipFunction<TRequest = any> = (req: TRequest) => boolean | Promise<boolean>;
+export type StoreErrorHandler<TRequest = any> = (error: Error, req: TRequest) => 'allow' | 'deny' | Promise<'allow' | 'deny'>;
+export type ResponseFormatter = (info: HitLimitInfo) => Record<string, any>;
+export type ResponseConfig = Record<string, any>;
+export declare const DEFAULT_LIMIT = 100;
+export declare const DEFAULT_WINDOW = "1m";
+export declare const DEFAULT_WINDOW_MS = 60000;
+export declare const DEFAULT_MESSAGE = "Whoa there! Rate limit exceeded.";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,27 @@
+export class HitLimitError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'HitLimitError';
+    }
+}
+export class StoreError extends HitLimitError {
+    cause;
+    constructor(message, cause) {
+        super(message, 'STORE_ERROR');
+        this.cause = cause;
+        this.name = 'StoreError';
+    }
+}
+export class ConfigError extends HitLimitError {
+    constructor(message) {
+        super(message, 'CONFIG_ERROR');
+        this.name = 'ConfigError';
+    }
+}
+export const DEFAULT_LIMIT = 100;
+export const DEFAULT_WINDOW = '1m';
+export const DEFAULT_WINDOW_MS = 60000;
+export const DEFAULT_MESSAGE = 'Whoa there! Rate limit exceeded.';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqDA,MAAM,OAAO,aAAc,SAAQ,KAAK;IACO;IAA7C,YAAY,OAAe,EAAkB,IAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAA;QAD6B,SAAI,GAAJ,IAAI,CAAW;QAE1D,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,aAAa;IACE;IAA7C,YAAY,OAAe,EAAkB,KAAa;QACxD,KAAK,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;QADc,UAAK,GAAL,KAAK,CAAQ;QAExD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IAC1B,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,aAAa;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;QAC9B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;IAC3B,CAAC;CACF;AAoCD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAChC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAClC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAA;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG,kCAAkC,CAAA"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@joint-ops/hitlimit-types",
+  "version": "1.0.0",
+  "description": "Type definitions for hitlimit rate limiting library",
+  "author": {
+    "name": "Shayan M Hussain",
+    "email": "shayanhussain48@gmail.com",
+    "url": "https://github.com/ShayanHussainSB"
+  },
+  "license": "MIT",
+  "homepage": "https://hitlimit.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JointOps/hitlimit-monorepo",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/JointOps/hitlimit-monorepo/issues"
+  },
+  "keywords": [
+    "rate-limit",
+    "rate-limiter",
+    "types",
+    "typescript",
+    "type-definitions",
+    "hitlimit",
+    "rate-limit-types",
+    "api-types",
+    "middleware-types"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  }
+}