@btravstack/core 0.25.0 → 0.27.0

package/dist/index.cjs

@@ -1007,14 +1007,14 @@ const dispatchUnit = (dispatch) => observed(dispatch.observers, dispatch.operati
 * record the piece declared. The starter keeps the types; this keeps the body.
 */
 const mintPiece = (port, withUnit) => (options) => (0, _btravstack_di.Provider)(port)({
-	inject: options.inject,
+	inject: options.inject ?? {},
 	sync: (services) => withUnit(options.unit ?? {}, options.sync(services))
 });
 /**
 * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
 * `TemporalActivities(contract)` — and its two arms. An array of pieces is
 * composed into one record keyed by each piece's port id less `prefix`, so the
-* services record IS the composed record; a `{ inject, unit?, sync }` record
+* services record IS the composed record; a `{ inject?, unit?, sync }` record
 * has `withUnit` applied to every entry `sync` answers.
 */
 const composeByPrefix = (port, prefix, withUnit) => {

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { AsyncResult, FailureView, Result } from "unthrown";
 import { AnyPort, AnyProvider, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
-import { Env, Environment } from "@btravstack/config";
+import { Env, Environment, EnvironmentFor } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
  * One package's offer of an OpenTelemetry instrumentation.
@@ -761,12 +761,34 @@ type ExitReport = {
    */
   readonly abandonedAt?: "build" | "stop";
 };
-type StartOptions = {
+/**
+ * The kernel's own variables, all optional: each has a default, and each is
+ * pinned by the matching {@link StartOptions} field.
+ */
+type KernelEnvironment = {
+  readonly PROBE_PORT?: string | undefined;
+  readonly PROBE_HOST?: string | undefined;
+  readonly PRE_DRAIN_DELAY_MS?: string | undefined;
+  readonly DRAIN_TIMEOUT_MS?: string | undefined;
+  readonly STOP_TIMEOUT_MS?: string | undefined;
+};
+/**
+ * The `env` a `start` of `M` accepts — what the module's configuration reads,
+ * plus the kernel's own variables. For typing an environment kept apart from
+ * the call, such as a test's shared one.
+ */
+type StartEnvironment<M> = M extends Module<infer _X, infer _E, infer N> ? EnvironmentFor<N> & KernelEnvironment : never;
+type StartOptions<Ev = Environment> = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
    * port and read for the kernel's own variables. Defaults to `process.env`.
+   *
+   * Typed by what the graph reads: at `start(module, { env })` it accepts the
+   * variables the module's configuration names and the kernel's own, requires
+   * the ones nothing defaults or pins, and refuses any other — unless some
+   * reader named none, when any record is accepted.
    */
-  readonly env?: Environment;
+  readonly env?: Ev;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
@@ -875,7 +897,7 @@ type PortIdOf<P> = P extends PortInstance<infer Id, infer _Service> ? Id : P;
 type StartGate<X, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? unknown : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
   readonly "UNSATISFIED DEPENDENCIES — nothing provides": PortIdOf<Exclude<N, Scope | Env>>;
 };
-export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
+export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions<EnvironmentFor<N> & KernelEnvironment>) => RunningApp<E, RuntimeInfoOf<X>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -911,7 +933,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  * await runMain(OrderApi);
  * ```
  */
-export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
+export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions<EnvironmentFor<N> & KernelEnvironment>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
 //#region src/unit-overrides.d.ts
 declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
@@ -944,9 +966,9 @@ export declare class UnitOverrides extends UnitOverrides_base<Readonly<Record<st
 type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /** How a starter puts a piece's declared `unit:` record on one of its entries. */
 type EntryWrapper = (record: Readonly<Record<string, AnyPort>>, entry: unknown) => unknown;
-/** A piece's `{ inject, unit?, sync }` options, with the types each starter states erased. */
+/** A piece's `{ inject?, unit?, sync }` options, with the types each starter states erased. */
 type PieceOptions = {
-  readonly inject: Readonly<Record<string, AnyPort>>;
+  readonly inject?: Readonly<Record<string, AnyPort>>;
   readonly unit?: Readonly<Record<string, AnyPort>>;
   readonly sync: (services: never) => unknown;
 };
@@ -961,7 +983,7 @@ export declare const mintPiece: (port: AnyPort, withUnit: EntryWrapper) => (opti
  * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
  * `TemporalActivities(contract)` — and its two arms. An array of pieces is
  * composed into one record keyed by each piece's port id less `prefix`, so the
- * services record IS the composed record; a `{ inject, unit?, sync }` record
+ * services record IS the composed record; a `{ inject?, unit?, sync }` record
  * has `withUnit` applied to every entry `sync` answers.
  */
 export declare const composeByPrefix: (port: AnyPort, prefix: string, withUnit: EntryWrapper) => ((first: unknown) => unknown);
@@ -978,4 +1000,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, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEnvironment, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartEnvironment, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { AnyPort, AnyProvider, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { AsyncResult, FailureView, Result } from "unthrown";
-import { Env, Environment } from "@btravstack/config";
+import { Env, Environment, EnvironmentFor } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
  * One package's offer of an OpenTelemetry instrumentation.
@@ -761,12 +761,34 @@ type ExitReport = {
    */
   readonly abandonedAt?: "build" | "stop";
 };
-type StartOptions = {
+/**
+ * The kernel's own variables, all optional: each has a default, and each is
+ * pinned by the matching {@link StartOptions} field.
+ */
+type KernelEnvironment = {
+  readonly PROBE_PORT?: string | undefined;
+  readonly PROBE_HOST?: string | undefined;
+  readonly PRE_DRAIN_DELAY_MS?: string | undefined;
+  readonly DRAIN_TIMEOUT_MS?: string | undefined;
+  readonly STOP_TIMEOUT_MS?: string | undefined;
+};
+/**
+ * The `env` a `start` of `M` accepts — what the module's configuration reads,
+ * plus the kernel's own variables. For typing an environment kept apart from
+ * the call, such as a test's shared one.
+ */
+type StartEnvironment<M> = M extends Module<infer _X, infer _E, infer N> ? EnvironmentFor<N> & KernelEnvironment : never;
+type StartOptions<Ev = Environment> = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
    * port and read for the kernel's own variables. Defaults to `process.env`.
+   *
+   * Typed by what the graph reads: at `start(module, { env })` it accepts the
+   * variables the module's configuration names and the kernel's own, requires
+   * the ones nothing defaults or pins, and refuses any other — unless some
+   * reader named none, when any record is accepted.
    */
-  readonly env?: Environment;
+  readonly env?: Ev;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
@@ -875,7 +897,7 @@ type PortIdOf<P> = P extends PortInstance<infer Id, infer _Service> ? Id : P;
 type StartGate<X, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? unknown : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
   readonly "UNSATISFIED DEPENDENCIES — nothing provides": PortIdOf<Exclude<N, Scope | Env>>;
 };
-export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
+export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions<EnvironmentFor<N> & KernelEnvironment>) => RunningApp<E, RuntimeInfoOf<X>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -911,7 +933,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  * await runMain(OrderApi);
  * ```
  */
-export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
+export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions<EnvironmentFor<N> & KernelEnvironment>, exit?: (code: number) => void) => Promise<void>;
 //#endregion
 //#region src/unit-overrides.d.ts
 declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
@@ -944,9 +966,9 @@ export declare class UnitOverrides extends UnitOverrides_base<Readonly<Record<st
 type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
 /** How a starter puts a piece's declared `unit:` record on one of its entries. */
 type EntryWrapper = (record: Readonly<Record<string, AnyPort>>, entry: unknown) => unknown;
-/** A piece's `{ inject, unit?, sync }` options, with the types each starter states erased. */
+/** A piece's `{ inject?, unit?, sync }` options, with the types each starter states erased. */
 type PieceOptions = {
-  readonly inject: Readonly<Record<string, AnyPort>>;
+  readonly inject?: Readonly<Record<string, AnyPort>>;
   readonly unit?: Readonly<Record<string, AnyPort>>;
   readonly sync: (services: never) => unknown;
 };
@@ -961,7 +983,7 @@ export declare const mintPiece: (port: AnyPort, withUnit: EntryWrapper) => (opti
  * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
  * `TemporalActivities(contract)` — and its two arms. An array of pieces is
  * composed into one record keyed by each piece's port id less `prefix`, so the
- * services record IS the composed record; a `{ inject, unit?, sync }` record
+ * services record IS the composed record; a `{ inject?, unit?, sync }` record
  * has `withUnit` applied to every entry `sync` answers.
  */
 export declare const composeByPrefix: (port: AnyPort, prefix: string, withUnit: EntryWrapper) => ((first: unknown) => unknown);
@@ -978,4 +1000,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, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEnvironment, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartEnvironment, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

package/dist/index.mjs

@@ -1006,14 +1006,14 @@ const dispatchUnit = (dispatch) => observed(dispatch.observers, dispatch.operati
 * record the piece declared. The starter keeps the types; this keeps the body.
 */
 const mintPiece = (port, withUnit) => (options) => Provider(port)({
-	inject: options.inject,
+	inject: options.inject ?? {},
 	sync: (services) => withUnit(options.unit ?? {}, options.sync(services))
 });
 /**
 * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
 * `TemporalActivities(contract)` — and its two arms. An array of pieces is
 * composed into one record keyed by each piece's port id less `prefix`, so the
-* services record IS the composed record; a `{ inject, unit?, sync }` record
+* services record IS the composed record; a `{ inject?, unit?, sync }` record
 * has `withUnit` applied to every entry `sync` answers.
 */
 const composeByPrefix = (port, prefix, withUnit) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,8 +45,8 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.25.0",
-    "@btravstack/di": "0.25.0",
+    "@btravstack/config": "0.27.0",
+    "@btravstack/di": "0.27.0",
     "@btravstack/tsconfig": "0.4.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
@@ -60,8 +60,8 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.25.0",
-    "@btravstack/di": "^0.25.0",
+    "@btravstack/config": "^0.27.0",
+    "@btravstack/di": "^0.27.0",
     "unthrown": "^5.0.0"
   },
   "engines": {