{"id":17313,"library":"objective-http","title":"Objective HTTP Server","description":"objective-http is a Node.js library that provides Object-Oriented Programming (OOP) proxy classes for constructing HTTP servers. It wraps Node.js's native `http` module, abstracting away low-level stream interactions into a more structured, class-based API. The library emphasizes a clear separation of concerns, allowing developers to define server logic through `Endpoint` classes (for route and request handling) and `Handler` classes (for error handling and request/response stream processing). Currently stable at version 2.1.6, the package appears to have a fairly active release cadence with frequent patch updates. It differentiates itself by offering a highly modular and extensible architecture for building HTTP services, including an `autoconfig` feature for simpler server setups, contrasting with more opinionated frameworks or purely functional approaches.","status":"active","version":"2.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/volatilization/objective-http","tags":["javascript","web","web-server","http","http-server","oop"],"install":[{"cmd":"npm install objective-http","lang":"bash","label":"npm"},{"cmd":"yarn add objective-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add objective-http","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary `Server` class is exposed via the `.server` namespace in CommonJS. Direct ESM imports like `import { Server } from 'objective-http';` are likely incorrect or unsupported due to the deep nesting of exports.","wrong":"import { Server } from 'objective-http';","symbol":"Server","correct":"const { Server } = require('objective-http').server;"},{"note":"The autoconfiguration utility is nested under `server.autoconfig`. It's exported as `server` within that module, so it's common to rename it on import.","wrong":"import { autoconfigServer } from 'objective-http/server/autoconfig';","symbol":"autoconfig","correct":"const { server: autoconfigServer } = require('objective-http').server.autoconfig;"},{"note":"Many core classes are deeply nested within the `handler`, `request`, and `response` namespaces. Proper CommonJS destructuring is required to access them.","symbol":"EndpointHandler, JsonServerRequest, LogErrorHandler","correct":"const { handler, request, response } = require('objective-http').server;\nconst { EndpointHandler } = handler.endpoint;\nconst { JsonServerRequest } = request.chunk;\nconst { LogErrorHandler } = handler.error;"}],"quickstart":{"code":"const { server: autoconfigServer } = require('objective-http').server.autoconfig;\nconst { env } = require('node:process');\n\nclass MyEndpoint {\n    route = {\n        method: 'GET',\n        path: '/hello'\n    }\n\n    async handle(request) {\n        console.log(`Received request for: ${request.url}`);\n        try {\n            // Simulate some async processing\n            await new Promise(resolve => setTimeout(resolve, 50));\n            return {\n                status: 200,\n                body: 'Hello, Objective HTTP!'\n            };\n        \n        } catch (e) {\n            console.error('Error handling request:', e);\n            return {\n                status: 500,\n                body: 'Internal server error'\n            };\n        }\n    }\n}\n\n// Start the server using autoconfig\nautoconfigServer({\n    env: env,\n    endpoints: [\n        new MyEndpoint()\n    ],\n    options: { port: 3000 } // You can pass http.createServer options here\n})\n.then(() => console.log('Objective HTTP server listening on port 3000'))\n.catch(err => console.error('Failed to start server:', err));\n\n// Optional: Keep the process alive or graceful shutdown\n// process.on('SIGINT', () => { console.log('Shutting down...'); process.exit(0); });\n","lang":"javascript","description":"This quickstart demonstrates setting up a basic HTTP server using `objective-http`'s `autoconfig` utility, defining a simple GET endpoint, and starting the server."},"warnings":[{"fix":"Review the README and source code for the correct import paths and destructuring patterns. Update `require()` calls to match the new module structure.","message":"Version 1.3.0 introduced a 'new import signature'. This likely changed how classes and functions were exported, requiring users to update their `require` statements or destructuring paths. Code written for versions prior to 1.3.0 will likely break due to module resolution errors.","severity":"breaking","affected_versions":">=1.3.0 <1.4.0"},{"fix":"For versions 1.x, you would need to implement custom JSON parsing/serialization. For versions 2.x and above, `JsonServerRequest` and `JsonServerResponse` have been re-added, but verify their usage patterns as they might differ from pre-1.4.0 versions.","message":"Version 1.4.0 explicitly 'removed json request and response' functionality. If your application relied on `JsonServerRequest` or `JsonServerResponse` classes in versions before 1.4.0, your code would have broken. Note that these classes were later reintroduced in version 2.x, but with potential API changes.","severity":"breaking","affected_versions":">=1.4.0 <2.0.0"},{"fix":"Prefer the `autoconfig` utility for simpler server setups. When building custom server configurations, carefully follow the provided examples for destructuring the `objective-http.server` object to access nested components.","message":"The library heavily relies on deeply nested object structures for its classes and utilities, especially when not using `autoconfig`. For example, `EndpointHandler` is under `objective-http.server.handler.endpoint.EndpointHandler`. This can lead to verbose `require` statements and makes direct ESM imports challenging or impossible.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the `endpoints` array contains valid instances of classes implementing the `Endpoint` interface (with `route` and `handle` methods). Pass `process.env` or a compatible object as the `env` parameter.","message":"The `autoconfig` utility requires an array of `Endpoint` instances and an `env` object. Forgetting to provide these, or providing them in an incorrect format, can lead to server startup failures or requests not being handled correctly.","severity":"gotcha","affected_versions":">=2.1.2"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Use the correct CommonJS `require` statement: `const { Server } = require('objective-http').server;`","cause":"Attempting to import `Server` using an incorrect ESM syntax or path when the package primarily uses CommonJS `require` with nested exports.","error":"TypeError: (0 , server_1.Server) is not a constructor"},{"fix":"The primary entry point for server components is usually `require('objective-http').server`. Avoid direct path imports like `require('objective-http/server')` unless explicitly documented.","cause":"This error typically occurs when attempting to use a direct path import for a submodule (`objective-http/server`) in a CommonJS context, or if the package's internal structure doesn't expose modules in that specific way for direct import.","error":"Error: Cannot find module 'objective-http/server'"},{"fix":"Ensure that any custom `Endpoint` classes are properly defined and instantiated before being passed to the server configuration. For example, `class MyEndpoint { ... }`.","cause":"When using `autoconfig` or manually configuring the `Server`, an `Endpoint` class (like `MyEndpoint`) is referenced but not defined or correctly imported within the scope.","error":"ReferenceError: MyEndpoint is not defined"}],"ecosystem":"npm","meta_description":null}