@iskra-bun/core 0.1.0 → 0.2.0

package/src/types.ts

@@ -13,17 +13,42 @@ export interface Plugin {
     install(app: App): Promise<void> | void;
 }
 
-export interface Context<T = any> {
+/** What an `app.on()` handler receives; `payload` is the emitted value. */
+export interface Context<T = unknown> {
     app: App;
     logger: Logger;
     payload: T;
-    reply(data: any): void;
+    /** Emits `<event>:reply` with `data`. */
+    reply(data: unknown): void;
 }
 
+/**
+ * What each kit shares through `app.context`, by key, so `app.context.get('db')`
+ * is typed. Kits add their keys with declaration merging, and so can an app:
+ *
+ * ```ts
+ * declare module '@iskra-bun/core' {
+ *     interface AppContextRegistry {
+ *         bridge: DesktopBridge;
+ *     }
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- filled by declaration merging
+export interface AppContextRegistry {}
+
+/**
+ * The payload of each app event, by name, so `app.on('process:exit', ...)`
+ * and `app.emit(...)` are typed. Kits add their events with declaration
+ * merging, and so can an app (as with AppContextRegistry).
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- filled by declaration merging
+export interface AppEvents {}
+
 export interface OtelConfig {
     /** Defaults to true when otel config is present */
     enabled?: boolean;
-    /** OTLP endpoint URL. Defaults to http://localhost:4318 */
+    /** OTLP endpoint URL. Defaults to http://localhost:4318; use https:// for a collector on another host. */
     endpoint?: string;
     /** Overrides app name for the service.name resource attribute */
     serviceName?: string;
@@ -35,8 +60,14 @@ export interface OtelConfig {
     metricIntervalMs?: number;
     /** Additional resource attributes */
     resourceAttributes?: Record<string, string>;
-    /** Auto-instrumentation overrides (passed to getNodeAutoInstrumentations) */
-    instrumentations?: Record<string, { enabled?: boolean }>;
+    /**
+     * Options of each auto-instrumentation, by package name, passed to
+     * getNodeAutoInstrumentations(): `{ enabled: false }`, or its own options
+     * (`'@opentelemetry/instrumentation-http': { ignoreIncomingRequestHook,
+     * redactedQueryParams }`). The HTTP one redacts SECRET_QUERY_PARAMS in
+     * exported URLs unless `redactedQueryParams` says otherwise.
+     */
+    instrumentations?: Record<string, { enabled?: boolean; [option: string]: unknown }>;
 }
 
 export interface AppConfig {
@@ -46,6 +77,13 @@ export interface AppConfig {
         level?: string;
     };
     otel?: OtelConfig;
+    /**
+     * Signals that trigger a graceful `stop()` and exit. Default
+     * `['SIGTERM', 'SIGINT']` (none under NODE_ENV=test); `false` disables.
+     */
+    shutdownSignals?: string[] | false;
+    /** Max time for a signal-triggered stop before forcing exit(1). Default 10000. */
+    shutdownTimeoutMs?: number;
     processes?: Record<string, ProcessConfig>;
     socket?: {
         enabled: boolean;
@@ -53,15 +91,26 @@ export interface AppConfig {
         adapter?: 'bun' | 'socket.io';
     };
     kv?: {
-        driver: 'memory' | 'redis' | 'libsql';
-        connection?: any;
+        driver: 'memory' | 'redis';
+        /** Redis: a URL string, ioredis options, or ioredis options with `url`. */
+        connection?: string | Record<string, unknown>;
     };
     db?: {
         driver: 'postgres' | 'mysql' | 'sqlite' | 'libsql';
         url: string;
         authToken?: string;
     };
-    [key: string]: any;
+    /** Sections of other kits or of the app; read them with their own type. */
+    [key: string]: unknown;
+}
+
+export interface RestartBackoffConfig {
+    /** Initial delay in ms before the first restart. Default: 1000 */
+    initialMs?: number;
+    /** Maximum delay cap in ms. Default: 30000 */
+    maxMs?: number;
+    /** Multiplier applied to the delay after each restart. Default: 2 */
+    factor?: number;
 }
 
 export interface ProcessConfig {
@@ -71,5 +120,20 @@ export interface ProcessConfig {
     restartOnCrash?: boolean;
     maxRestarts?: number;
     restartCooldown?: number;
+    /** Variables set for the child, over the ones it inherits (see `inheritEnv`). */
     env?: Record<string, string>;
+    /**
+     * Which of the app's environment variables the child inherits. Default
+     * `false`: a minimal set without secrets (PATH, HOME, locale, TZ, temp
+     * dir, NODE_ENV…). A list adds those names to it; `true` passes them all
+     * (DATABASE_URL, AUTH_SECRET, cloud keys…).
+     */
+    inheritEnv?: boolean | string[];
+    /**
+     * `stdio` mode: bytes `send()` lets wait for a child that is not reading
+     * its stdin; past this it refuses messages (returns false). Default 8 MiB.
+     */
+    maxPendingStdinBytes?: number;
+    /** Exponential backoff settings for restarts. Defaults to 1000 ms flat (no backoff). */
+    restartBackoff?: RestartBackoffConfig;
 }