@devindex/api-kit 0.1.0 → 0.2.0

package/README.md

@@ -425,6 +425,41 @@ Every Redis replica upserts the same scheduler and starts an equivalent Worker.
 leader; BullMQ coordinates which Worker receives each occurrence. A new occurrence is produced when
 the previous one starts, so global concurrency serializes slow runs rather than overlapping them.
 
+## `./env`
+
+`createEnvReader()` reads `process.env` and **collects** what is wrong instead of failing on the
+first problem, so a misconfigured deploy reports every missing or malformed variable in one boot
+rather than one per restart. It does not decide how to fail: `issues()` hands the list back and the
+service merges it with its own cross-field rules.
+
+```js
+import { createEnvReader } from '@devindex/api-kit/env';
+
+const env = createEnvReader();
+
+export const config = Object.freeze({
+  port: env.int('PORT', { fallback: 3000 }),
+  mongoUri: env.str('MONGO_URI', { required: true }),
+  driver: env.oneOf('MESSAGING_DRIVER', ['memory', 'bullmq'], { fallback: 'memory' }),
+});
+
+export function assertConfig() {
+  const issues = env.issues();
+  if (issues.length === 0) return;
+
+  for (const issue of issues) console.error(`config: ${issue}`);
+  process.exit(1);
+}
+```
+
+`str`, `int` and `oneOf` take `fallback` (default `null`) and `required` (default `false`), and read
+an empty string as an absent value — a variable left blank in a `.env` is not a value. A rejected
+variable still returns its fallback, so the config object finishes building and `issues()` reports
+everything in one pass.
+
+A reader owns its own list, so config split across several modules is just the reader passed to each
+one, and a test builds its own with `createEnvReader({ PORT: '3000' })` without touching the process.
+
 ## `./runtime`
 
 `onShutdown` wires `SIGINT`/`SIGTERM` to a teardown callback and exits — the one
@@ -449,6 +484,21 @@ A second signal arriving mid-drain is a no-op. A `close` that throws exits `1` a
 logging; one that hangs past `timeoutMs` (default `10_000`) force-exits `1` so a stuck
 drain cannot wedge the process. `signals` defaults to `['SIGINT', 'SIGTERM']`.
 
+`onFatalError` covers the other exit: an uncaught exception or an unhandled rejection is
+logged as fatal and the process exits `1`.
+
+```js
+import { onFatalError } from '@devindex/api-kit/runtime';
+
+onFatalError({ logger });
+```
+
+It deliberately does not run the shutdown callback. After an uncaught throw the process
+state is undefined, and a teardown running over it can hang or corrupt what it touches —
+exiting fast leaves the restart to the supervisor. The logger is flushed first, so a
+`pretty` transport writing from a worker thread does not lose the line that explains the
+crash.
+
 ## Tests
 
 The default suite exercises every memory path and skips integration tests when Redis is absent:

package/env/index.js

@@ -0,0 +1,50 @@
+/**
+ * Reads environment variables, collecting every problem instead of failing on
+ * the first one, so a misconfigured boot reports all of them at once.
+ *
+ * @param {Record<string, string|undefined>} [source=process.env]
+ * @return {{str: Function, int: Function, oneOf: Function, issues: Function}}
+ *   Frozen reader owning its own issue list.
+ */
+export function createEnvReader(source = process.env) {
+  const issues = [];
+
+  // An empty string is a variable someone left blank in a .env, not a value.
+  function read(name, required) {
+    const value = source[name];
+    if (value === undefined || value === '') {
+      if (required) issues.push(`${name} is required`);
+      return null;
+    }
+    return value;
+  }
+
+  function str(name, { fallback = null, required = false } = {}) {
+    return read(name, required) ?? fallback;
+  }
+
+  function int(name, { fallback = null, required = false } = {}) {
+    const raw = read(name, required);
+    if (raw === null) return fallback;
+    const value = Number.parseInt(raw, 10);
+    if (Number.isNaN(value)) {
+      issues.push(`${name} must be an integer`);
+      return fallback;
+    }
+    return value;
+  }
+
+  function oneOf(name, values, { fallback = null, required = false } = {}) {
+    const raw = read(name, required);
+    if (raw === null) return fallback;
+    if (!values.includes(raw)) {
+      issues.push(`${name} must be one of ${values.join(', ')}`);
+      return fallback;
+    }
+    return raw;
+  }
+
+  // A copy: the caller merges these with its own cross-field checks, and must
+  // not be able to edit the reader's list while doing it.
+  return Object.freeze({ str, int, oneOf, issues: () => [...issues] });
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@devindex/api-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Building blocks for Fastify services: typed domain errors, HTTP plugins, logging and background runtime",
   "type": "module",
   "exports": {
     "./context": "./context/index.js",
+    "./env": "./env/index.js",
     "./errors": "./errors/index.js",
     "./events": "./events/index.js",
     "./http": "./http/index.js",
@@ -16,6 +17,7 @@
   },
   "files": [
     "context",
+    "env",
     "errors",
     "events",
     "http",

package/runtime/index.js

@@ -35,3 +35,25 @@ export function onShutdown(close, { signals = ['SIGINT', 'SIGTERM'], timeoutMs =
     process.once(signal, () => handle(signal));
   }
 }
+
+/**
+ * Logs an uncaught exception or unhandled rejection as fatal, then exits 1.
+ *
+ * @param {object} [options]
+ * @param {{ fatal: Function, flush?: Function }} [options.logger] - Logs the error before exiting.
+ */
+export function onFatalError({ logger } = {}) {
+  // No teardown here, unlike `onShutdown`: after an uncaught throw the process
+  // state is undefined, and a `close` running over it can hang or corrupt what
+  // it touches. Exiting fast leaves the restart to the supervisor.
+  const handle = (event) => (error) => {
+    logger?.fatal({ err: error }, event);
+    // A pino transport writes from a worker thread, so exiting on the next line
+    // would drop the very line explaining why the process died.
+    logger?.flush?.();
+    process.exit(1);
+  };
+
+  process.on('uncaughtException', handle('uncaught exception'));
+  process.on('unhandledRejection', handle('unhandled rejection'));
+}