@executablemd/runtime 0.4.1 → 0.5.0

package/esm/apis.js

@@ -63,6 +63,7 @@ import { fetch as effectionFetch } from "@effectionx/fetch";
 import { readTextFile as fsReadTextFile, stat as fsStat, globToRegExp, walk } from "@effectionx/fs";
 import { exec as processExec } from "@effectionx/process";
 import { each, race, sleep } from "effection";
+import { timeout as contextualTimeout } from "./config.js";
 function* withTimeout(label, timeout, operation) {
     if (timeout === undefined) {
         return yield* operation;
@@ -92,7 +93,8 @@ export const API = {
             if (!cmd) {
                 throw new Error("exec: command array must not be empty");
             }
-            const result = yield* withTimeout(`exec(${cmd})`, timeout, processExec(cmd, {
+            const effectiveTimeout = timeout ?? (yield* contextualTimeout);
+            const result = yield* withTimeout(`exec(${cmd})`, effectiveTimeout, processExec(cmd, {
                 arguments: args,
                 cwd,
                 env,
@@ -162,7 +164,7 @@ export const API = {
      */
     Fetch: createApi("runtime.fetch", {
         *fetch(input, init) {
-            const timeout = init?.timeout;
+            const timeout = init?.timeout ?? (yield* contextualTimeout);
             const response = yield* withTimeout(`fetch(${input})`, timeout, effectionFetch(input, {
                 method: init?.method,
                 headers: init?.headers,
@@ -205,7 +207,7 @@ export const API = {
      *
      * Default handler throws — platform-specific middleware must be
      * installed via `yield* API.Compiler.around(...)` before use.
-     * See `core/src/deno-compiler.ts` for the Deno implementation.
+     * See `packages/core/src/deno-compiler.ts` for the Deno implementation.
      */
     Compiler: createApi("runtime.compiler", {
         // deno-lint-ignore require-yield

package/esm/config.js

@@ -0,0 +1,29 @@
+/**
+ * Config Api — shared execution configuration with pluggable middleware.
+ *
+ * Supplies the contextual timeout in milliseconds. Process, Fetch, and
+ * Agent operations read it when a call does not provide an explicit
+ * timeout. Override it for a scope with:
+ *
+ * ```typescript
+ * yield* Config.around({ timeout: () => 30_000 }, { at: "min" });
+ * ```
+ */
+import { createApi } from "@effectionx/context-api";
+export const Config = createApi("Config", {
+    timeout: 120_000,
+});
+/**
+ * The validated contextual timeout. Always a positive, finite number of
+ * milliseconds — a middleware-supplied value that is not valid fails loudly
+ * here rather than silently disabling or corrupting timeouts downstream.
+ */
+export const timeout = {
+    *[Symbol.iterator]() {
+        const value = yield* Config.operations.timeout;
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+            throw new Error(`Config timeout must be a positive, finite number of milliseconds, got ${String(value)}`);
+        }
+        return value;
+    },
+};

package/esm/mod.js

@@ -11,6 +11,7 @@
  * - `API.Fetch` — HTTP requests (`fetch`)
  * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
  * - `API.Compiler` — block compilation (`compile`)
+ * - `Config` — shared execution config (`timeout`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
@@ -18,3 +19,4 @@
 export { API } from "./apis.js";
 export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.js";
 export { findFreePort } from "./find-free-port.js";
+export { Config, timeout } from "./config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {

package/types/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Config Api — shared execution configuration with pluggable middleware.
+ *
+ * Supplies the contextual timeout in milliseconds. Process, Fetch, and
+ * Agent operations read it when a call does not provide an explicit
+ * timeout. Override it for a scope with:
+ *
+ * ```typescript
+ * yield* Config.around({ timeout: () => 30_000 }, { at: "min" });
+ * ```
+ */
+import { type Api } from "@effectionx/context-api";
+import type { Operation } from "effection";
+export interface ConfigApi {
+    /** Shared timeout in milliseconds. */
+    timeout: number;
+}
+export declare const Config: Api<ConfigApi>;
+/**
+ * The validated contextual timeout. Always a positive, finite number of
+ * milliseconds — a middleware-supplied value that is not valid fails loudly
+ * here rather than silently disabling or corrupting timeouts downstream.
+ */
+export declare const timeout: Operation<number>;

package/types/mod.d.ts

@@ -11,6 +11,7 @@
  * - `API.Fetch` — HTTP requests (`fetch`)
  * - `API.Env` — environment variables and platform info (`cwd`, `env`, `platform`)
  * - `API.Compiler` — block compilation (`compile`)
+ * - `Config` — shared execution config (`timeout`)
  *
  * See `apis.ts` for architecture rationale.
  * See `@executablemd/runtime/test` for composable test stubs.
@@ -19,3 +20,5 @@ export { API } from "./apis.js";
 export { exec, readTextFile, stat, glob, fetch, cwd, env, platform, compile } from "./apis.js";
 export type { ResponseHeaders, RuntimeFetchResponse, StatResult } from "./apis.js";
 export { findFreePort } from "./find-free-port.js";
+export { Config, timeout } from "./config.js";
+export type { ConfigApi } from "./config.js";