Bar JS

BaR (Builder a Response)

Package: @vorlaxen-labs/bar-js v2.0.0 · Zero runtime deps

Framework-agnostic response builder that replaces ad-hoc res.status().json() with a fluent, typed API enforcing a single response contract.

Critical Rules

1. Register bar.handler() before route handlers — injects res.builder and req.bar.ctx.
2. Always call .build() to dispatch — chaining alone does not send a response.
3. Use semantic presets (.as.ok(), .as.created(), etc.) instead of raw status codes.
4. Use .wrap(promise) for async routes — then call .build() or .message(). Do not call .as.ok(undefined) after wrap() — it overwrites resolved data with null.
5. Set environment: 'production' in prod — masks internal error details in wrap().
6. Never invent response fields — follow the envelope schema below.

Response Envelope

Every response follows this shape:

interface IResponse<T = unknown, M = unknown> {
  success: boolean;
  timestamp: string;       // ISO 8601 at build time
  message?: string;
  data: T | null;
  metadata: {
    request_id: string;
    server_time: string;
    status_code: number;
  } & M;
}

• success is true for status 200–399 (unless .forceSuccess() overrides).
• metadata.request_id is auto-generated or read from X-Request-Id / X-Correlation-Id / traceparent.

Quick Start

import express from 'express';
import { BarExpressAdapter } from '@vorlaxen-labs/bar-js';

const app = express();
const bar = new BarExpressAdapter({
  environment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
  logger: console,
});

app.use(bar.handler());
app.use(express.json());

app.get('/api/users/:id', async (req, res) => {
  await res.builder.wrap(userService.findById(req.params.id));
  return res.builder.message('User retrieved').build();
});

Semantic Presets (.as.*)

Common Patterns

Async with wrap

app.post('/api/users', async (req, res) => {
  await res.builder.wrap(userService.create(req.body));
  return res.builder.message('User created').status(201).build();
});

Pagination

return res.builder
  .as.ok(users)
  .paginate(total, page, limit)
  .build();

Conditional chaining

return res.builder
  .as.ok(data)
  .when(includeMeta, b => b.setMeta({ version: '2.0' }))
  .build();

Request tracing

const { request_id, start_time } = req.bar.ctx;
// request_id appears in every response metadata

Middleware Order

1. Trust proxy / CORS
2. bar.handler()          ← injects builder + context
3. express.json()
4. Route handlers
5. Not found middleware
6. Global exception filter

Adapter Options

When NOT to Use BaR

• GraphQL or gRPC exclusively
• Streaming/SSE responses (BaR is JSON-focused)
• API already has a mature, enforced response envelope that cannot change

Reference Documentation