@ultra-tools/http

@ultra-tools/http

Complete HTTP utility toolkit for Node.js and browsers - Status codes, error handling, response builders, headers management, and framework integration with zero dependencies.

✨ Features

• 🚀 Complete HTTP Status Codes (100-599) with validation
• 🛡️ Robust Error Handling with specific error classes and factory functions
• 📤 Response Builders for success, error, redirection, and pagination
• 🔧 Headers Management for CORS, cache, and security
• 🎯 Framework Integration with Express.js and Fastify
• 📱 Zero Dependencies - Lightweight and fast
• 🔒 TypeScript First with strict typing and IntelliSense
• 📚 Comprehensive Documentation with examples

📦 Installation

npm install @ultra-tools/http
# or
yarn add @ultra-tools/http
# or
pnpm add @ultra-tools/http

🚀 Quick Start

Import the entire HTTP toolkit

import http from '@ultra-tools/http';

// Status codes
const ok = http.status.codes.OK;           // 200
const notFound = http.status.codes.NOT_FOUND; // 404

// Validation
const isValid = http.status.isValid(200);  // true
const message = http.status.getMessage(404); // "Not Found"

// Error handling
const error = http.error.badRequest('Invalid input');

// Response building
const response = http.response.ok({ data: 'success' });

Import specific categories

import { status, error, response, headers } from '@ultra-tools/http';

// Direct access
const statusCode = status.codes.OK;
const error1 = error.badRequest('Invalid input');
const response1 = response.ok({ data: 'success' });
const corsHeaders = headers.cors('*');

📚 API Reference

Status Codes (http.status)

Get status codes

import { status } from '@ultra-tools/http';

// All status codes
const ok = status.codes.OK;                    // 200
const created = status.codes.CREATED;          // 201
const notFound = status.codes.NOT_FOUND;       // 404
const serverError = status.codes.INTERNAL_SERVER_ERROR; // 500

// By category
const successCodes = status.success;           // All 2xx codes
const clientErrors = status.clientError;       // All 4xx codes
const serverErrors = status.serverError;       // All 5xx codes

Validation utilities

// Check if valid
const isValid = status.isValid(200);          // true
const isValid2 = status.isValid(999);         // false

// Get message
const message = status.getMessage(404);        // "Not Found"

// Get category
const category = status.getCategory(500);      // "server_error"

// Validate and throw if invalid
status.validate(200);                          // ✅ OK
status.validate(999);                          // ❌ Throws Error

Validation Helpers (http.is)

import { is } from '@ultra-tools/http';

// Category checks
is.success(200);        // true
is.error(404);          // true
is.retryable(500);      // true

// Property checks
is.cacheable(200);      // true
is.empty(204);          // true
is.informational(100);  // true
is.redirection(301);    // true
is.clientError(400);    // true
is.serverError(500);    // true

Error Handling (http.error)

Create specific errors

import { error } from '@ultra-tools/http';

// Factory functions (recommended)
const badRequest = error.badRequest('Invalid input');
const notFound = error.notFound('User missing');
const serverError = error.internalServerError('Database error');

// With additional details
const detailedError = error.badRequest('Validation failed', {
  field: 'email',
  value: 'invalid-email',
  rule: 'must be valid email format'
});

// Custom status code
const customError = error.create(418, "I'm a teapot", { reason: 'RFC 2324' });

Error classes

// Direct instantiation
const error1 = new error.BadRequest('Invalid input');
const error2 = new error.NotFound('Resource missing');
const error3 = new error.InternalServerError('Server error');

Error utilities

// Check error types
error.isHTTPError(badRequest);     // true
error.isClientError(badRequest);   // true
error.isServerError(serverError);  // true
error.isRetryable(serverError);    // true

// Check status codes
error.hasStatusCode(badRequest, 400);  // true

Response Builders (http.response)

Success responses

import { response } from '@ultra-tools/http';

// Basic success
const okResponse = response.ok({ data: 'Hello World' });
const createdResponse = response.created({ id: 123, name: 'John' });
const noContentResponse = response.noContent();

// With custom message
const response1 = response.ok({ data: 'success' }, 'Operation completed');
const response2 = response.created({ id: 456 }, 'User created successfully');

Error responses

// Error responses
const badRequestResponse = response.badRequest('Invalid input');
const notFoundResponse = response.notFound('User not found');
const serverErrorResponse = response.internalServerError('Database error');

// With details
const detailedResponse = response.badRequest('Validation failed', {
  field: 'email',
  value: 'invalid-email'
});

Redirection responses

// Redirection
const movedResponse = response.movedPermanently('/new-location');
const foundResponse = response.found('/temporary-location');
const redirectResponse = response.temporaryRedirect('/temp-location');

Pagination

// Paginated response
const users = [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }];
const paginatedResponse = response.paginated(users, 1, 10, 100, 'Users retrieved');

// Pagination metadata only
const meta = response.paginationMeta(1, 10, 100);
// { page: 1, limit: 10, total: 100, totalPages: 10, hasNext: true, hasPrev: false }

Headers Management (http.headers)

import { headers } from '@ultra-tools/http';

// Common headers
const commonHeaders = headers.common({ 'x-api-version': '2.0' });

// CORS headers
const corsHeaders = headers.cors('https://example.com', 'GET, POST, PUT');
const openCorsHeaders = headers.cors('*', 'GET, POST');

// Cache headers
const cacheHeaders = headers.cache(3600); // 1 hour
const cacheWithEtag = headers.cache(7200, 'etag-123');

Framework Integration (http.framework)

import { framework } from '@ultra-tools/http';

const response = response.ok({ data: 'test' });

// Express.js format
const expressResponse = framework.express(response);
// { status: 200, json: { data: 'test' }, headers: {...} }

// Fastify format
const fastifyResponse = framework.fastify(response);
// { statusCode: 200, payload: { data: 'test' }, headers: {...} }

🔧 Advanced Usage

Custom error handling

import { error } from '@ultra-tools/http';

// Create custom error handler
function handleError(err: unknown) {
  if (error.isHTTPError(err)) {
    // Handle HTTP errors
    if (error.isRetryable(err)) {
      // Retry logic
      console.log('Retryable error:', err.message);
    } else if (error.isClientError(err)) {
      // Client error - don't retry
      console.log('Client error:', err.message);
    }

    // Convert to response
    return err.toResponse();
  }

  // Handle other errors
  return error.internalServerError('Unknown error').toResponse();
}

Response middleware

import { response, headers } from '@ultra-tools/http';

// Express middleware
app.use((req, res, next) => {
  // Add common headers
  const commonHeaders = headers.common();
  Object.entries(commonHeaders).forEach(([key, value]) => {
    res.setHeader(key, value);
  });

  // Add CORS if needed
  if (req.method === 'OPTIONS') {
    const corsHeaders = headers.cors('*');
    Object.entries(corsHeaders).forEach(([key, value]) => {
      res.setHeader(key, value);
    });
  }

  next();
});

// Response handler
app.get('/api/users', (req, res) => {
  try {
    const users = getUserService.getUsers();
    const response = response.ok(users, 'Users retrieved successfully');

    // Set headers
    Object.entries(response.headers).forEach(([key, value]) => {
      res.setHeader(key, value);
    });

    res.status(response.statusCode).json(response);
  } catch (err) {
    const errorResponse = response.internalServerError('Failed to get users');
    res.status(errorResponse.statusCode).json(errorResponse);
  }
});

Validation pipeline

import { status, response } from '@ultra-tools/http';

function validateStatusCodes(codes: number[]) {
  const invalidCodes: number[] = [];
  const validCodes: number[] = [];

  codes.forEach(code => {
    if (status.isValid(code)) {
      validCodes.push(code);
    } else {
      invalidCodes.push(code);
    }
  });

  if (invalidCodes.length > 0) {
    throw new Error(`Invalid status codes: ${invalidCodes.join(', ')}`);
  }

  return validCodes;
}

// Usage
try {
  const codes = [200, 404, 500, 999]; // 999 is invalid
  const validCodes = validateStatusCodes(codes);
  console.log('Valid codes:', validCodes);
} catch (err) {
  console.error('Validation failed:', err.message);
}

📖 Examples

Complete API endpoint

import { response, error, headers } from '@ultra-tools/http';

app.post('/api/users', async (req, res) => {
  try {
    // Validate input
    if (!req.body.email || !req.body.name) {
      const errorResponse = response.badRequest('Missing required fields', {
        required: ['email', 'name'],
        provided: Object.keys(req.body)
      });
      return res.status(errorResponse.statusCode).json(errorResponse);
    }

    // Create user
    const user = await userService.createUser(req.body);

    // Success response
    const successResponse = response.created(user, 'User created successfully');

    // Set headers
    const responseHeaders = {
      ...headers.common(),
      ...successResponse.headers
    };

    Object.entries(responseHeaders).forEach(([key, value]) => {
      res.setHeader(key, value);
    });

    res.status(successResponse.statusCode).json(successResponse);

  } catch (err) {
    // Handle specific errors
    if (err.code === 'DUPLICATE_EMAIL') {
      const conflictResponse = response.conflict('Email already exists');
      return res.status(conflictResponse.statusCode).json(conflictResponse);
    }

    // Generic server error
    const serverErrorResponse = response.internalServerError('Failed to create user');
    res.status(serverErrorResponse.statusCode).json(serverErrorResponse);
  }
});

Error handling with retry logic

import { error, is } from '@ultra-tools/http';

async function fetchWithRetry(url: string, maxRetries = 3) {
  let lastError: Error;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url);

      if (is.success(response.status)) {
        return await response.json();
      }

      if (is.clientError(response.status)) {
        // Don't retry client errors
        throw new Error(`Client error: ${response.status}`);
      }

      if (is.serverError(response.status) && is.retryable(response.status)) {
        // Retry server errors
        lastError = new Error(`Server error: ${response.status}`);
        continue;
      }

      throw new Error(`Unexpected status: ${response.status}`);

    } catch (err) {
      lastError = err as Error;

      if (attempt === maxRetries) {
        break;
      }

      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
    }
  }

  throw lastError!;
}

🆚 Comparison with Alternatives

Feature	@ultra-tools/http	http-status-codes	http-errors	statuses
Status Codes	✅ Complete (100-599)	✅ Complete	❌ Limited	✅ Complete
Error Handling	✅ Classes + Factory	❌ None	✅ Classes only	❌ None
Response Builders	✅ Full API	❌ None	❌ None	❌ None
Headers Management	✅ CORS + Cache	❌ None	❌ None	❌ None
Framework Integration	✅ Express + Fastify	❌ None	❌ None	❌ None
TypeScript	✅ First-class	✅ Yes	✅ Yes	❌ No
Zero Dependencies	✅ Yes	✅ Yes	❌ No	✅ Yes
Documentation	✅ Comprehensive	❌ Basic	❌ Basic	❌ Basic

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/ultra-tools/ultra.git
cd ultra

# Install dependencies
yarn install

# Build packages
yarn build

# Run tests
yarn test

# Run linting
yarn lint

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation: https://ultra-tools.dev/docs/http
• GitHub: https://github.com/ultra-tools/ultra
• Issues: https://github.com/ultra-tools/ultra/issues
• Discussions: https://github.com/ultra-tools/ultra/discussions
• Changelog: CHANGELOG.md

⭐ Star History

Made with ❤️ by the Ultra team