@btravstack/core 0.17.0 → 0.18.0

package/dist/index.cjs

@@ -5,6 +5,7 @@ let node_timers_promises = require("node:timers/promises");
 let _btravstack_config = require("@btravstack/config");
 let node_http = require("node:http");
 let node_async_hooks = require("node:async_hooks");
+let node_crypto = require("node:crypto");
 //#region src/instrumentation.ts
 /**
 * The set port a package contributes its instrumentation to.
@@ -432,10 +433,22 @@ const installUncaughtHandlers = (onUncaught) => {
 const storage = new node_async_hooks.AsyncLocalStorage();
 const runWithUnit = (record, fn) => storage.run(record, fn);
 const currentUnit = () => storage.getStore();
-let counter = 0;
-const nextId = () => {
-	counter += 1;
-	return `u${counter}`;
+const outcomes = /* @__PURE__ */ new WeakMap();
+const settleUnit = (record, outcome) => {
+	outcomes.set(record, outcome);
+};
+/**
+* How the current unit's work settled, for the code that runs AFTER it: a
+* unit module's `onStop`, which tears down inside the record but is handed
+* only its own service. `undefined` outside a unit and while the work is still
+* running. Whether the unit was aborted is the record's own `signal`.
+*
+* It is the kernel's outcome, not the transport's: an HTTP unit that answered
+* a `500` still settled `ok`, since the kernel never maps a status.
+*/
+const unitOutcome = () => {
+	const unit = currentUnit();
+	return unit === void 0 ? void 0 : outcomes.get(unit);
 };
 const createUnitRegistry = () => {
 	const open = /* @__PURE__ */ new Set();
@@ -451,7 +464,7 @@ const createUnitRegistry = () => {
 			const controller = new AbortController();
 			open.add(controller);
 			const record = {
-				unitId: nextId(),
+				unitId: (0, node_crypto.randomUUID)(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
 				signal: controller.signal
@@ -741,13 +754,18 @@ const start = (module, options = {}) => {
 				}).get();
 				return (0, unthrown.fromSafePromise)(ready.promise);
 			};
+			const record = currentUnit();
 			const outcome = (async () => {
+				let settledAs = "error";
 				try {
-					return await work({
+					const result = await work({
 						ctx: runtimeCtx,
 						fork
 					}, signal);
+					if (result.isOk()) settledAs = "ok";
+					return result;
 				} finally {
+					if (record !== void 0) settleUnit(record, settledAs);
 					hasSettled = true;
 					settled.resolve();
 					if (closing !== void 0) await closing;
@@ -976,4 +994,5 @@ exports.start = start;
 exports.stderrSink = stderrSink;
 exports.systemClock = systemClock;
 exports.traceIdOfTraceparent = traceIdOfTraceparent;
+exports.unitOutcome = unitOutcome;
 exports.withUnitRecord = withUnitRecord;

package/dist/index.d.cts

@@ -352,6 +352,18 @@ type UnitRecord = {
   readonly signal: AbortSignal;
 };
 export declare const currentUnit: () => UnitRecord | undefined;
+/** How a unit's work settled: `ok`, or `error` for an `Err`, a `Defect` and a throw alike. */
+type UnitOutcome = "ok" | "error";
+/**
+ * How the current unit's work settled, for the code that runs AFTER it: a
+ * unit module's `onStop`, which tears down inside the record but is handed
+ * only its own service. `undefined` outside a unit and while the work is still
+ * running. Whether the unit was aborted is the record's own `signal`.
+ *
+ * It is the kernel's outcome, not the transport's: an HTTP unit that answered
+ * a `500` still settled `ok`, since the kernel never maps a status.
+ */
+export declare const unitOutcome: () => UnitOutcome | undefined;
 /**
  * What a runtime says about one piece of work as it submits it. `kind` is the
  * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
@@ -363,7 +375,8 @@ export declare const currentUnit: () => UnitRecord | undefined;
  * silently defeats the ambient record. A route template is a `kind`.
  *
  * The kernel cannot check this, so uniqueness is the runtime's to guarantee.
- * What it does guarantee is {@link UnitRecord}'s `unitId`, minted per unit;
+ * What it does guarantee is {@link UnitRecord}'s `unitId`, a UUID minted per
+ * unit, so no two units share one across replicas either;
  * `traceId` is the CORRELATION id, which is why it is the one a runtime may
  * supply — it carries an id from outside the process.
  */
@@ -942,4 +955,4 @@ export declare const noObserverMember: Provider<Observers, never, never> & {
   readonly port: typeof Observers;
 };
 //#endregion
-export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

package/dist/index.d.mts

@@ -352,6 +352,18 @@ type UnitRecord = {
   readonly signal: AbortSignal;
 };
 export declare const currentUnit: () => UnitRecord | undefined;
+/** How a unit's work settled: `ok`, or `error` for an `Err`, a `Defect` and a throw alike. */
+type UnitOutcome = "ok" | "error";
+/**
+ * How the current unit's work settled, for the code that runs AFTER it: a
+ * unit module's `onStop`, which tears down inside the record but is handed
+ * only its own service. `undefined` outside a unit and while the work is still
+ * running. Whether the unit was aborted is the record's own `signal`.
+ *
+ * It is the kernel's outcome, not the transport's: an HTTP unit that answered
+ * a `500` still settled `ok`, since the kernel never maps a status.
+ */
+export declare const unitOutcome: () => UnitOutcome | undefined;
 /**
  * What a runtime says about one piece of work as it submits it. `kind` is the
  * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
@@ -363,7 +375,8 @@ export declare const currentUnit: () => UnitRecord | undefined;
  * silently defeats the ambient record. A route template is a `kind`.
  *
  * The kernel cannot check this, so uniqueness is the runtime's to guarantee.
- * What it does guarantee is {@link UnitRecord}'s `unitId`, minted per unit;
+ * What it does guarantee is {@link UnitRecord}'s `unitId`, a UUID minted per
+ * unit, so no two units share one across replicas either;
  * `traceId` is the CORRELATION id, which is why it is the one a runtime may
  * supply — it carries an id from outside the process.
  */
@@ -942,4 +955,4 @@ export declare const noObserverMember: Provider<Observers, never, never> & {
   readonly port: typeof Observers;
 };
 //#endregion
-export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { Config, ConfigInvalid, Env } from "@btravstack/config";
 import { createServer } from "node:http";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 //#region src/instrumentation.ts
 /**
 * The set port a package contributes its instrumentation to.
@@ -431,10 +432,22 @@ const installUncaughtHandlers = (onUncaught) => {
 const storage = new AsyncLocalStorage();
 const runWithUnit = (record, fn) => storage.run(record, fn);
 const currentUnit = () => storage.getStore();
-let counter = 0;
-const nextId = () => {
-	counter += 1;
-	return `u${counter}`;
+const outcomes = /* @__PURE__ */ new WeakMap();
+const settleUnit = (record, outcome) => {
+	outcomes.set(record, outcome);
+};
+/**
+* How the current unit's work settled, for the code that runs AFTER it: a
+* unit module's `onStop`, which tears down inside the record but is handed
+* only its own service. `undefined` outside a unit and while the work is still
+* running. Whether the unit was aborted is the record's own `signal`.
+*
+* It is the kernel's outcome, not the transport's: an HTTP unit that answered
+* a `500` still settled `ok`, since the kernel never maps a status.
+*/
+const unitOutcome = () => {
+	const unit = currentUnit();
+	return unit === void 0 ? void 0 : outcomes.get(unit);
 };
 const createUnitRegistry = () => {
 	const open = /* @__PURE__ */ new Set();
@@ -450,7 +463,7 @@ const createUnitRegistry = () => {
 			const controller = new AbortController();
 			open.add(controller);
 			const record = {
-				unitId: nextId(),
+				unitId: randomUUID(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
 				signal: controller.signal
@@ -740,13 +753,18 @@ const start = (module, options = {}) => {
 				}).get();
 				return fromSafePromise(ready.promise);
 			};
+			const record = currentUnit();
 			const outcome = (async () => {
+				let settledAs = "error";
 				try {
-					return await work({
+					const result = await work({
 						ctx: runtimeCtx,
 						fork
 					}, signal);
+					if (result.isOk()) settledAs = "ok";
+					return result;
 				} finally {
+					if (record !== void 0) settleUnit(record, settledAs);
 					hasSettled = true;
 					settled.resolve();
 					if (closing !== void 0) await closing;
@@ -949,4 +967,4 @@ const noObserverMember = Provider.member(Observers)({
 	value: noObserver
 });
 //#endregion
-export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, composeByPrefix, currentUnit, dispatchUnit, mintPiece, noObserver, noObserverMember, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent, withUnitRecord };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, composeByPrefix, currentUnit, dispatchUnit, mintPiece, noObserver, noObserverMember, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent, unitOutcome, withUnitRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,20 +45,21 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.17.0",
-    "@btravstack/di": "0.17.0",
+    "@btravstack/config": "0.18.0",
+    "@btravstack/di": "0.18.0",
     "@btravstack/tsconfig": "0.4.0",
     "@types/node": "26.6.4",
     "@unthrown/vitest": "5.12.0",
     "@vitest/coverage-v8": "5.0.3",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
+    "typescript-consumer": "npm:typescript@5.9.3",
     "unthrown": "5.12.0",
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.17.0",
-    "@btravstack/di": "^0.17.0",
+    "@btravstack/config": "^0.18.0",
+    "@btravstack/di": "^0.18.0",
     "unthrown": "^5.0.0"
   },
   "engines": {
@@ -69,6 +70,6 @@
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch --tsconfig tsconfig.build.json",
     "generate": "node ../../docs/scripts/extract-doc-samples.ts --group core --out src/generated/doc-samples",
     "test": "vitest run --coverage",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
   }
 }