@zudojs/core 0.0.1 → 1.0.0

package/dist/runtime/runtimeState.state.js

@@ -1,4 +1,5 @@
-import { RuntimeStateError } from "@zudojs/errors";
+import { InvalidRuntimeStateError, InvalidRuntimeTransitionError, } from "./runtimeError/runtimeError.lifecycle.js";
+export { InvalidRuntimeStateError, InvalidRuntimeTransitionError, } from "./runtimeError/runtimeError.lifecycle.js";
 /** Runtime lifecycle states. */
 export var RuntimeState;
 (function (RuntimeState) {
@@ -9,38 +10,27 @@ export var RuntimeState;
     RuntimeState["STOPPED"] = "stopped";
     RuntimeState["FAILED"] = "failed";
 })(RuntimeState || (RuntimeState = {}));
-/** Terminal runtime states. */
+/** Terminal runtime states: no further transitions are possible. */
 export const TERMINAL_RUNTIME_STATES = Object.freeze([
     RuntimeState.STOPPED,
+    RuntimeState.FAILED,
 ]);
 /** Runtime states from which startup is allowed. */
 export const STARTABLE_RUNTIME_STATES = Object.freeze([
     RuntimeState.CREATED,
 ]);
-/** Runtime states from which shutdown is allowed. */
+/**
+ * Runtime states from which shutdown is allowed.
+ *
+ * CREATED is included because stopping a runtime that never started
+ * is a valid soft stop (no modules to unwind).
+ */
 export const STOPPABLE_RUNTIME_STATES = Object.freeze([
+    RuntimeState.CREATED,
     RuntimeState.READY,
 ]);
 /** Runtime states that indicate a lifecycle operation is in progress. */
 export const TRANSITIONAL_RUNTIME_STATES = Object.freeze([RuntimeState.BOOTSTRAPPING, RuntimeState.STOPPING]);
-/** Error thrown when an invalid runtime state is encountered. */
-export class InvalidRuntimeStateError extends RuntimeStateError {
-    state;
-    constructor(message) {
-        super(message);
-        this.state = message;
-    }
-}
-/** Error thrown when an invalid runtime state transition is attempted. */
-export class InvalidRuntimeTransitionError extends RuntimeStateError {
-    from;
-    to;
-    constructor(from, to) {
-        super(`Invalid runtime state transition from "${from}" to "${to}".`);
-        this.from = from;
-        this.to = to;
-    }
-}
 export function isRuntimeState(value) {
     return (value === RuntimeState.CREATED ||
         value === RuntimeState.BOOTSTRAPPING ||
@@ -67,16 +57,29 @@ export function canStartRuntime(state) {
 export function canStopRuntime(state) {
     return STOPPABLE_RUNTIME_STATES.includes(state);
 }
+/**
+ * Determines whether a runtime state transition is valid.
+ *
+ * Rules:
+ * - Self transitions are never valid.
+ * - FAILED is reachable from every non-terminal state
+ *   (CREATED, BOOTSTRAPPING, READY, STOPPING).
+ * - CREATED → STOPPED is a valid "soft stop": a runtime that
+ *   never started can be stopped as a no-op.
+ * - STOPPED and FAILED are terminal for transitions.
+ */
 export function canTransitionRuntime(from, to) {
     if (from === to)
-        return true;
+        return false;
     switch (from) {
         case RuntimeState.CREATED:
-            return to === RuntimeState.BOOTSTRAPPING;
+            return (to === RuntimeState.BOOTSTRAPPING ||
+                to === RuntimeState.STOPPED ||
+                to === RuntimeState.FAILED);
         case RuntimeState.BOOTSTRAPPING:
             return to === RuntimeState.READY || to === RuntimeState.FAILED;
         case RuntimeState.READY:
-            return to === RuntimeState.STOPPING;
+            return to === RuntimeState.STOPPING || to === RuntimeState.FAILED;
         case RuntimeState.STOPPING:
             return to === RuntimeState.STOPPED || to === RuntimeState.FAILED;
         case RuntimeState.FAILED:
@@ -89,7 +92,7 @@ export function canTransitionRuntime(from, to) {
 }
 export function assertRuntimeState(value) {
     if (!isRuntimeState(value))
-        throw new InvalidRuntimeStateError(`Invalid runtime state: "${String(value)}".`);
+        throw new InvalidRuntimeStateError(`Invalid runtime state: "${String(value)}".`, { state: String(value) });
 }
 export function assertRuntimeTransition(from, to) {
     if (!canTransitionRuntime(from, to))
@@ -139,11 +142,15 @@ export function getRuntimeStates() {
 export function getNextRuntimeStates(state) {
     switch (state) {
         case RuntimeState.CREATED:
-            return Object.freeze([RuntimeState.BOOTSTRAPPING]);
+            return Object.freeze([
+                RuntimeState.BOOTSTRAPPING,
+                RuntimeState.STOPPED,
+                RuntimeState.FAILED,
+            ]);
         case RuntimeState.BOOTSTRAPPING:
             return Object.freeze([RuntimeState.READY, RuntimeState.FAILED]);
         case RuntimeState.READY:
-            return Object.freeze([RuntimeState.STOPPING]);
+            return Object.freeze([RuntimeState.STOPPING, RuntimeState.FAILED]);
         case RuntimeState.STOPPING:
             return Object.freeze([RuntimeState.STOPPED, RuntimeState.FAILED]);
         case RuntimeState.FAILED:

package/dist/runtime/runtimeTimeout.d.ts

@@ -0,0 +1,40 @@
+import type { RuntimeErrorOptions } from "./runtimeError/runtimeError.type.js";
+/**
+ * An operation that can be raced against a timeout.
+ *
+ * The operation receives an AbortSignal that is aborted when the
+ * timeout elapses; cooperative operations should stop mutating
+ * shared state once `signal.aborted` is true.
+ */
+export type TimeoutAwareOperation<T> = (signal: AbortSignal) => Promise<T>;
+/**
+ * Options for {@link withRuntimeTimeout}.
+ */
+export interface RuntimeTimeoutOptions {
+    /**
+     * Message used for the timeout error.
+     */
+    readonly message?: string;
+    /**
+     * Additional runtime error options for the timeout error.
+     */
+    readonly error?: RuntimeErrorOptions;
+    /**
+     * Invoked if the abandoned operation eventually rejects after the
+     * timeout already fired. Defaults to swallowing the rejection so it
+     * never surfaces as an unhandled rejection.
+     */
+    readonly onLateRejection?: (error: unknown) => void;
+}
+/**
+ * Runs an operation with a timeout.
+ *
+ * - `timeoutMs <= 0` disables the timeout.
+ * - On timeout the operation's AbortSignal is aborted and a
+ *   RuntimeTimeoutError is thrown.
+ * - The abandoned operation promise always has a rejection handler
+ *   attached, so a late failure can never become an unhandled
+ *   rejection.
+ */
+export declare function withRuntimeTimeout<T>(operation: TimeoutAwareOperation<T>, timeoutMs: number, options?: RuntimeTimeoutOptions): Promise<T>;
+//# sourceMappingURL=runtimeTimeout.d.ts.map

package/dist/runtime/runtimeTimeout.js

@@ -0,0 +1,42 @@
+import { RuntimeTimeoutError } from "./runtimeError/runtimeError.specialized.js";
+/**
+ * Runs an operation with a timeout.
+ *
+ * - `timeoutMs <= 0` disables the timeout.
+ * - On timeout the operation's AbortSignal is aborted and a
+ *   RuntimeTimeoutError is thrown.
+ * - The abandoned operation promise always has a rejection handler
+ *   attached, so a late failure can never become an unhandled
+ *   rejection.
+ */
+export async function withRuntimeTimeout(operation, timeoutMs, options = {}) {
+    const controller = new AbortController();
+    if (timeoutMs <= 0) {
+        return operation(controller.signal);
+    }
+    let timer;
+    const pending = operation(controller.signal);
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new RuntimeTimeoutError(options.message ??
+                `Runtime operation exceeded the configured timeout of ${timeoutMs}ms.`, timeoutMs, options.error));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([pending, timeout]);
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            pending.catch((lateError) => {
+                options.onLateRejection?.(lateError);
+            });
+        }
+        throw error;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=runtimeTimeout.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/core",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Application lifecycle management, execution context propagation, and runtime orchestration for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,24 +44,19 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "clean": "tsc -p tsconfig.json --clean"
-  },
   "devDependencies": {
     "@types/node": "^26.4.1",
-    "typescript": "^7.0.2",
+    "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@zudojs/errors": "^0.0.1",
-    "@zudojs/constants": "^0.0.1",
-    "@zudojs/messaging": "^0.0.1"
+    "@zudojs/errors": "1.0.0",
+    "@zudojs/constants": "1.0.0"
   },
   "license": "MIT",
   "publishConfig": {
@@ -78,8 +73,19 @@
     "context"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/core"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
   }
-}
+}