@erenthedeveloper0/zen 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Eren Sümer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+<p align="center">
+  <img alt="zen.js — a compiler-first web framework" src="https://raw.githubusercontent.com/erenthedeveloper0/zen/main/.github/images/banner-dark.png" width="100%">
+</p>
+
+# @erenthedeveloper0/zen
+
+**A compiler-first web framework for Node.js.** Express-simple, Fastify-fast,
+typed end to end.
+
+> **Alpha.** The API will change before `1.0`. Do not put this in production yet — see
+> [the status section](https://github.com/erenthedeveloper0/zen#status).
+
+```bash
+npm install @erenthedeveloper0/zen@alpha
+```
+
+```ts
+import { zen } from '@erenthedeveloper0/zen'
+
+const app = zen()
+
+app.get('/', () => 'Hello world')
+
+await app.listen(3000)
+```
+
+Two concepts: `app.METHOD(path, handler)`, and **the handler returns the
+response**. There is no response object to learn.
+
+## What you get
+
+Registration is a source language: `ready()` freezes the application and
+compiles the router, every route's pipeline, its validators and response
+serializers, and the request context's own memory layout into generated
+JavaScript. Stages a route does not use are not emitted at all.
+
+- **Typed routes** from the path template and your schemas — Zod, Valibot and
+  ArkType work through [Standard Schema](https://standardschema.dev) with no
+  adapter.
+- **Response contracts**: a route that declares `response: { 200: User }`
+  compiles a serializer that *cannot* emit a field `User` does not declare.
+- **Deadlines**, **health and readiness endpoints**, **validated configuration**,
+  **content negotiation**, **server-sent events**, **file responses** with
+  `ETag`/`Range`, and **graceful shutdown** that drains before it refuses.
+- **Boot-time diagnostics**, aggregated: every registration problem in one run,
+  each with a fix.
+
+```ts
+import { zen } from '@erenthedeveloper0/zen'
+import { z } from 'zod'
+
+const app = zen({ timeout: '30s' })
+
+app.get('/users/:id<int>', {
+  response: { 200: z.object({ id: z.number(), name: z.string() }) },
+}, async (ctx) => {
+  const user = await db.users.find(ctx.params.id)   // ctx.params.id is a number
+  return user                                       // a passwordHash on it never reaches the wire
+})
+
+await app.listen()                                  // address from config.server
+```
+
+## This package
+
+`@erenthedeveloper0/zen` wires together:
+
+| Package | Role |
+| --- | --- |
+| [`@erenthedeveloper0/zen-core`](https://www.npmjs.com/package/@erenthedeveloper0/zen-core) | registries, compilers, runtime, errors — zero dependencies |
+| [`@erenthedeveloper0/zen-router`](https://www.npmjs.com/package/@erenthedeveloper0/zen-router) | the compiled radix router |
+| [`@erenthedeveloper0/zen-adapter-node`](https://www.npmjs.com/package/@erenthedeveloper0/zen-adapter-node) | Node's `http` server |
+| [`@erenthedeveloper0/zen-middleware`](https://www.npmjs.com/package/@erenthedeveloper0/zen-middleware) | CORS, security headers, request ids, rate limiting |
+
+and re-exports all of them, so one import is enough. It also supplies the two
+things only a Node process has: `process.env` as the configuration environment,
+and signal handling — `SIGTERM`/`SIGINT` run the graceful shutdown and exit, and
+an uncaught exception is logged and does the same with exit code 1. Pass
+`lifecycle: false` if something else manages the process.
+
+OpenAPI generation is a separate install:
+[`@erenthedeveloper0/zen-openapi`](https://www.npmjs.com/package/@erenthedeveloper0/zen-openapi).
+
+## Requirements
+
+- Node.js **≥ 22.6**
+- TypeScript **≥ 5.0**, if you use TypeScript
+
+## Documentation
+
+- [README](https://github.com/erenthedeveloper0/zen#readme) — the tour
+- [ARCHITECTURE.md](https://github.com/erenthedeveloper0/zen/blob/main/ARCHITECTURE.md) — the design, and the arguments that lost
+- [Error codes](https://github.com/erenthedeveloper0/zen/blob/main/docs/errors.md)
+- [Examples](https://github.com/erenthedeveloper0/zen/tree/main/examples)
+
+[MIT](https://github.com/erenthedeveloper0/zen/blob/main/LICENSE) © [Eren Sümer](https://github.com/erenthedeveloper0) · [contributors](https://github.com/erenthedeveloper0/zen/blob/main/CONTRIBUTORS.md)

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { ZenApp, type HostLifecycle, type ZenOptions } from '@erenthedeveloper0/zen-core';
+/**
+ * The meta-package — rfcs/0001 §24.1.
+ *
+ * Beginners install one thing (`zen`); experts install six (`@erenthedeveloper0/zen-core`,
+ * `@erenthedeveloper0/zen-router`, an adapter, …). This module is the *only* place the three
+ * are wired together, which is what keeps `@erenthedeveloper0/zen-core` free of any router or
+ * platform dependency.
+ */
+export type ZenAppOptions<C = Record<string, never>> = Partial<Omit<ZenOptions<C>, 'router' | 'pathParser' | 'lifecycle'>> & {
+    readonly router?: ZenOptions['router'] | undefined;
+    readonly pathParser?: ZenOptions['pathParser'] | undefined;
+    /**
+     * Signals and crash handling — §4.5, §12.8. Defaults to
+     * `processLifecycle()`: `SIGTERM`/`SIGINT` drain and exit, an uncaught
+     * error is logged and shuts down with exit 1. `false` leaves the process
+     * alone, for a host that manages it itself.
+     */
+    readonly lifecycle?: HostLifecycle | false | undefined;
+};
+/**
+ * The five-line app:
+ *
+ *     import { zen } from '@erenthedeveloper0/zen'
+ *     const app = zen()
+ *     app.get('/', () => 'Hello world')
+ *     app.listen({ port: 3000 })
+ *
+ * Two concepts — `app.METHOD(path, handler)`, and *the handler returns the
+ * response*. That is one fewer than Express, because there is no response
+ * object to learn (§1.2).
+ */
+export declare function zen<X = {}, C = Record<string, never>>(options?: ZenAppOptions<C>): ZenApp<X & {
+    readonly config: C;
+}>;
+export default zen;
+export * from '@erenthedeveloper0/zen-core';
+export { ZenRouter, parsePath, renderPath, BUILTIN_PARAM_TYPES, analyzeRoutes } from '@erenthedeveloper0/zen-router';
+export { nodeAdapter, NODE_CAPABILITIES, mediaTypeFor, type NodeAdapterOptions } from '@erenthedeveloper0/zen-adapter-node';
+export { processLifecycle, type ProcessLifecycleOptions } from './lifecycle.ts';
+/**
+ * The first-party middleware pack — §24.2's "common middleware" row.
+ *
+ * Re-exported here and importable from `@erenthedeveloper0/zen-middleware` directly; §21.2's
+ * example uses the second form and `examples/middleware` follows it, so both
+ * paths stay exercised.
+ *
+ * Adding this row is what turned `@erenthedeveloper0/zen-core`'s `requestId` — the ULID
+ * generator, exported since 0.1 and imported by nothing outside core — into a
+ * live collision with the plugin of the same name, where `app.use(requestId())`
+ * would have registered a *string* as middleware and failed at compile with a
+ * message about neither. The generator is now `generateRequestId`, which is
+ * what it always was.
+ */
+export * from '@erenthedeveloper0/zen-middleware';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAKpG;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IACjD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC,CAAC,GAAG;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,GAAG,SAAS,CAAA;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,KAAK,GAAG,SAAS,CAAA;CACvD,CAAA;AA4BH;;;;;;;;;;;GAWG;AACH,wBAAgB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EACnD,OAAO,GAAE,aAAa,CAAC,CAAC,CAAM,GAC7B,MAAM,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,CAapC;AAED,eAAe,GAAG,CAAA;AAGlB,cAAc,6BAA6B,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AACpH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,qCAAqC,CAAA;AAC3H,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAE/E;;;;;;;;;;;;;GAaG;AACH,cAAc,mCAAmC,CAAA"}

package/dist/index.js

@@ -0,0 +1,76 @@
+import { createApp, ZenApp } from '@erenthedeveloper0/zen-core';
+import { ZenRouter, parsePath } from '@erenthedeveloper0/zen-router';
+import { nodeAdapter } from '@erenthedeveloper0/zen-adapter-node';
+import { processLifecycle } from "./lifecycle.js";
+/**
+ * The process environment, or nothing — rfcs/0001 §16.1 layer 6.
+ *
+ * This is the one line in the project that reaches for `process`, and it is
+ * here rather than in `@erenthedeveloper0/zen-core` on purpose: `process` does not exist on
+ * workerd, where the environment arrives as an argument to the fetch handler,
+ * so a core that read it would be a core that cannot run there (§3.3 B2). The
+ * meta-package already knows it is on Node — it imports the Node adapter — so
+ * it is the right place to know where the environment lives, and an app that
+ * wants a different source passes `env:` explicitly.
+ *
+ * Read through `globalThis` rather than the bare identifier so that a runtime
+ * without it produces `{}` instead of a `ReferenceError` on import.
+ */
+function processEnv() {
+    const global = globalThis;
+    return global.process?.env ?? {};
+}
+const defaultPathParser = {
+    parse(path) {
+        const parsed = parsePath(path);
+        return { path: parsed.path, segments: parsed.segments };
+    },
+};
+/**
+ * The five-line app:
+ *
+ *     import { zen } from '@erenthedeveloper0/zen'
+ *     const app = zen()
+ *     app.get('/', () => 'Hello world')
+ *     app.listen({ port: 3000 })
+ *
+ * Two concepts — `app.METHOD(path, handler)`, and *the handler returns the
+ * response*. That is one fewer than Express, because there is no response
+ * object to learn (§1.2).
+ */
+export function zen(options = {}) {
+    return createApp({
+        ...options,
+        router: options.router ?? new ZenRouter(),
+        pathParser: options.pathParser ?? defaultPathParser,
+        adapter: options.adapter ?? nodeAdapter(),
+        // §16.1 layer 6. Explicit `env` — including a list of `.env` sources —
+        // always wins; this is only the default nobody should have to write.
+        env: options.env ?? processEnv(),
+        // §4.5, §12.8 — installed at `listen()`, so an app that is only ever
+        // `inject()`ed in a test never touches the process.
+        lifecycle: options.lifecycle === false ? undefined : (options.lifecycle ?? processLifecycle()),
+    });
+}
+export default zen;
+// Re-export the full public surface so `import { … } from '@erenthedeveloper0/zen'` is enough.
+export * from '@erenthedeveloper0/zen-core';
+export { ZenRouter, parsePath, renderPath, BUILTIN_PARAM_TYPES, analyzeRoutes } from '@erenthedeveloper0/zen-router';
+export { nodeAdapter, NODE_CAPABILITIES, mediaTypeFor } from '@erenthedeveloper0/zen-adapter-node';
+export { processLifecycle } from "./lifecycle.js";
+/**
+ * The first-party middleware pack — §24.2's "common middleware" row.
+ *
+ * Re-exported here and importable from `@erenthedeveloper0/zen-middleware` directly; §21.2's
+ * example uses the second form and `examples/middleware` follows it, so both
+ * paths stay exercised.
+ *
+ * Adding this row is what turned `@erenthedeveloper0/zen-core`'s `requestId` — the ULID
+ * generator, exported since 0.1 and imported by nothing outside core — into a
+ * live collision with the plugin of the same name, where `app.use(requestId())`
+ * would have registered a *string* as middleware and failed at compile with a
+ * message about neither. The generator is now `generateRequestId`, which is
+ * what it always was.
+ */
+export * from '@erenthedeveloper0/zen-middleware';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAuC,MAAM,6BAA6B,CAAA;AACpG,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAuBjD;;;;;;;;;;;;;GAaG;AACH,SAAS,UAAU;IACjB,MAAM,MAAM,GAAG,UAAwE,CAAA;IACvF,OAAO,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,CAAA;AAClC,CAAC;AAED,MAAM,iBAAiB,GAA6B;IAClD,KAAK,CAAC,IAAY;QAChB,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;QAC9B,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAA;IACzD,CAAC;CACF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,GAAG,CACjB,UAA4B,EAAE;IAE9B,OAAO,SAAS,CAAO;QACrB,GAAG,OAAO;QACV,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,SAAS,EAAE;QACzC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,iBAAiB;QACnD,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,WAAW,EAAE;QACzC,uEAAuE;QACvE,qEAAqE;QACrE,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE;QAChC,qEAAqE;QACrE,oDAAoD;QACpD,SAAS,EAAE,OAAO,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,gBAAgB,EAAE,CAAC;KAC/F,CAAC,CAAA;AACJ,CAAC;AAED,eAAe,GAAG,CAAA;AAElB,+FAA+F;AAC/F,cAAc,6BAA6B,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AACpH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,YAAY,EAA2B,MAAM,qCAAqC,CAAA;AAC3H,OAAO,EAAE,gBAAgB,EAAgC,MAAM,gBAAgB,CAAA;AAE/E;;;;;;;;;;;;;GAaG;AACH,cAAc,mCAAmC,CAAA"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,45 @@
+import type { HostLifecycle } from '@erenthedeveloper0/zen-core';
+export interface ProcessLifecycleOptions {
+    /**
+     * Signals that start a graceful shutdown. `SIGTERM` is what Kubernetes, ECS,
+     * systemd and `docker stop` send; `SIGINT` is Ctrl+C.
+     */
+    readonly signals?: readonly string[] | undefined;
+    /**
+     * Exit once shutdown finishes — 0 after a signal, 1 after a crash. On by
+     * default, because a process whose server has closed and whose pools are
+     * disposed has nothing left to do, and one that lingers holds its container.
+     */
+    readonly exit?: boolean | undefined;
+    /**
+     * §12.8: on an uncaught exception or unhandled rejection, log it at `fatal`
+     * and shut down with exit code 1. On by default.
+     */
+    readonly crashes?: boolean | undefined;
+    /** Called when a shutdown signal arrives, before anything closes. */
+    readonly onSignal?: ((signal: string) => void) | undefined;
+}
+/**
+ * The Node process's side of the lifecycle — rfcs/0001 §4.5, §12.8.
+ *
+ * `zen()` installs this by default when the app starts listening. Before it
+ * existed, §4.5 described what happens "on SIGTERM" and nothing listened for
+ * one: Node's default action ended the process on the spot, so readiness never
+ * went red, the drain window never opened, and `onClose` never ran — on every
+ * rolling deploy, which is the exact situation §4.5 exists for. Every example
+ * in this repository wrote the same four lines to fill the gap, and two did
+ * not.
+ *
+ *   - **First signal:** run `app.close()` — readiness drains, the socket
+ *     closes, in-flight requests finish, `onClose` runs, services dispose — then
+ *     exit 0.
+ *   - **Second signal while that is in progress:** exit now. Ctrl+C twice
+ *     means "stop waiting", and a shutdown stuck behind a hung connection
+ *     should not be un-killable from a terminal.
+ *   - **An uncaught exception or unhandled rejection:** log it at `fatal`, then
+ *     the same graceful shutdown with exit 1. Zen does not keep serving from a
+ *     process whose state is unknown (§12.8) — that instinct is how corrupted
+ *     data gets written — but it does let requests already in flight finish.
+ */
+export declare function processLifecycle(options?: ProcessLifecycleOptions): HostLifecycle;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE7E,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;IAChD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACtC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CAC3D;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,aAAa,CAwDrF"}

package/dist/lifecycle.js

@@ -0,0 +1,75 @@
+/**
+ * The Node process's side of the lifecycle — rfcs/0001 §4.5, §12.8.
+ *
+ * `zen()` installs this by default when the app starts listening. Before it
+ * existed, §4.5 described what happens "on SIGTERM" and nothing listened for
+ * one: Node's default action ended the process on the spot, so readiness never
+ * went red, the drain window never opened, and `onClose` never ran — on every
+ * rolling deploy, which is the exact situation §4.5 exists for. Every example
+ * in this repository wrote the same four lines to fill the gap, and two did
+ * not.
+ *
+ *   - **First signal:** run `app.close()` — readiness drains, the socket
+ *     closes, in-flight requests finish, `onClose` runs, services dispose — then
+ *     exit 0.
+ *   - **Second signal while that is in progress:** exit now. Ctrl+C twice
+ *     means "stop waiting", and a shutdown stuck behind a hung connection
+ *     should not be un-killable from a terminal.
+ *   - **An uncaught exception or unhandled rejection:** log it at `fatal`, then
+ *     the same graceful shutdown with exit 1. Zen does not keep serving from a
+ *     process whose state is unknown (§12.8) — that instinct is how corrupted
+ *     data gets written — but it does let requests already in flight finish.
+ */
+export function processLifecycle(options = {}) {
+    const signals = options.signals ?? ['SIGTERM', 'SIGINT'];
+    const exit = options.exit ?? true;
+    const crashes = options.crashes ?? true;
+    return {
+        install(control) {
+            const proc = globalThis.process;
+            if (proc === undefined || typeof proc.on !== 'function')
+                return () => { };
+            let stopping = false;
+            const shutdown = (reason, code) => {
+                if (stopping) {
+                    control.log.warn({ reason }, 'second shutdown request while shutting down; exiting now');
+                    proc.exit(code === 0 ? 130 : code);
+                    return;
+                }
+                stopping = true;
+                control.close(reason).then(() => { if (exit)
+                    proc.exit(code); }, (error) => {
+                    control.log.fatal({ err: error }, 'shutdown failed');
+                    proc.exit(1);
+                });
+            };
+            const onSignal = (signal) => {
+                options.onSignal?.(signal);
+                shutdown(signal, 0);
+            };
+            const onException = (error) => {
+                control.log.fatal({ err: error }, 'uncaught exception; shutting down');
+                shutdown('uncaughtException', 1);
+            };
+            const onRejection = (reason) => {
+                control.log.fatal({ err: reason }, 'unhandled promise rejection; shutting down');
+                shutdown('unhandledRejection', 1);
+            };
+            for (const signal of signals)
+                proc.on(signal, onSignal);
+            if (crashes) {
+                proc.on('uncaughtException', onException);
+                proc.on('unhandledRejection', onRejection);
+            }
+            return () => {
+                for (const signal of signals)
+                    proc.off(signal, onSignal);
+                if (crashes) {
+                    proc.off('uncaughtException', onException);
+                    proc.off('unhandledRejection', onRejection);
+                }
+            };
+        },
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;IACpE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAA;IACjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAA;IAEvC,OAAO;QACL,OAAO,CAAC,OAAoB;YAC1B,MAAM,IAAI,GAAI,UAA2C,CAAC,OAAO,CAAA;YACjE,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,UAAU;gBAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAA;YAExE,IAAI,QAAQ,GAAG,KAAK,CAAA;YAEpB,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,IAAY,EAAQ,EAAE;gBACtD,IAAI,QAAQ,EAAE,CAAC;oBACb,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,0DAA0D,CAAC,CAAA;oBACxF,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;oBAClC,OAAM;gBACR,CAAC;gBACD,QAAQ,GAAG,IAAI,CAAA;gBACf,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CACxB,GAAG,EAAE,GAAG,IAAI,IAAI;oBAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAC,CAAC,EACnC,CAAC,KAAc,EAAE,EAAE;oBACjB,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,iBAAiB,CAAC,CAAA;oBACpD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;gBACd,CAAC,CACF,CAAA;YACH,CAAC,CAAA;YAED,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAQ,EAAE;gBACxC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAA;gBAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;YACrB,CAAC,CAAA;YACD,MAAM,WAAW,GAAG,CAAC,KAAc,EAAQ,EAAE;gBAC3C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,mCAAmC,CAAC,CAAA;gBACtE,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAA;YAClC,CAAC,CAAA;YACD,MAAM,WAAW,GAAG,CAAC,MAAe,EAAQ,EAAE;gBAC5C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,4CAA4C,CAAC,CAAA;gBAChF,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAA;YACnC,CAAC,CAAA;YAED,KAAK,MAAM,MAAM,IAAI,OAAO;gBAAE,IAAI,CAAC,EAAE,CAAC,MAAgB,EAAE,QAAQ,CAAC,CAAA;YACjE,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,EAAE,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAA;gBACzC,IAAI,CAAC,EAAE,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAA;YAC5C,CAAC;YAED,OAAO,GAAG,EAAE;gBACV,KAAK,MAAM,MAAM,IAAI,OAAO;oBAAE,IAAI,CAAC,GAAG,CAAC,MAAgB,EAAE,QAAQ,CAAC,CAAA;gBAClE,IAAI,OAAO,EAAE,CAAC;oBACZ,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAA;oBAC1C,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAA;gBAC7C,CAAC;YACH,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@erenthedeveloper0/zen",
+  "version": "0.1.0-alpha.1",
+  "description": "Zen: a compiler-first web framework for Node.js. Routing, validation, serialization and the request context are compiled at boot.",
+  "keywords": [
+    "web",
+    "framework",
+    "http",
+    "server",
+    "api",
+    "rest",
+    "typescript",
+    "openapi",
+    "validation",
+    "compiler",
+    "zen"
+  ],
+  "homepage": "https://github.com/erenthedeveloper0/zen/tree/main/packages/zen#readme",
+  "bugs": {
+    "url": "https://github.com/erenthedeveloper0/zen/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erenthedeveloper0/zen.git",
+    "directory": "packages/zen"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Eren Sümer",
+    "url": "https://github.com/erenthedeveloper0"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "node --test \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@erenthedeveloper0/zen-adapter-node": "0.1.0-alpha.1",
+    "@erenthedeveloper0/zen-core": "0.1.0-alpha.1",
+    "@erenthedeveloper0/zen-middleware": "0.1.0-alpha.1",
+    "@erenthedeveloper0/zen-router": "0.1.0-alpha.1"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+import { createApp, ZenApp, type HostLifecycle, type ZenOptions } from '@erenthedeveloper0/zen-core'
+import { ZenRouter, parsePath } from '@erenthedeveloper0/zen-router'
+import { nodeAdapter } from '@erenthedeveloper0/zen-adapter-node'
+import { processLifecycle } from './lifecycle.ts'
+
+/**
+ * The meta-package — rfcs/0001 §24.1.
+ *
+ * Beginners install one thing (`zen`); experts install six (`@erenthedeveloper0/zen-core`,
+ * `@erenthedeveloper0/zen-router`, an adapter, …). This module is the *only* place the three
+ * are wired together, which is what keeps `@erenthedeveloper0/zen-core` free of any router or
+ * platform dependency.
+ */
+export type ZenAppOptions<C = Record<string, never>> =
+  Partial<Omit<ZenOptions<C>, 'router' | 'pathParser' | 'lifecycle'>> & {
+    readonly router?: ZenOptions['router'] | undefined
+    readonly pathParser?: ZenOptions['pathParser'] | undefined
+    /**
+     * Signals and crash handling — §4.5, §12.8. Defaults to
+     * `processLifecycle()`: `SIGTERM`/`SIGINT` drain and exit, an uncaught
+     * error is logged and shuts down with exit 1. `false` leaves the process
+     * alone, for a host that manages it itself.
+     */
+    readonly lifecycle?: HostLifecycle | false | undefined
+  }
+
+/**
+ * The process environment, or nothing — rfcs/0001 §16.1 layer 6.
+ *
+ * This is the one line in the project that reaches for `process`, and it is
+ * here rather than in `@erenthedeveloper0/zen-core` on purpose: `process` does not exist on
+ * workerd, where the environment arrives as an argument to the fetch handler,
+ * so a core that read it would be a core that cannot run there (§3.3 B2). The
+ * meta-package already knows it is on Node — it imports the Node adapter — so
+ * it is the right place to know where the environment lives, and an app that
+ * wants a different source passes `env:` explicitly.
+ *
+ * Read through `globalThis` rather than the bare identifier so that a runtime
+ * without it produces `{}` instead of a `ReferenceError` on import.
+ */
+function processEnv(): Readonly<Record<string, string | undefined>> {
+  const global = globalThis as { process?: { env?: Record<string, string | undefined> } }
+  return global.process?.env ?? {}
+}
+
+const defaultPathParser: ZenOptions['pathParser'] = {
+  parse(path: string) {
+    const parsed = parsePath(path)
+    return { path: parsed.path, segments: parsed.segments }
+  },
+}
+
+/**
+ * The five-line app:
+ *
+ *     import { zen } from '@erenthedeveloper0/zen'
+ *     const app = zen()
+ *     app.get('/', () => 'Hello world')
+ *     app.listen({ port: 3000 })
+ *
+ * Two concepts — `app.METHOD(path, handler)`, and *the handler returns the
+ * response*. That is one fewer than Express, because there is no response
+ * object to learn (§1.2).
+ */
+export function zen<X = {}, C = Record<string, never>>(
+  options: ZenAppOptions<C> = {},
+): ZenApp<X & { readonly config: C }> {
+  return createApp<X, C>({
+    ...options,
+    router: options.router ?? new ZenRouter(),
+    pathParser: options.pathParser ?? defaultPathParser,
+    adapter: options.adapter ?? nodeAdapter(),
+    // §16.1 layer 6. Explicit `env` — including a list of `.env` sources —
+    // always wins; this is only the default nobody should have to write.
+    env: options.env ?? processEnv(),
+    // §4.5, §12.8 — installed at `listen()`, so an app that is only ever
+    // `inject()`ed in a test never touches the process.
+    lifecycle: options.lifecycle === false ? undefined : (options.lifecycle ?? processLifecycle()),
+  })
+}
+
+export default zen
+
+// Re-export the full public surface so `import { … } from '@erenthedeveloper0/zen'` is enough.
+export * from '@erenthedeveloper0/zen-core'
+export { ZenRouter, parsePath, renderPath, BUILTIN_PARAM_TYPES, analyzeRoutes } from '@erenthedeveloper0/zen-router'
+export { nodeAdapter, NODE_CAPABILITIES, mediaTypeFor, type NodeAdapterOptions } from '@erenthedeveloper0/zen-adapter-node'
+export { processLifecycle, type ProcessLifecycleOptions } from './lifecycle.ts'
+
+/**
+ * The first-party middleware pack — §24.2's "common middleware" row.
+ *
+ * Re-exported here and importable from `@erenthedeveloper0/zen-middleware` directly; §21.2's
+ * example uses the second form and `examples/middleware` follows it, so both
+ * paths stay exercised.
+ *
+ * Adding this row is what turned `@erenthedeveloper0/zen-core`'s `requestId` — the ULID
+ * generator, exported since 0.1 and imported by nothing outside core — into a
+ * live collision with the plugin of the same name, where `app.use(requestId())`
+ * would have registered a *string* as middleware and failed at compile with a
+ * message about neither. The generator is now `generateRequestId`, which is
+ * what it always was.
+ */
+export * from '@erenthedeveloper0/zen-middleware'

package/src/lifecycle.ts

@@ -0,0 +1,104 @@
+import type { HostControl, HostLifecycle } from '@erenthedeveloper0/zen-core'
+
+export interface ProcessLifecycleOptions {
+  /**
+   * Signals that start a graceful shutdown. `SIGTERM` is what Kubernetes, ECS,
+   * systemd and `docker stop` send; `SIGINT` is Ctrl+C.
+   */
+  readonly signals?: readonly string[] | undefined
+  /**
+   * Exit once shutdown finishes — 0 after a signal, 1 after a crash. On by
+   * default, because a process whose server has closed and whose pools are
+   * disposed has nothing left to do, and one that lingers holds its container.
+   */
+  readonly exit?: boolean | undefined
+  /**
+   * §12.8: on an uncaught exception or unhandled rejection, log it at `fatal`
+   * and shut down with exit code 1. On by default.
+   */
+  readonly crashes?: boolean | undefined
+  /** Called when a shutdown signal arrives, before anything closes. */
+  readonly onSignal?: ((signal: string) => void) | undefined
+}
+
+type Signal = Parameters<NodeJS.Process['on']>[0]
+
+/**
+ * The Node process's side of the lifecycle — rfcs/0001 §4.5, §12.8.
+ *
+ * `zen()` installs this by default when the app starts listening. Before it
+ * existed, §4.5 described what happens "on SIGTERM" and nothing listened for
+ * one: Node's default action ended the process on the spot, so readiness never
+ * went red, the drain window never opened, and `onClose` never ran — on every
+ * rolling deploy, which is the exact situation §4.5 exists for. Every example
+ * in this repository wrote the same four lines to fill the gap, and two did
+ * not.
+ *
+ *   - **First signal:** run `app.close()` — readiness drains, the socket
+ *     closes, in-flight requests finish, `onClose` runs, services dispose — then
+ *     exit 0.
+ *   - **Second signal while that is in progress:** exit now. Ctrl+C twice
+ *     means "stop waiting", and a shutdown stuck behind a hung connection
+ *     should not be un-killable from a terminal.
+ *   - **An uncaught exception or unhandled rejection:** log it at `fatal`, then
+ *     the same graceful shutdown with exit 1. Zen does not keep serving from a
+ *     process whose state is unknown (§12.8) — that instinct is how corrupted
+ *     data gets written — but it does let requests already in flight finish.
+ */
+export function processLifecycle(options: ProcessLifecycleOptions = {}): HostLifecycle {
+  const signals = options.signals ?? ['SIGTERM', 'SIGINT']
+  const exit = options.exit ?? true
+  const crashes = options.crashes ?? true
+
+  return {
+    install(control: HostControl): () => void {
+      const proc = (globalThis as { process?: NodeJS.Process }).process
+      if (proc === undefined || typeof proc.on !== 'function') return () => {}
+
+      let stopping = false
+
+      const shutdown = (reason: string, code: number): void => {
+        if (stopping) {
+          control.log.warn({ reason }, 'second shutdown request while shutting down; exiting now')
+          proc.exit(code === 0 ? 130 : code)
+          return
+        }
+        stopping = true
+        control.close(reason).then(
+          () => { if (exit) proc.exit(code) },
+          (error: unknown) => {
+            control.log.fatal({ err: error }, 'shutdown failed')
+            proc.exit(1)
+          },
+        )
+      }
+
+      const onSignal = (signal: string): void => {
+        options.onSignal?.(signal)
+        shutdown(signal, 0)
+      }
+      const onException = (error: unknown): void => {
+        control.log.fatal({ err: error }, 'uncaught exception; shutting down')
+        shutdown('uncaughtException', 1)
+      }
+      const onRejection = (reason: unknown): void => {
+        control.log.fatal({ err: reason }, 'unhandled promise rejection; shutting down')
+        shutdown('unhandledRejection', 1)
+      }
+
+      for (const signal of signals) proc.on(signal as Signal, onSignal)
+      if (crashes) {
+        proc.on('uncaughtException', onException)
+        proc.on('unhandledRejection', onRejection)
+      }
+
+      return () => {
+        for (const signal of signals) proc.off(signal as Signal, onSignal)
+        if (crashes) {
+          proc.off('uncaughtException', onException)
+          proc.off('unhandledRejection', onRejection)
+        }
+      }
+    },
+  }
+}