@pristine-ts/core 1.0.440 → 2.0.1

package/dist/types/interfaces/instantiation-test.interface.d.ts

@@ -0,0 +1,13 @@
+import { DependencyContainer } from "tsyringe";
+import { InstantiationTestResultInterface } from "./instantiation-test-result.interface";
+/**
+ * Embedders register implementations of this interface (decorated with
+ * `@tag(ServiceDefinitionTagEnum.InstantiationTest)`) to contribute checks that run as part
+ * of `Kernel.verifyInstantiation`. Implementations receive the verifier's container so they
+ * can resolve services and assert on them. Tests should be cheap and side-effect-free.
+ */
+export interface InstantiationTestInterface {
+    name: string;
+    description?: string;
+    run(container: DependencyContainer): Promise<InstantiationTestResultInterface>;
+}

package/dist/types/interfaces/interfaces.d.ts

@@ -5,4 +5,8 @@ export * from "./event-listener.interface";
 export * from "./event-mapper.interface";
 export * from "./events-execution-options.interface";
 export * from "./execution-context.interface";
+export * from "./instantiation-test.interface";
+export * from "./instantiation-test-result.interface";
 export * from "./options-mapper.interface";
+export * from "./runtime-server.interface";
+export * from "./serialized-error.interface";

package/dist/types/interfaces/runtime-server.interface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A long-running server orchestrated by `pristine start`. Implementations (an HTTP server,
+ * a gRPC server, a websocket listener, etc.) tag themselves with
+ * `ServiceDefinitionTagEnum.RuntimeServer` and `pristine start` resolves them all and calls
+ * `start()` on each. Graceful shutdown is the module's responsibility — typically wired via
+ * `ModuleInterface.onShutdown` calling the server's `stop()`.
+ *
+ * Why the layer exists: `pristine start` cannot directly import from `@pristine-ts/http`
+ * (that would invert the dependency direction — http already depends on cli). This interface
+ * lets the cli orchestrate any number of server types without knowing about any of them
+ * specifically. Modules opt in by implementing and tagging.
+ */
+export interface RuntimeServerInterface {
+    /**
+     * A short label for log lines and diagnostic output (e.g. "http", "https", "grpc").
+     * Implementations should keep it stable across restarts so log filtering works.
+     */
+    name: string;
+    /**
+     * Boots the server and returns once it is accepting requests. The optional overrides let
+     * `pristine start` propagate runtime flags like `--port` / `--address` to whichever server
+     * cares to honor them. Implementations are free to ignore overrides that don't apply.
+     */
+    start(overrides?: {
+        port?: number;
+        address?: string;
+    }): Promise<void>;
+    /**
+     * Drains and shuts the server down. Should be idempotent — `pristine start` may call it
+     * after `Kernel.stop()` has already triggered an `onShutdown`-driven stop.
+     */
+    stop(): Promise<void>;
+}

package/dist/types/interfaces/serialized-error.interface.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plain-data shape of an `Error` captured during instantiation. The original `Error` instance
+ * is not retained because the report it lives in is meant to be JSON-serializable (logged,
+ * sent over the wire, persisted) — and a thrown `Error` does not survive serialization
+ * round-trips with name/message/stack intact.
+ */
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+}

package/dist/types/kernel.d.ts

@@ -1,9 +1,10 @@
 import "reflect-metadata";
 import { DependencyContainer } from "tsyringe";
-import { AppModuleInterface, Request } from "@pristine-ts/common";
+import { AppModuleInterface, ModuleInterface, Request } from "@pristine-ts/common";
 import { ModuleConfigurationValue } from "@pristine-ts/configuration";
 import { ExecutionContextInterface } from "./interfaces/execution-context.interface";
 import { Event } from "./models/event";
+import { InstantiationReport } from "./models/instantiation-report";
 /**
  * This is the central class that manages the lifecyle of this library.
  */
@@ -19,9 +20,11 @@ export declare class Kernel {
     instantiationId: string;
     /**
      * Contains a map of all the modules that were instantiated indexed by the modules names.
-     * @private
+     * @public Exposed read-only so commands like `pristine info` can introspect the boot graph.
      */
-    private instantiatedModules;
+    instantiatedModules: {
+        [id: string]: ModuleInterface;
+    };
     /**
      * Contains a map of all the modules that the afterInit was run for, indexed by the modules names .
      * @private
@@ -32,6 +35,12 @@ export declare class Kernel {
      * @private
      */
     private initializationSpan?;
+    /**
+     * True after `stop()` has begun (or completed). Prevents double-shutdown when multiple
+     * SIGTERM/SIGINT signals arrive in quick succession.
+     * @private
+     */
+    private stopped;
     /**
      * This function is the entry point of the Kernel. It initializes the module for your application (AppModule) as well as its the dependencies,
      * it registers the services, registers the configurations and runs the afterInit for each module.
@@ -41,6 +50,51 @@ export declare class Kernel {
     start(module: AppModuleInterface, moduleConfigurationValues?: {
         [key: string]: ModuleConfigurationValue;
     }): Promise<void>;
+    /**
+     * Verifies that this kernel can be fully instantiated against the provided AppModule and configuration values.
+     * Runs the same boot phases as `start()` on this kernel, capturing each phase's outcome rather than letting
+     * exceptions propagate, then collects and runs every embedder-registered `InstantiationTestInterface`.
+     *
+     * Important: this method mutates the kernel's container (it actually performs registration). It should be
+     * called on a fresh `new Kernel()` instance, not on a kernel that has already had `start()` invoked.
+     *
+     * @param module The AppModule to verify.
+     * @param moduleConfigurationValues The configuration values that would be passed to `start()`.
+     * @param options.runInstantiationTests When false, skips the test discovery/execution phase. Default true.
+     * @param options.stopOnFirstFailure When true, halts after the first failed phase and marks the rest as skipped. Default false.
+     */
+    verifyInstantiation(module: AppModuleInterface, moduleConfigurationValues?: {
+        [key: string]: ModuleConfigurationValue;
+    }, options?: {
+        runInstantiationTests?: boolean;
+        stopOnFirstFailure?: boolean;
+    }): Promise<InstantiationReport>;
+    /**
+     * Gracefully shuts down the kernel by invoking each instantiated module's `onShutdown` hook
+     * in reverse instantiation order (root module first, deepest dependencies last). Modules
+     * without an `onShutdown` hook are skipped silently.
+     *
+     * Each hook runs under a per-hook timeout so a single misbehaving module cannot block the
+     * shutdown indefinitely. When a hook throws or times out, the error is logged via the
+     * resolved `LogHandlerInterface` (or stderr if logging itself failed) and shutdown continues
+     * with the next module — the goal is to release as much as possible, not to abort on the
+     * first failure.
+     *
+     * Calling `stop()` more than once is a no-op (subsequent calls return immediately) so this
+     * method is safe to wire up to multiple signal handlers.
+     *
+     * @param options.perHookTimeoutMs Maximum milliseconds to wait for a single module's
+     *        `onShutdown` to resolve. Default 10_000 (10 seconds). Set to 0 to wait indefinitely.
+     */
+    stop(options?: {
+        perHookTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Wraps a Promise in a timeout that rejects with a clear error if not settled in time.
+     * `timeoutMs <= 0` disables the timeout entirely.
+     * @private
+     */
+    private runWithTimeout;
     /**
      *
      * @param event
@@ -64,11 +118,18 @@ export declare class Kernel {
      */
     private initModule;
     /**
-     * Registers all the configuration definitions that all the modules have defined.
-     * @param moduleConfigurationValues
+     * Resolves the ConfigurationManager and registers every module's configuration definitions onto it.
+     * Returns the manager so the caller can subsequently inspect required parameters or call `load()`.
+     * Split out from the original `initConfiguration` so `verifyInstantiation` can run a non-mutating
+     * check between definition registration and value loading.
      * @private
      */
-    private initConfiguration;
+    private registerConfigurationDefinitions;
+    /**
+     * Loads the configuration values into the previously-registered ConfigurationManager.
+     * @private
+     */
+    private loadConfiguration;
     /**
      * This method receives a module and recursively calls back this method with the module dependencies
      * specified as imported by the module.
@@ -91,4 +152,14 @@ export declare class Kernel {
      * @private
      */
     private registerNonModuleScopedServiceTags;
+    /**
+     * Wraps a phase invocation: times it, captures any thrown error into a serialized form, appends a
+     * PhaseResult to the report, and returns whether the phase passed.
+     * @private
+     */
+    private runPhase;
+    private runInstantiationTest;
+    private skipPhase;
+    private skipRemainingPhases;
+    private serializeError;
 }

package/dist/types/models/instantiation-report.d.ts

@@ -0,0 +1,43 @@
+import { LogHandlerInterface } from "@pristine-ts/logging";
+import { InstantiationStatusEnum } from "../enums/instantiation-status.enum";
+import { PhaseResult } from "./phase-result";
+import { InstantiationTestExecutionResult } from "./instantiation-test-execution-result";
+import { MissingRequiredConfigurationEntry } from "./missing-required-configuration-entry";
+/**
+ * Aggregated outcome of `Kernel.verifyInstantiation`. Plain data — callers serialize, render, or programmatically
+ * inspect it. The `log()` helper routes the report through the project's `LogHandlerInterface` (and falls back to
+ * stderr only when no LogHandler is available, e.g. when module registration itself failed before logging was wired up).
+ */
+export declare class InstantiationReport {
+    phases: PhaseResult[];
+    missingRequiredConfiguration: MissingRequiredConfigurationEntry[];
+    instantiationTests: InstantiationTestExecutionResult[];
+    totalDurationMs: number;
+    /**
+     * LogHandler stamped onto the report by the verifier when one becomes resolvable. Optional because the
+     * verifier may never reach a state where logging is available (e.g., module registration threw).
+     */
+    logHandler?: LogHandlerInterface;
+    /**
+     * Overall status derived from phase + test outcomes. Failed if any phase failed; PassedWithWarnings if
+     * there are missing required configurations satisfied only by default resolvers, or any failed instantiation
+     * tests; Passed otherwise.
+     */
+    get overallStatus(): InstantiationStatusEnum;
+    /**
+     * Convenience boolean: `true` when the report contains anything that should fail a CI check or block startup.
+     * Equivalent to `overallStatus === Failed`.
+     */
+    get hasErrors(): boolean;
+    get failedInstantiationTests(): InstantiationTestExecutionResult[];
+    get succeededInstantiationTests(): InstantiationTestExecutionResult[];
+    /**
+     * Routes the report through the project's logging stack. Each phase, missing configuration entry, and
+     * test result is emitted as its own log entry at the appropriate severity. When no LogHandler is provided
+     * and none was stamped onto the report (typical when module registration itself failed), falls back to
+     * `process.stderr` so the report is never silently swallowed.
+     */
+    log(logHandler?: LogHandlerInterface): void;
+    private fallbackLog;
+    private toPlainObject;
+}

package/dist/types/models/instantiation-test-execution-result.d.ts

@@ -0,0 +1,11 @@
+import { SerializedError } from "../interfaces/serialized-error.interface";
+export declare class InstantiationTestExecutionResult {
+    readonly name: string;
+    readonly passed: boolean;
+    readonly durationMs: number;
+    readonly description?: string | undefined;
+    readonly message?: string | undefined;
+    readonly details?: any | undefined;
+    readonly error?: SerializedError | undefined;
+    constructor(name: string, passed: boolean, durationMs: number, description?: string | undefined, message?: string | undefined, details?: any | undefined, error?: SerializedError | undefined);
+}

package/dist/types/models/missing-required-configuration-entry.d.ts

@@ -0,0 +1,5 @@
+export declare class MissingRequiredConfigurationEntry {
+    readonly parameterName: string;
+    readonly hasDefaultResolvers: boolean;
+    constructor(parameterName: string, hasDefaultResolvers: boolean);
+}

package/dist/types/models/models.d.ts

@@ -1,2 +1,6 @@
 export * from "./event";
 export * from "./event.response";
+export * from "./instantiation-report";
+export * from "./instantiation-test-execution-result";
+export * from "./missing-required-configuration-entry";
+export * from "./phase-result";

package/dist/types/models/phase-result.d.ts

@@ -0,0 +1,15 @@
+import { InstantiationPhaseEnum } from "../enums/instantiation-phase.enum";
+import { InstantiationStatusEnum } from "../enums/instantiation-status.enum";
+import { SerializedError } from "../interfaces/serialized-error.interface";
+/**
+ * Outcome of a single phase of `Kernel.verifyInstantiation` (e.g. `ModuleRegistration`,
+ * `ConfigurationLoad`, `BootProbe`). One `PhaseResult` per phase appears in the report.
+ */
+export declare class PhaseResult {
+    readonly phase: InstantiationPhaseEnum;
+    status: InstantiationStatusEnum;
+    durationMs: number;
+    error?: SerializedError | undefined;
+    details?: any | undefined;
+    constructor(phase: InstantiationPhaseEnum, status: InstantiationStatusEnum, durationMs: number, error?: SerializedError | undefined, details?: any | undefined);
+}

package/dist/types/runtime-servers/default-runtime-server.d.ts

@@ -0,0 +1,22 @@
+import { RuntimeServerInterface } from "../interfaces/runtime-server.interface";
+/**
+ * No-op default registration for `ServiceDefinitionTagEnum.RuntimeServer`. Without this,
+ * tsyringe's `@injectAll(RuntimeServer)` would throw "Attempted to resolve unregistered
+ * dependency token" in apps that don't import any module providing a real RuntimeServer
+ * (e.g. an AppModule that doesn't include `@pristine-ts/http`). Registering one default
+ * lets `pristine start` cleanly handle the "no servers" case as an empty-loop scenario
+ * (after filtering this out) rather than an exception.
+ *
+ * Same pattern as `DefaultEventMapper` and `DefaultEventListener` use for their respective
+ * tags.
+ */
+export declare class DefaultRuntimeServer implements RuntimeServerInterface {
+    /**
+     * Sentinel name. Consumers that iterate the resolved server list should filter on this
+     * value (or simply skip servers whose `start()` is a no-op) when they want to ignore
+     * the default placeholder.
+     */
+    readonly name: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/types/runtime-servers/runtime-servers.d.ts

@@ -0,0 +1 @@
+export * from "./default-runtime-server";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pristine-ts/core",
-  "version": "1.0.440",
+  "version": "2.0.1",
   "description": "",
   "module": "dist/lib/esm/core.module.js",
   "main": "dist/lib/cjs/core.module.js",
@@ -20,11 +20,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@pristine-ts/common": "^1.0.440",
-    "@pristine-ts/configuration": "^1.0.440",
-    "@pristine-ts/logging": "^1.0.440",
-    "@pristine-ts/security": "^1.0.440",
-    "@pristine-ts/telemetry": "^1.0.440",
+    "@pristine-ts/common": "^2.0.1",
+    "@pristine-ts/configuration": "^2.0.1",
+    "@pristine-ts/logging": "^2.0.1",
+    "@pristine-ts/security": "^2.0.1",
+    "@pristine-ts/telemetry": "^2.0.1",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
@@ -64,7 +64,7 @@
       "src/*.{js,ts}"
     ]
   },
-  "gitHead": "2828491bc8cc720476584f3cf60791a4a705a77e",
+  "gitHead": "a5e40ea0fcdeaf743666c1981a9315bfde9c4c00",
   "repository": {
     "type": "git",
     "url": "https://github.com/magieno/pristine-ts.git",