@qubitcodes/qcresp

Standardized response handler and semantic internal codes registry for Next.js (App Router, Edge, Edge API routes, Turbopack) and Node.js web applications.

Exposes a highly typed semantic internal code contract with compile-time verified HTTP status synchronization, range-based resolvers for dynamic user codes, and manual HTTP overrides on-demand.

Installation

npm install @qubitcodes/qcresp

Features

• 🛡️ Type-Safe Semantic Reference (CODES enum): Exposes a standardized registry of named events (CODES.OK, CODES.VALIDATION_ERROR, etc.) for zero magic-number references across controllers.
• ⚡ O(1) Status Resolution Cache: Pre-compiles dynamic lookup caches once during module initialization to ensure lightning fast, constant-time HTTP status mapping.
• 🧩 Open-Ended Custom Codes: Supports standard template codes with autocomplete, while allowing developers to supply any arbitrary custom success/error codes (like 405 for MAIL_FAILED) which resolve automatically via fallback ranges.
• 🎛️ Manual Override: Supports an optional customHttpStatus override parameter on-demand to bypass automatic resolution.

API Reference

1. resp.success

resp.success<T>(
  message?: string,          // Custom success message
  data?: T | null,           // Payload array/object
  code?: ResponseCode,       // Internal semantic application code (defaults to CODES.OK)
  misc?: Record<string, any>,// Optional metadata (e.g. pagination, auth tokens)
  customHttpStatus?: number  // Optional manual HTTP status override
)

2. resp.failure

resp.failure<T>(
  message?: string,          // Custom error message
  code?: ResponseCode,       // Internal semantic application code (defaults to CODES.GENERAL_CLIENT_ERROR)
  errors?: any[],            // Detailed validation / system error arrays
  data?: T | null,           // Payload payload
  misc?: Record<string, any>,// Optional metadata
  customHttpStatus?: number  // Optional manual HTTP status override
)

Example Usage

A. Standard Semantic Response

import { resp } from '@qubitcodes/qcresp';

// Return a standard HTTP 200 / App Code 100 response
return resp.success('Profile fetched successfully.', profileData, resp.codes.OK);

B. Custom Internal Codes with Range Fallbacks

You can pass any custom application code. The resolver automatically assigns the correct HTTP status:

import { resp } from '@qubitcodes/qcresp';

// Internal error code 405 (automatically maps to HTTP 422 Business Logic Error)
return resp.failure('Mail failed to send.', 405);

C. Manual HTTP Status Override

import { resp } from '@qubitcodes/qcresp';

// Overrides default database mapping to return a standard HTTP 503 Service Unavailable
return resp.failure(
  'Database maintenance underway.',
  resp.codes.SYSTEM_MAINTENANCE,
  undefined,
  null,
  undefined,
  503
);

License

MIT License - Copyright (c) 2026 QubitCodes