Http Support

🔧 What it does: TypeScript library for HTTP status codes with human-friendly messages
🌐 Works with: Any framework, any runtime (Node, Deno, Bun, Edge)

Compatibility

• 🏃 Runtimes: Node.js • Deno • Bun • Edge Runtime
• 🏗️ Backend: Express • NestJS • Fastify • Hono • Koa
• ⚛️ Frontend: React • Vue • Angular • Svelte
• 🧪 Testing: Jest • Vitest • MSW • Playwright

Install & Use

npm install http-supports
# or
yarn add http-supports
# or
pnpm add http-supports

import { http } from 'http-supports';
// or
import http from 'http-supports';

// ✅ Status codes
http.status.OK                    // 200
http.status.NOT_FOUND            // 404
http.status.INTERNAL_SERVER_ERROR // 500

// ✅ Status text  
http.statusText.NOT_FOUND        // "Not Found"

// ✅ Human-friendly messages
http.message.NOT_FOUND           // "We can't find what you're looking for..."

// ✅ Complete objects
http.full.OK                     // { status: 200, statusText: "OK", message: "Perfect! Everything worked as expected." }
http.full.NOT_FOUND             // { status: 404, statusText: "Not Found", message: "We can't find..." }

API Reference

Default Instance

import { http } from 'http-supports';

// Access status codes
http.status.OK                    // 200
http.status.CREATED              // 201
http.status.BAD_REQUEST          // 400
http.status.NOT_FOUND            // 404

// Access status text
http.statusText.OK               // "OK"
http.statusText.NOT_FOUND        // "Not Found"

// Access human-friendly messages
http.message.OK                  // "Perfect! Everything worked as expected."
http.message.NOT_FOUND          // "We can't find what you're looking for..."

// Access complete objects
http.full.OK                     // { status: 200, statusText: "OK", message: "Perfect! Everything worked as expected." }
http.full.NOT_FOUND             // { status: 404, statusText: "Not Found", message: "We can't find..." }

Custom Sections

import { HttpProvider } from 'http-supports';

// Create custom HTTP provider
const customHttp = HttpProvider.create({
  CUSTOM_SUCCESS: {
    status: 250,
    statusText: "Custom Success",
    message: "This is a custom success status"
  },
  API_KEY_REQUIRED: {
    status: 460,
    statusText: "API Key Required", 
    message: "Please provide a valid API key"
  }
});

console.log(customHttp.status.CUSTOM_SUCCESS);     // 250
console.log(customHttp.message.API_KEY_REQUIRED);  // "Please provide a valid API key"

Extending HTTP Sections

import { http } from 'http-supports';

// Extend default with custom sections
const extended = http.extend({
  CUSTOM_ERROR: {
    status: 499,
    statusText: "Custom Error",
    message: "Something custom went wrong"
  }
});

// Has all default status codes plus custom ones
console.log(extended.status.NOT_FOUND);    // 404 (from default)
console.log(extended.status.CUSTOM_ERROR); // 499 (custom)

Individual Sections

import { 
  INFORMATIONAL, 
  SUCCESS, 
  CLIENT_ERROR,
  HttpProvider 
} from 'http-supports';

// Use only specific sections
const apiHttp = HttpProvider.create({
  ...SUCCESS,
  ...CLIENT_ERROR
});

console.log(apiHttp.status.OK);        // 200
console.log(apiHttp.status.NOT_FOUND); // 404
// No server errors or redirects included

Quick Examples

🔧 Server (Express/NestJS/Next.js)

import { http } from 'http-supports';

// Express/Fastify/Koa
app.get('/users/:id', async (req, res) => {
  try {
    const user = await getUserById(req.params.id);
    
    if (!user) {
      return res.status(http.status.NOT_FOUND).json({
        error: http.statusText.NOT_FOUND,
        message: http.message.NOT_FOUND
      });
    }
    
    res.status(http.status.OK).json(user);
  } catch (error) {
    res.status(http.status.INTERNAL_SERVER_ERROR).json({
      error: http.statusText.INTERNAL_SERVER_ERROR,
      message: http.message.INTERNAL_SERVER_ERROR
    });
  }
});

// NestJS  
@Get('users/:id')
async getUser(@Param('id') id: string) {
  const user = await this.userService.findById(id);
  
  if (!user) {
    throw new HttpException(
      http.message.NOT_FOUND, 
      http.status.NOT_FOUND
    );
  }
  
  return user;
}

// Next.js API Routes
export async function GET(request: NextRequest) {
  try {
    const data = await fetchData();
    
    return NextResponse.json(data, {
      status: http.status.OK
    });
  } catch (error) {
    return NextResponse.json(
      { 
        error: http.statusText.INTERNAL_SERVER_ERROR,
        message: http.message.INTERNAL_SERVER_ERROR 
      },
      { status: http.status.INTERNAL_SERVER_ERROR }
    );
  }
}

// Hono
app.get('/api/users', async (c) => {
  try {
    const users = await getUsers();
    return c.json(users, http.status.OK);
  } catch (error) {
    return c.json(
      { message: http.message.INTERNAL_SERVER_ERROR },
      http.status.INTERNAL_SERVER_ERROR
    );
  }
});

💻 Client (React/Vue/Angular)

import { http } from 'http-supports';

// React/Vue/Angular HTTP client
const fetchUser = async (id: string) => {
  const response = await fetch(`/api/users/${id}`);
  
  if (response.status === http.status.NOT_FOUND) {
    throw new Error(http.message.NOT_FOUND);
  }
  
  if (response.status === http.status.UNAUTHORIZED) {
    // Redirect to login
    window.location.href = '/login';
    return;
  }
  
  if (!response.ok) {
    throw new Error(http.message.INTERNAL_SERVER_ERROR);
  }
  
  return response.json();
};

// Error handling with specific messages
try {
  const user = await fetchUser('123');
} catch (error) {
  if (error.message === http.message.NOT_FOUND) {
    showNotification('User not found', 'warning');
  } else {
    showNotification('Something went wrong', 'error');
  }
}

🧪 Testing (Jest/Vitest)

import { http } from 'http-supports';
import request from 'supertest';
import app from '../app';

describe('User API', () => {
  test('should return 404 for non-existent user', async () => {
    const response = await request(app)
      .get('/users/999')
      .expect(http.status.NOT_FOUND);
    
    expect(response.body.message).toBe(http.message.NOT_FOUND);
  });
  
  test('should return 200 for existing user', async () => {
    const response = await request(app)
      .get('/users/1')
      .expect(http.status.OK);
      
    expect(response.body).toHaveProperty('id');
  });
});

Available Status Codes

1xx Informational

| Code | Status | Message | |---|---|---| | 100 | Continue | Great! Keep going with your request. | | 101 | Switching Protocols | We're switching to a better protocol as you requested... | | 102 | Processing | Hang tight! We're working on your request... | | 103 | Early Hints | Here's a sneak peek! We're sending you some early hints... |

2xx Success

| Code | Status | Message | |---|---|---| | 200 | OK | Perfect! Everything worked as expected. | | 201 | Created | Success! Your new resource has been created. | | 202 | Accepted | Got it! We've accepted your request and are processing it now. | | 204 | No Content | Done! Your request was successful, but there's nothing to show you. |

3xx Redirection

| Code | Status | Message | |---|---|---| | 301 | Moved Permanently | This page has moved to a new address permanently. Update your bookmarks! | | 302 | Found | Found it! But it's at a different address. We'll take you there. | | 304 | Not Modified | Good news! Nothing has changed since your last visit... | | 307 | Temporary Redirect | This page is temporarily at a different location... |

4xx Client Errors

| Code | Status | Message | |---|---|---| | 400 | Bad Request | Oops! Something's wrong with your request. Please check your data and try again. | | 401 | Unauthorized | You need to log in first. Please sign in to continue. | | 403 | Forbidden | Sorry, you don't have access to this. Contact support if you think this is a mistake. | | 404 | Not Found | We can't find what you're looking for. Check the URL or go back to the homepage. | | 429 | Too Many Requests | Whoa, slow down! You're making too many requests. Please wait a moment and try again. |

5xx Server Errors

| Code | Status | Message | |---|---|---| | 500 | Internal Server Error | Oops! Something went wrong on our end. We're working on it - please try again in a few minutes. | | 502 | Bad Gateway | There's a problem with our server connection. Please try again shortly. | | 503 | Service Unavailable | We're temporarily down for maintenance. Please check back soon! |

View all 59+ status codes →

TypeScript Support

Full TypeScript support with autocomplete and type safety:

import { HttpProvider, Http } from 'http-supports';

// Type-safe custom sections
interface CustomHttp extends Record<string, Http> {
  MY_CUSTOM_STATUS: Http;
}

const customSection: CustomHttp = {
  MY_CUSTOM_STATUS: {
    status: 299,
    statusText: "Custom Status",
    message: "This is a custom status message"
  }
};

const customHttp = HttpProvider.create(customSection);

// Full autocomplete and type checking
customHttp.status.MY_CUSTOM_STATUS; // 299 (number)
customHttp.statusText.MY_CUSTOM_STATUS; // "Custom Status" (string)
customHttp.message.MY_CUSTOM_STATUS; // "This is a custom status message" (string)

Why We Built This 💙

HTTP status codes shouldn't be mysterious numbers that developers have to memorize or constantly look up. Every 404 has a story, every 500 represents a moment where something didn't go as planned, and every 200 is a small victory worth celebrating.

We believe that code should be human-friendly, not just machine-readable. That's why every status code in this library comes with a message that speaks to real people - developers like you who are building amazing things and sometimes need a gentle reminder of what went wrong... or right!

Whether you're a seasoned developer tired of typing the same status codes over and over, or someone just starting their journey and trying to make sense of HTTP responses, this library is our gift to you.

Happy coding! 🚀

Contributing

Found a bug? Have an idea for a better message? We'd love to hear from you!

• 🐛 Report Issues: GitHub Issues
• 💡 Suggest Features: GitHub Discussions
• 🤝 Pull Requests: Always welcome!

Support the Project

If this library made your development life a little easier, consider:

• ⭐ Star the repo on GitHub
• 📦 Share it with your team
• 💬 Tell us how you're using it

Every star means the world to us! ✨

License

MIT © thieenlabs

Made with ❤️ for developers who believe that code should be as human as the people who write it.