@dbcdk/febib-shared

Shared TypeScript libraries for Febib projects.

@dbcdk/febib-shared is a set of opinionated shared libraries for Febib projects. The goal is to standardize core patterns across projects, so we log the same way, reuse optimized building blocks, and avoid each project reinventing infrastructure details.

Install

npm install @dbcdk/febib-shared

Usage

import fetchClient from "@dbcdk/febib-shared/server/fetch";
import { configureFetch } from "@dbcdk/febib-shared/server/fetch";
import { configureRedis, withRedisCache } from "@dbcdk/febib-shared/server/redis";

configureFetch({
  logger: {
    info: (message, meta) => console.info(message, meta),
    error: (message, meta) => console.error(message, meta),
  },
  modifyHeaders: (oldHeaders) => {
    oldHeaders.set("x-correlation-id", "request-123");
    return oldHeaders;
  },
});

const response = await fetchClient("https://example.com/api", {
  method: "GET",
  headers: {
    "x-correlation-id": "abc-123",
  },
});
const json = await response.json<{ ok: boolean }>();

configureRedis({
  logger: {
    info: (message, meta) => console.info(message, meta),
  },
});

const cachedLookup = withRedisCache(
  async (id: string) => ({ id, value: "example" }),
  {
    ttlSeconds: 60,
    keyPrefix: "lookup",
    key: (id) => id,
  },
);

Subpath exports are available as:

• @dbcdk/febib-shared/server/fetch
• @dbcdk/febib-shared/server/redis

febib-serve

febib-serve is included as a CLI in this package. It starts your app command on an internal port and exposes a proxy on the public PORT with shared logging, metrics, /health, and /api/errorLogger.

Example:

febib-serve next dev

Other examples:

febib-serve next start
febib-serve fastify start -w app.js

If the command is next or fastify, febib-serve auto-injects --port unless you already provided --port/-p yourself.

Environment variables

fetch can run without environment variables, but for outbound traffic through proxy you can configure:

• HTTPS_PROXY - proxy URL for HTTPS requests.
• NO_PROXY - comma-separated hosts that should bypass proxy.
• NODE_USE_ENV_PROXY - set to 1 to let Node fetch use env proxy settings.

redis reads these environment variables:

• REDIS_CLUSTER_HOST - Redis cluster host. Default: localhost.
• REDIS_CLUSTER_PORT - Redis cluster port. Default: 6379.
• REDIS_KEY_PREFIX - Optional key prefix used by Redis client. Default: empty string.
• REDIS_USE_MOCK - Set to true to force ioredis-mock instead of real Redis.
• NODE_ENV - If set to test, Redis automatically uses mock mode.
• JEST_WORKER_ID - If present (set by Jest), Redis automatically uses mock mode.

For production usage you should normally set REDIS_CLUSTER_HOST, REDIS_CLUSTER_PORT, and REDIS_KEY_PREFIX.

febib-serve reads these environment variables:

• PORT - Public proxy port exposed by febib-serve. Default: 3000.
• FEBIB_SERVE_HEALTH_PORT - Optional dedicated port for GET /health. Default: disabled (0). If set to same value as PORT, no dedicated health listener is started.
• NODE_ENV - Runtime mode forwarded to both proxy and app process. Default: development.
• FEBIB_SERVE_UPSTREAM_TIMEOUT_MS - Upstream request timeout in ms. Default: 30000.
• FEBIB_SERVE_HEALTH_GRACE_WINDOW_SECONDS - Startup grace period before health threshold failures can fail /health. Default: 30.
• FEBIB_SERVE_THRESHOLD_JS_CLIENT_ERROR_COUNT - Max rolling 5m client JS errors (JS_CLIENT_ERROR). Default: 50. Set 0 to disable.
• FEBIB_SERVE_THRESHOLD_HTTP_5XX_COUNT - Max rolling 5m HTTP 5xx count. Default: 50. Set 0 to disable.
• FEBIB_SERVE_THRESHOLD_APP_CPU_USAGE - Max rolling app CPU usage percentage in process metrics. Default: 100. Set 0 to disable.
• FEBIB_SERVE_THRESHOLD_RESPONSE_TIME_P95_MS - Max rolling 5m response-time p95 in ms. Default: 3000. Set 0 to disable.
• FEBIB_SERVE_CLIENT_JS_ERROR_BODY_LIMIT_BYTES - Max accepted body size for /api/errorLogger. Default: 32768.

febib-serve always injects a lightweight Node request probe into the app process (via NODE_OPTIONS) and logs serviceReceiveDelayMs and serviceTimeToFirstByteMs under responseObj.timings. To distinguish runtime logs from outbound helper calls, request completed events include a top-level source field ("febib-serve" for runtime proxy traffic, "fetch" for @dbcdk/febib-shared/server/fetch calls). For each incoming request, febib-serve generates a requestId, logs it as top-level requestId, and forwards it to upstream services in the x-request-id header.

FEBIB_SERVE_UPSTREAM_URL and FEBIB_SERVE_WORKSPACE_ROOT are internal runtime variables controlled by febib-serve and are always overridden by the wrapper.

Development

npm install
npm run build