@ayepi/updown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philip Diffenderfer
+
+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,73 @@
+# @ayepi/updown
+
+Graceful **startup and shutdown** orchestration. Register named components with
+dependencies; `up()` starts them in dependency order, and `down()` (or a process
+signal) tears them down in reverse through a two-phase **pre → post** shutdown.
+Zero dependencies; works with any runtime.
+
+```sh
+pnpm add @ayepi/updown
+```
+
+```ts
+import { updown } from '@ayepi/updown'
+
+const lc = updown() // SIGTERM/SIGINT trigger shutdown by default
+
+lc.register({ name: 'db', up: () => db.connect(), post: () => db.end() })
+lc.register({
+  name: 'http',
+  deps: ['db'],
+  up: () => server.listen(),
+  pre: () => server.stopAcceptingNewConnections(), // drain
+  post: () => server.close(),                       // teardown
+})
+
+await lc.up()             // db, then http
+app.get('/livez', () => lc.isLive() ? 200 : 503)
+app.get('/readyz', () => lc.isReady() ? 200 : 503)
+// SIGTERM → pre (drain) → isReady=false → post (close) → process exits
+```
+
+## Lifecycle & health
+
+- **`up()`** — starts components in dependency order (independent ones in
+  parallel). Resolves when everything is up; rejects if any `up` throws.
+- **`down()`** — runs all `pre` hooks (reverse-dependency order), then all `post`
+  hooks. Idempotent and best-effort (a throwing hook is reported via `onError`,
+  not fatal). Always resolves.
+- **`isLive()`** — `true` once `up()` finishes and shutdown has **not** been
+  requested. Flips `false` the instant shutdown begins.
+- **`isReady()`** — `true` once `up()` finishes and the **pre** phase hasn't
+  finished. Stays `true` while draining, flips `false` when **post** begins.
+- **`whenDown()`** — resolve when shutdown completes, *without* triggering it
+  (await a signal-driven shutdown: `await lc.whenDown()`).
+- **`list()`** — every component with its `deps`, `status`
+  (`idle → starting → up → pre → post → down`, or `failed`), and last `error`.
+
+## Options
+
+```ts
+updown({
+  signals: ['SIGTERM', 'SIGINT'], // or false to disable
+  exit: true,                     // process.exit(0) after a signal-triggered shutdown
+  timeout: 30_000,              // bound up()/down(); shutdown resolves even if a hook hangs
+  onError: (err, phase, name) => log.error({ err, phase, name }),
+})
+```
+
+A default instance is also exported with top-level `register`/`up`/`down`/
+`whenDown`/`isReady`/`isLive`/`list` for the common single-lifecycle case.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-updown.md`](./ayepi-updown.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/updown) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,210 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/** Process signals that trigger shutdown by default. */
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+/** Exit code used after a signal-triggered shutdown. */
+const EXIT_OK = 0;
+const globalProcess = () => globalThis.process;
+/** Race a promise against a timeout; resolves to `'timeout'` if it elapses first. */
+function withTimeout(p, ms) {
+	if (!ms) return p;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => resolve("timeout"), ms);
+		timer.unref?.();
+		p.then((v) => {
+			clearTimeout(timer);
+			resolve(v);
+		}, (e) => {
+			clearTimeout(timer);
+			reject(e);
+		});
+	});
+}
+/**
+* Create a lifecycle controller. See the {@link UpDown} methods.
+*/
+function updown(opts = {}) {
+	const comps = /* @__PURE__ */ new Map();
+	const status = /* @__PURE__ */ new Map();
+	const errors = /* @__PURE__ */ new Map();
+	let upPromise = null;
+	let downPromise = null;
+	let upDone = false;
+	let downRequested = false;
+	let preDone = false;
+	let resolveDown;
+	const downSignal = new Promise((r) => resolveDown = r);
+	let handlers = [];
+	const fail = (msg) => {
+		throw new Error(`updown: ${msg}`);
+	};
+	const dependentsOf = (name) => [...comps.values()].filter((c) => (c.deps ?? []).includes(name)).map((c) => c.name);
+	function checkGraph() {
+		const visiting = /* @__PURE__ */ new Set();
+		const done = /* @__PURE__ */ new Set();
+		const visit = (n, trail) => {
+			if (done.has(n)) return;
+			if (visiting.has(n)) fail(`dependency cycle: ${[...trail, n].join(" → ")}`);
+			visiting.add(n);
+			for (const d of comps.get(n).deps ?? []) {
+				if (!comps.has(d)) fail(`"${n}" depends on unknown component "${d}"`);
+				visit(d, [...trail, n]);
+			}
+			visiting.delete(n);
+			done.add(n);
+		};
+		for (const n of comps.keys()) visit(n, []);
+	}
+	const proc = opts.process ?? globalProcess();
+	function wireSignals() {
+		const sigs = opts.signals === false ? [] : opts.signals ?? DEFAULT_SIGNALS;
+		if (!proc?.on) return;
+		for (const sig of sigs) {
+			const h = () => void api.down().then(() => opts.exit !== false && proc.exit?.(EXIT_OK));
+			proc.on(sig, h);
+			handlers.push({
+				sig,
+				h
+			});
+		}
+	}
+	function unwireSignals() {
+		for (const { sig, h } of handlers) proc?.off?.(sig, h);
+		handlers = [];
+	}
+	function startUpGraph() {
+		const started = /* @__PURE__ */ new Map();
+		const start = (name) => {
+			const existing = started.get(name);
+			if (existing) return existing;
+			const c = comps.get(name);
+			const p = (async () => {
+				await Promise.all((c.deps ?? []).map(start));
+				if (downRequested) return;
+				status.set(name, "starting");
+				try {
+					await c.up?.();
+					status.set(name, "up");
+				} catch (e) {
+					status.set(name, "failed");
+					errors.set(name, e);
+					opts.onError?.(e, "up", name);
+					throw e;
+				}
+			})();
+			started.set(name, p);
+			return p;
+		};
+		return Promise.all([...comps.keys()].map(start)).then(() => void 0);
+	}
+	/** Run one shutdown phase in reverse-dependency order (dependents tear down before their deps). */
+	async function runPhase(hook) {
+		const done = /* @__PURE__ */ new Map();
+		const run = (name) => {
+			const existing = done.get(name);
+			if (existing) return existing;
+			const c = comps.get(name);
+			const p = (async () => {
+				await Promise.all(dependentsOf(name).map(run));
+				const st = status.get(name);
+				if (st === "idle" || st === "failed") return;
+				status.set(name, hook);
+				const fn = c[hook];
+				if (fn) try {
+					await fn();
+				} catch (e) {
+					status.set(name, "failed");
+					errors.set(name, e);
+					opts.onError?.(e, hook, name);
+					return;
+				}
+				if (hook === "post") status.set(name, "down");
+			})();
+			done.set(name, p);
+			return p;
+		};
+		await Promise.all([...comps.keys()].map(run));
+	}
+	const api = {
+		register(component) {
+			if (upPromise) fail(`cannot register "${component.name}" after up() has started`);
+			if (comps.has(component.name)) fail(`duplicate component "${component.name}"`);
+			comps.set(component.name, component);
+			status.set(component.name, "idle");
+			return api;
+		},
+		up() {
+			if (upPromise) return upPromise;
+			checkGraph();
+			wireSignals();
+			upPromise = (async () => {
+				if (await withTimeout(startUpGraph(), opts.timeout) === "timeout") throw new Error(`updown: up() timed out after ${opts.timeout}ms`);
+				upDone = true;
+			})();
+			return upPromise;
+		},
+		down() {
+			if (downPromise) return downPromise;
+			downRequested = true;
+			downPromise = (async () => {
+				if (upPromise) await upPromise.catch(() => {});
+				if (await withTimeout((async () => {
+					await runPhase("pre");
+					preDone = true;
+					await runPhase("post");
+				})(), opts.timeout) === "timeout") opts.onError?.(/* @__PURE__ */ new Error(`updown: down() timed out after ${opts.timeout}ms`), "post", "*");
+				unwireSignals();
+				resolveDown();
+			})();
+			return downPromise;
+		},
+		whenDown() {
+			return downSignal;
+		},
+		isReady() {
+			return upDone && !preDone;
+		},
+		isLive() {
+			return upDone && !downRequested;
+		},
+		list() {
+			return [...comps.values()].map((c) => {
+				/* v8 ignore next */ const st = status.get(c.name) ?? "idle";
+				const s = {
+					name: c.name,
+					deps: c.deps ?? [],
+					status: st
+				};
+				return errors.has(c.name) ? {
+					...s,
+					error: errors.get(c.name)
+				} : s;
+			});
+		}
+	};
+	return api;
+}
+const instance = updown();
+/** Register a component on the default lifecycle. */
+const register = (component) => instance.register(component);
+/** Start the default lifecycle. */
+const up = () => instance.up();
+/** Shut down the default lifecycle. */
+const down = () => instance.down();
+/** Resolve when the default lifecycle has shut down (without triggering it). */
+const whenDown = () => instance.whenDown();
+/** Readiness of the default lifecycle. */
+const isReady = () => instance.isReady();
+/** Liveness of the default lifecycle. */
+const isLive = () => instance.isLive();
+/** Snapshot of the default lifecycle's components. */
+const list = () => instance.list();
+//#endregion
+exports.down = down;
+exports.isLive = isLive;
+exports.isReady = isReady;
+exports.list = list;
+exports.register = register;
+exports.up = up;
+exports.updown = updown;
+exports.whenDown = whenDown;

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+//#region src/index.d.ts
+/**
+ * # @ayepi/updown
+ *
+ * Graceful **startup and shutdown** orchestration. Register named components with
+ * dependencies; `up()` starts them in dependency order, and `down()` (or a process
+ * signal) tears them down in reverse order through a two-phase **pre → post**
+ * shutdown.
+ *
+ * Health semantics, suitable for liveness/readiness probes:
+ *
+ * - **`isLive()`** — `true` once `up()` finishes and shutdown has **not** been
+ *   requested. Flips `false` the moment shutdown begins.
+ * - **`isReady()`** — `true` once `up()` finishes and the **pre** phase has not yet
+ *   finished. Stays `true` while draining (pre), flips `false` when **post** begins.
+ *
+ * ```ts
+ * import { updown } from '@ayepi/updown'
+ *
+ * const lc = updown()
+ * lc.register({ name: 'db', up: () => db.connect(), post: () => db.end() })
+ * lc.register({ name: 'http', deps: ['db'], up: () => listen(), pre: () => drain(), post: () => close() })
+ *
+ * await lc.up()         // db then http
+ * lc.isReady()          // true
+ * // SIGTERM → pre (drain) → isReady=false → post (close) → process exits
+ * ```
+ *
+ * @module
+ */
+type MaybePromise<T> = T | Promise<T>;
+/** A process signal name (e.g. `'SIGTERM'`). */
+type Signal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGUSR2' | (string & {});
+/** A registered lifecycle component. */
+interface Component {
+  /** Unique name. */
+  readonly name: string;
+  /** Names of components that must be **up** before this one starts (shutdown runs in reverse). */
+  readonly deps?: readonly string[];
+  /** Startup work — `up()` awaits this. */
+  readonly up?: () => MaybePromise<void>;
+  /** Pre-shutdown hook (the drain phase: stop accepting work, finish in-flight). */
+  readonly pre?: () => MaybePromise<void>;
+  /** Post-shutdown hook (the teardown phase: close resources). */
+  readonly post?: () => MaybePromise<void>;
+}
+/** A component's current lifecycle status. */
+type Status = 'idle' | 'starting' | 'up' | 'pre' | 'post' | 'down' | 'failed';
+/** A component's name, deps, current {@link Status}, and last error (if any). */
+interface ComponentStatus {
+  readonly name: string;
+  readonly deps: readonly string[];
+  readonly status: Status;
+  readonly error?: unknown;
+}
+/** The shutdown phase a hook error occurred in. */
+type Phase = 'up' | 'pre' | 'post';
+/** The minimal process surface signal handling uses (the global `process`, or your own). */
+interface ProcessLike {
+  on?(event: string, handler: () => void): void;
+  off?(event: string, handler: () => void): void;
+  exit?(code: number): void;
+}
+/** Options for {@link updown}. */
+interface UpDownOptions {
+  /** Process signals that trigger `down()` (default `['SIGTERM', 'SIGINT']`); `false` to disable. */
+  readonly signals?: readonly Signal[] | false;
+  /** Call `process.exit(0)` after a **signal-triggered** shutdown completes (default `true`). Explicit `down()` never exits. */
+  readonly exit?: boolean;
+  /** Bound `up()` and `down()` each to this many milliseconds (0 / omitted = no timeout). */
+  readonly timeout?: number;
+  /** Called when a component hook throws (shutdown is best-effort and continues). */
+  readonly onError?: (error: unknown, phase: Phase, name: string) => void;
+  /** Override the process object signals attach to (defaults to the global `process`). */
+  readonly process?: ProcessLike;
+}
+/** The lifecycle controller returned by {@link updown}. */
+interface UpDown {
+  /** Register a component. Chainable. Throws after `up()` has started or on a duplicate name. */
+  register(component: Component): UpDown;
+  /** Start all components in dependency order. Idempotent (returns the same promise). Rejects if any `up` throws. */
+  up(): Promise<void>;
+  /** Run the pre then post shutdown phases in reverse-dependency order. Idempotent. Always resolves (best-effort). */
+  down(): Promise<void>;
+  /** Resolve when shutdown has completed — **without** triggering it (await a signal-driven `down()`). */
+  whenDown(): Promise<void>;
+  /** `true` once up completes and the pre phase has not finished (ok to serve traffic). */
+  isReady(): boolean;
+  /** `true` once up completes and shutdown has not been requested. */
+  isLive(): boolean;
+  /** A snapshot of every registered component and its status. */
+  list(): ComponentStatus[];
+}
+/**
+ * Create a lifecycle controller. See the {@link UpDown} methods.
+ */
+declare function updown(opts?: UpDownOptions): UpDown;
+/** Register a component on the default lifecycle. */
+declare const register: (component: Component) => UpDown;
+/** Start the default lifecycle. */
+declare const up: () => Promise<void>;
+/** Shut down the default lifecycle. */
+declare const down: () => Promise<void>;
+/** Resolve when the default lifecycle has shut down (without triggering it). */
+declare const whenDown: () => Promise<void>;
+/** Readiness of the default lifecycle. */
+declare const isReady: () => boolean;
+/** Liveness of the default lifecycle. */
+declare const isLive: () => boolean;
+/** Snapshot of the default lifecycle's components. */
+declare const list: () => ComponentStatus[];
+//#endregion
+export { Component, ComponentStatus, Phase, ProcessLike, Signal, Status, UpDown, UpDownOptions, down, isLive, isReady, list, register, up, updown, whenDown };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+//#region src/index.d.ts
+/**
+ * # @ayepi/updown
+ *
+ * Graceful **startup and shutdown** orchestration. Register named components with
+ * dependencies; `up()` starts them in dependency order, and `down()` (or a process
+ * signal) tears them down in reverse order through a two-phase **pre → post**
+ * shutdown.
+ *
+ * Health semantics, suitable for liveness/readiness probes:
+ *
+ * - **`isLive()`** — `true` once `up()` finishes and shutdown has **not** been
+ *   requested. Flips `false` the moment shutdown begins.
+ * - **`isReady()`** — `true` once `up()` finishes and the **pre** phase has not yet
+ *   finished. Stays `true` while draining (pre), flips `false` when **post** begins.
+ *
+ * ```ts
+ * import { updown } from '@ayepi/updown'
+ *
+ * const lc = updown()
+ * lc.register({ name: 'db', up: () => db.connect(), post: () => db.end() })
+ * lc.register({ name: 'http', deps: ['db'], up: () => listen(), pre: () => drain(), post: () => close() })
+ *
+ * await lc.up()         // db then http
+ * lc.isReady()          // true
+ * // SIGTERM → pre (drain) → isReady=false → post (close) → process exits
+ * ```
+ *
+ * @module
+ */
+type MaybePromise<T> = T | Promise<T>;
+/** A process signal name (e.g. `'SIGTERM'`). */
+type Signal = 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'SIGUSR2' | (string & {});
+/** A registered lifecycle component. */
+interface Component {
+  /** Unique name. */
+  readonly name: string;
+  /** Names of components that must be **up** before this one starts (shutdown runs in reverse). */
+  readonly deps?: readonly string[];
+  /** Startup work — `up()` awaits this. */
+  readonly up?: () => MaybePromise<void>;
+  /** Pre-shutdown hook (the drain phase: stop accepting work, finish in-flight). */
+  readonly pre?: () => MaybePromise<void>;
+  /** Post-shutdown hook (the teardown phase: close resources). */
+  readonly post?: () => MaybePromise<void>;
+}
+/** A component's current lifecycle status. */
+type Status = 'idle' | 'starting' | 'up' | 'pre' | 'post' | 'down' | 'failed';
+/** A component's name, deps, current {@link Status}, and last error (if any). */
+interface ComponentStatus {
+  readonly name: string;
+  readonly deps: readonly string[];
+  readonly status: Status;
+  readonly error?: unknown;
+}
+/** The shutdown phase a hook error occurred in. */
+type Phase = 'up' | 'pre' | 'post';
+/** The minimal process surface signal handling uses (the global `process`, or your own). */
+interface ProcessLike {
+  on?(event: string, handler: () => void): void;
+  off?(event: string, handler: () => void): void;
+  exit?(code: number): void;
+}
+/** Options for {@link updown}. */
+interface UpDownOptions {
+  /** Process signals that trigger `down()` (default `['SIGTERM', 'SIGINT']`); `false` to disable. */
+  readonly signals?: readonly Signal[] | false;
+  /** Call `process.exit(0)` after a **signal-triggered** shutdown completes (default `true`). Explicit `down()` never exits. */
+  readonly exit?: boolean;
+  /** Bound `up()` and `down()` each to this many milliseconds (0 / omitted = no timeout). */
+  readonly timeout?: number;
+  /** Called when a component hook throws (shutdown is best-effort and continues). */
+  readonly onError?: (error: unknown, phase: Phase, name: string) => void;
+  /** Override the process object signals attach to (defaults to the global `process`). */
+  readonly process?: ProcessLike;
+}
+/** The lifecycle controller returned by {@link updown}. */
+interface UpDown {
+  /** Register a component. Chainable. Throws after `up()` has started or on a duplicate name. */
+  register(component: Component): UpDown;
+  /** Start all components in dependency order. Idempotent (returns the same promise). Rejects if any `up` throws. */
+  up(): Promise<void>;
+  /** Run the pre then post shutdown phases in reverse-dependency order. Idempotent. Always resolves (best-effort). */
+  down(): Promise<void>;
+  /** Resolve when shutdown has completed — **without** triggering it (await a signal-driven `down()`). */
+  whenDown(): Promise<void>;
+  /** `true` once up completes and the pre phase has not finished (ok to serve traffic). */
+  isReady(): boolean;
+  /** `true` once up completes and shutdown has not been requested. */
+  isLive(): boolean;
+  /** A snapshot of every registered component and its status. */
+  list(): ComponentStatus[];
+}
+/**
+ * Create a lifecycle controller. See the {@link UpDown} methods.
+ */
+declare function updown(opts?: UpDownOptions): UpDown;
+/** Register a component on the default lifecycle. */
+declare const register: (component: Component) => UpDown;
+/** Start the default lifecycle. */
+declare const up: () => Promise<void>;
+/** Shut down the default lifecycle. */
+declare const down: () => Promise<void>;
+/** Resolve when the default lifecycle has shut down (without triggering it). */
+declare const whenDown: () => Promise<void>;
+/** Readiness of the default lifecycle. */
+declare const isReady: () => boolean;
+/** Liveness of the default lifecycle. */
+declare const isLive: () => boolean;
+/** Snapshot of the default lifecycle's components. */
+declare const list: () => ComponentStatus[];
+//#endregion
+export { Component, ComponentStatus, Phase, ProcessLike, Signal, Status, UpDown, UpDownOptions, down, isLive, isReady, list, register, up, updown, whenDown };

package/dist/index.js

@@ -0,0 +1,202 @@
+//#region src/index.ts
+/** Process signals that trigger shutdown by default. */
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+/** Exit code used after a signal-triggered shutdown. */
+const EXIT_OK = 0;
+const globalProcess = () => globalThis.process;
+/** Race a promise against a timeout; resolves to `'timeout'` if it elapses first. */
+function withTimeout(p, ms) {
+	if (!ms) return p;
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => resolve("timeout"), ms);
+		timer.unref?.();
+		p.then((v) => {
+			clearTimeout(timer);
+			resolve(v);
+		}, (e) => {
+			clearTimeout(timer);
+			reject(e);
+		});
+	});
+}
+/**
+* Create a lifecycle controller. See the {@link UpDown} methods.
+*/
+function updown(opts = {}) {
+	const comps = /* @__PURE__ */ new Map();
+	const status = /* @__PURE__ */ new Map();
+	const errors = /* @__PURE__ */ new Map();
+	let upPromise = null;
+	let downPromise = null;
+	let upDone = false;
+	let downRequested = false;
+	let preDone = false;
+	let resolveDown;
+	const downSignal = new Promise((r) => resolveDown = r);
+	let handlers = [];
+	const fail = (msg) => {
+		throw new Error(`updown: ${msg}`);
+	};
+	const dependentsOf = (name) => [...comps.values()].filter((c) => (c.deps ?? []).includes(name)).map((c) => c.name);
+	function checkGraph() {
+		const visiting = /* @__PURE__ */ new Set();
+		const done = /* @__PURE__ */ new Set();
+		const visit = (n, trail) => {
+			if (done.has(n)) return;
+			if (visiting.has(n)) fail(`dependency cycle: ${[...trail, n].join(" → ")}`);
+			visiting.add(n);
+			for (const d of comps.get(n).deps ?? []) {
+				if (!comps.has(d)) fail(`"${n}" depends on unknown component "${d}"`);
+				visit(d, [...trail, n]);
+			}
+			visiting.delete(n);
+			done.add(n);
+		};
+		for (const n of comps.keys()) visit(n, []);
+	}
+	const proc = opts.process ?? globalProcess();
+	function wireSignals() {
+		const sigs = opts.signals === false ? [] : opts.signals ?? DEFAULT_SIGNALS;
+		if (!proc?.on) return;
+		for (const sig of sigs) {
+			const h = () => void api.down().then(() => opts.exit !== false && proc.exit?.(EXIT_OK));
+			proc.on(sig, h);
+			handlers.push({
+				sig,
+				h
+			});
+		}
+	}
+	function unwireSignals() {
+		for (const { sig, h } of handlers) proc?.off?.(sig, h);
+		handlers = [];
+	}
+	function startUpGraph() {
+		const started = /* @__PURE__ */ new Map();
+		const start = (name) => {
+			const existing = started.get(name);
+			if (existing) return existing;
+			const c = comps.get(name);
+			const p = (async () => {
+				await Promise.all((c.deps ?? []).map(start));
+				if (downRequested) return;
+				status.set(name, "starting");
+				try {
+					await c.up?.();
+					status.set(name, "up");
+				} catch (e) {
+					status.set(name, "failed");
+					errors.set(name, e);
+					opts.onError?.(e, "up", name);
+					throw e;
+				}
+			})();
+			started.set(name, p);
+			return p;
+		};
+		return Promise.all([...comps.keys()].map(start)).then(() => void 0);
+	}
+	/** Run one shutdown phase in reverse-dependency order (dependents tear down before their deps). */
+	async function runPhase(hook) {
+		const done = /* @__PURE__ */ new Map();
+		const run = (name) => {
+			const existing = done.get(name);
+			if (existing) return existing;
+			const c = comps.get(name);
+			const p = (async () => {
+				await Promise.all(dependentsOf(name).map(run));
+				const st = status.get(name);
+				if (st === "idle" || st === "failed") return;
+				status.set(name, hook);
+				const fn = c[hook];
+				if (fn) try {
+					await fn();
+				} catch (e) {
+					status.set(name, "failed");
+					errors.set(name, e);
+					opts.onError?.(e, hook, name);
+					return;
+				}
+				if (hook === "post") status.set(name, "down");
+			})();
+			done.set(name, p);
+			return p;
+		};
+		await Promise.all([...comps.keys()].map(run));
+	}
+	const api = {
+		register(component) {
+			if (upPromise) fail(`cannot register "${component.name}" after up() has started`);
+			if (comps.has(component.name)) fail(`duplicate component "${component.name}"`);
+			comps.set(component.name, component);
+			status.set(component.name, "idle");
+			return api;
+		},
+		up() {
+			if (upPromise) return upPromise;
+			checkGraph();
+			wireSignals();
+			upPromise = (async () => {
+				if (await withTimeout(startUpGraph(), opts.timeout) === "timeout") throw new Error(`updown: up() timed out after ${opts.timeout}ms`);
+				upDone = true;
+			})();
+			return upPromise;
+		},
+		down() {
+			if (downPromise) return downPromise;
+			downRequested = true;
+			downPromise = (async () => {
+				if (upPromise) await upPromise.catch(() => {});
+				if (await withTimeout((async () => {
+					await runPhase("pre");
+					preDone = true;
+					await runPhase("post");
+				})(), opts.timeout) === "timeout") opts.onError?.(/* @__PURE__ */ new Error(`updown: down() timed out after ${opts.timeout}ms`), "post", "*");
+				unwireSignals();
+				resolveDown();
+			})();
+			return downPromise;
+		},
+		whenDown() {
+			return downSignal;
+		},
+		isReady() {
+			return upDone && !preDone;
+		},
+		isLive() {
+			return upDone && !downRequested;
+		},
+		list() {
+			return [...comps.values()].map((c) => {
+				/* v8 ignore next */ const st = status.get(c.name) ?? "idle";
+				const s = {
+					name: c.name,
+					deps: c.deps ?? [],
+					status: st
+				};
+				return errors.has(c.name) ? {
+					...s,
+					error: errors.get(c.name)
+				} : s;
+			});
+		}
+	};
+	return api;
+}
+const instance = updown();
+/** Register a component on the default lifecycle. */
+const register = (component) => instance.register(component);
+/** Start the default lifecycle. */
+const up = () => instance.up();
+/** Shut down the default lifecycle. */
+const down = () => instance.down();
+/** Resolve when the default lifecycle has shut down (without triggering it). */
+const whenDown = () => instance.whenDown();
+/** Readiness of the default lifecycle. */
+const isReady = () => instance.isReady();
+/** Liveness of the default lifecycle. */
+const isLive = () => instance.isLive();
+/** Snapshot of the default lifecycle's components. */
+const list = () => instance.list();
+//#endregion
+export { down, isLive, isReady, list, register, up, updown, whenDown };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ayepi/updown",
+  "version": "0.1.0",
+  "description": "Graceful startup/shutdown orchestration — named components with dependencies, two-phase shutdown, liveness/readiness",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/updown"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/updown#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "lifecycle",
+    "graceful-shutdown",
+    "startup",
+    "shutdown",
+    "healthcheck",
+    "liveness",
+    "readiness",
+    "ayepi"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}