@btravstack/core 0.24.0 → 0.26.0

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">;
@@ -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">;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.24.0",
+  "version": "0.26.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.24.0",
-    "@btravstack/di": "0.24.0",
+    "@btravstack/config": "0.26.0",
+    "@btravstack/di": "0.26.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.24.0",
-    "@btravstack/di": "^0.24.0",
+    "@btravstack/config": "^0.26.0",
+    "@btravstack/di": "^0.26.0",
     "unthrown": "^5.0.0"
   },
   "engines": {