@iota-uz/sdk 0.16.0 → 0.17.1

package/dist/testing/driver.js

@@ -1,74 +1,146 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
 import { randomUUID } from 'node:crypto';
+export class DriverError extends Error {
+    code;
+    operation;
+    environmentId;
+    artifactDirectory;
+    descriptor;
+    causes;
+    constructor(message, details) {
+        super(message, { cause: details.cause });
+        this.name = 'DriverError';
+        this.code = details.code;
+        this.operation = details.operation;
+        this.environmentId = details.environmentId;
+        this.artifactDirectory = details.artifactDirectory;
+        this.descriptor = details.descriptor;
+        this.causes = details.causes ?? [];
+    }
+}
 /** One persistent, shell-free driver owns every environment it creates. */
 export function createProcessEnvironmentDriver(options) {
     const timeoutMs = options.timeoutMs ?? 120_000;
-    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
-        throw new Error('timeoutMs must be a positive integer');
+    const closeTimeoutMs = options.closeTimeoutMs ?? 35_000;
+    const killTimeoutMs = options.killTimeoutMs ?? 10_000;
+    for (const [name, value] of Object.entries({ timeoutMs, closeTimeoutMs, killTimeoutMs })) {
+        if (!Number.isInteger(value) || value <= 0)
+            throw new Error(`${name} must be a positive integer`);
+    }
     const child = spawn(options.command, [...options.args ?? []], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'] });
     const pending = new Map();
+    const environments = new Map();
     let stderr = '';
     let closed = false;
+    let closing;
     child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-16_384); });
-    const rejectAll = (error) => {
+    const failure = (request, code, message, cause) => new DriverError(message, {
+        code, operation: request.operation, environmentId: request.environmentId,
+        artifactDirectory: request.environmentId ? environments.get(request.environmentId)?.artifactDirectory : undefined, cause,
+    });
+    const rejectAll = (code, message, cause) => {
         closed = true;
-        for (const request of pending.values()) {
-            clearTimeout(request.timer);
-            request.reject(error);
+        for (const item of pending.values()) {
+            clearTimeout(item.timer);
+            item.reject(failure(item.request, code, message, cause));
         }
         pending.clear();
     };
     const exit = new Promise((resolve, reject) => {
-        child.once('error', error => { rejectAll(error); reject(error); });
+        child.once('error', error => {
+            rejectAll('process_error', error.message, error);
+            reject(failure({ operation: 'close' }, 'process_error', error.message, error));
+        });
         child.once('exit', (code, signal) => {
-            const error = new Error(`Test environment driver exited (${code ?? signal}): ${stderr}`);
-            rejectAll(error);
+            const message = `Test environment driver exited (${code ?? signal}): ${stderr}`;
+            rejectAll('process_exit', message);
             if (code === 0)
                 resolve();
             else
-                reject(error);
+                reject(failure({ operation: 'close' }, 'process_exit', message));
         });
     });
-    // Keep unexpected process exits observed even before the caller closes the driver.
     void exit.catch(() => { });
     const lines = createInterface({ input: child.stdout });
+    const close = () => closing ??= (async () => {
+        closed = true;
+        child.stdin.end();
+        let timer;
+        const settled = async (ms) => {
+            try {
+                return await Promise.race([exit.then(() => true), new Promise(resolve => { timer = setTimeout(() => resolve(false), ms); })]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+        try {
+            if (await settled(closeTimeoutMs))
+                return;
+            child.kill('SIGINT');
+            if (await settled(killTimeoutMs))
+                return;
+            child.kill('SIGKILL');
+            // Only this spawned driver receives the hard kill; never await its exit
+            // beyond the shutdown deadline. Its rejection remains observed above.
+            throw failure({ operation: 'close' }, 'close_timeout', 'Test environment driver did not close before its shutdown deadline');
+        }
+        finally {
+            lines.close();
+        }
+    })();
     lines.on('line', line => {
         let response;
+        const validError = (error) => error !== null && typeof error === 'object' && typeof error.code === 'string' && typeof error.message === 'string' && (error.causes === undefined || Array.isArray(error.causes) && error.causes.every(validError));
         try {
             response = JSON.parse(line);
+            if (response === null || typeof response !== 'object' || typeof response.id !== 'string' || (response.error !== undefined && !validError(response.error)))
+                throw new Error('Invalid response envelope');
         }
         catch {
-            rejectAll(new Error('Test environment driver emitted invalid JSON'));
-            child.kill('SIGINT');
+            rejectAll('invalid_response', 'Test environment driver emitted invalid JSON');
+            void close().catch(() => { });
             return;
         }
-        const request = pending.get(response.id);
-        if (!request)
+        const item = pending.get(response.id);
+        if (!item)
             return;
         pending.delete(response.id);
-        clearTimeout(request.timer);
-        if (response.error)
-            request.reject(new Error(`${response.error.code}: ${response.error.message}`));
+        clearTimeout(item.timer);
+        if (response.error) {
+            const convert = (error) => new DriverError(`${error.code}: ${error.message}`, {
+                code: error.code, operation: error.operation ?? item.request.operation,
+                environmentId: error.environmentId ?? response.descriptor?.environmentId ?? item.request.environmentId,
+                artifactDirectory: error.artifactDirectory ?? response.descriptor?.artifactDirectory ?? (item.request.environmentId ? environments.get(item.request.environmentId)?.artifactDirectory : undefined),
+                descriptor: response.descriptor, causes: error.causes?.map(convert),
+            });
+            item.reject(convert(response.error));
+        }
         else
-            request.resolve(response.descriptor);
+            item.resolve(response.descriptor);
+    });
+    child.stdin.on('error', error => {
+        rejectAll('write_failed', error.message, error);
+        void close().catch(() => { });
     });
     const invoke = (request) => {
         if (closed)
-            return Promise.reject(new Error('Test environment driver is closed'));
+            return Promise.reject(failure(request, 'driver_closed', 'Test environment driver is closed'));
         const id = randomUUID();
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 pending.delete(id);
-                reject(new Error('Test environment driver request timed out'));
-                child.kill('SIGINT');
+                reject(failure(request, 'request_timeout', 'Test environment driver request timed out'));
+                void close().catch(() => { });
             }, timeoutMs);
-            pending.set(id, { resolve, reject, timer });
+            pending.set(id, { request, resolve, reject, timer });
             child.stdin.write(`${JSON.stringify({ id, ...request })}\n`, error => {
                 if (error) {
                     clearTimeout(timer);
                     pending.delete(id);
-                    reject(error);
+                    reject(failure(request, 'write_failed', error.message, error));
                 }
             });
         });
@@ -77,14 +149,15 @@ export function createProcessEnvironmentDriver(options) {
         start: async (workerIndex) => {
             const descriptor = await invoke({ operation: 'start', spec: options.spec(workerIndex) });
             if (!descriptor?.environmentId || !descriptor?.baseURL || !descriptor?.artifactDirectory) {
-                child.kill('SIGINT');
-                throw new Error('Incomplete test environment descriptor');
+                void close().catch(() => { });
+                throw new DriverError('Incomplete test environment descriptor', { code: 'invalid_descriptor', operation: 'start', environmentId: descriptor?.environmentId, artifactDirectory: descriptor?.artifactDirectory, descriptor });
             }
-            return { ...descriptor, runId: descriptor.environmentId, artifactDir: descriptor.artifactDirectory };
+            const environment = { ...descriptor, runId: descriptor.environmentId, artifactDir: descriptor.artifactDirectory };
+            environments.set(environment.environmentId, environment);
+            return environment;
         },
-        // Driver start returns only after the configured real readiness probe succeeds.
         ready: async () => { },
-        stop: async (environment) => { await invoke({ operation: 'stop', environmentId: environment.environmentId }); },
+        stop: async (environment) => { await invoke({ operation: 'stop', environmentId: environment.environmentId }); environments.delete(environment.environmentId); },
     };
-    return { lifecycle, close: async () => { child.stdin.end(); await exit; lines.close(); } };
+    return { lifecycle, close };
 }

package/dist/testing/fixtures.d.ts

@@ -1,5 +1,31 @@
 import type { Browser, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from '@playwright/test';
 import { type EnvironmentDescriptor, type EnvironmentLifecycle, type ScenarioControl, type ScenarioLease, type IdentityLease } from './index.js';
+export interface EnvironmentLeaseInfo {
+    workerIndex: number;
+    parallelIndex: number;
+    testId?: string;
+    retry?: number;
+    runName: string;
+    environmentName: string;
+}
+type LeaseFixtureOptions<E extends EnvironmentDescriptor> = {
+    scope: 'test' | 'worker';
+    runName?: string;
+    name?(info: Omit<EnvironmentLeaseInfo, 'environmentName'>): string;
+    lifecycle(info: EnvironmentLeaseInfo): EnvironmentLifecycle<E> & {
+        close?(): Promise<void>;
+    };
+};
+export declare function createEnvironmentLeaseTest<T extends {}, W extends {}, E extends EnvironmentDescriptor>(base: TestType<T, W>, options: LeaseFixtureOptions<E> & {
+    scope: 'test';
+}): TestType<T & {
+    environmentLease: E;
+}, W>;
+export declare function createEnvironmentLeaseTest<T extends {}, W extends {}, E extends EnvironmentDescriptor>(base: TestType<T, W>, options: LeaseFixtureOptions<E> & {
+    scope: 'worker';
+}): TestType<T, W & {
+    environmentLease: E;
+}>;
 export declare function createEnvironmentTest<E extends EnvironmentDescriptor, Input, State, Key, Identity>(base: TestType<PlaywrightTestArgs & PlaywrightTestOptions, PlaywrightWorkerArgs & PlaywrightWorkerOptions>, options: {
     lifecycle: EnvironmentLifecycle<E>;
     scenarios(environment: E): ScenarioControl<Input, State>;
@@ -11,3 +37,4 @@ export declare function createEnvironmentTest<E extends EnvironmentDescriptor, I
     environment: E;
     workerIdentity: IdentityLease<Key, Identity>;
 }>;
+export {};

package/dist/testing/fixtures.js

@@ -1,4 +1,20 @@
 import { lazyIdentities, withEnvironment } from './index.js';
+import { preservingCleanup, withEnvironmentLease } from './lease.js';
+export function createEnvironmentLeaseTest(base, options) {
+    const runName = options.runName ?? crypto.randomUUID();
+    const fixtures = {
+        environmentLease: [async ({}, use, info) => {
+                const identity = { workerIndex: info.workerIndex, parallelIndex: info.parallelIndex, testId: info.testId, retry: info.retry, runName };
+                const environmentName = options.name?.(identity) ?? `${runName}-w${info.workerIndex}-${info.testId ? `t${info.testId}-r${info.retry}` : 'worker'}`;
+                const lifecycle = options.lifecycle({ ...identity, environmentName });
+                await withEnvironmentLease(lifecycle, info.workerIndex, use, { closeDriver: lifecycle.close?.bind(lifecycle) });
+            }, { scope: options.scope }],
+        baseURL: async ({ environmentLease }, use) => { await use(environmentLease.baseURL); },
+    };
+    // The runtime scope selects which fixture namespace owns the same lease;
+    // overloads preserve that namespace for the consumer's injected base test.
+    return base.extend(fixtures);
+}
 export function createEnvironmentTest(base, options) {
     return base.extend({
         environment: [async ({}, use, info) => {
@@ -12,19 +28,18 @@ export function createEnvironmentTest(base, options) {
         scenario: async ({ environment }, use, info) => {
             const control = options.scenarios(environment);
             const scopes = [];
-            try {
+            await preservingCleanup(async () => {
                 await use(async (input) => {
                     const scope = `${environment.runId}-w${info.workerIndex}-r${info.retry}-${crypto.randomUUID()}`;
                     scopes.push(scope);
                     return control.prepare(input, scope);
                 });
-            }
-            finally {
+            }, async () => {
                 const results = await Promise.allSettled(scopes.map(scope => control.dispose(scope)));
                 const errors = results.filter((result) => result.status === 'rejected').map(result => result.reason);
                 if (errors.length)
                     throw new AggregateError(errors, 'Scenario teardown failed');
-            }
+            });
         },
     });
 }

package/dist/testing/index.d.ts

@@ -55,8 +55,9 @@ export declare function withScenario<Input, State, Result>(control: ScenarioCont
 export declare function lazyIdentities<Key, State>(create: (identity: Key) => Promise<State>): (identity: Key) => Promise<State>;
 export type ScenarioLease<Input, State> = (input: Input) => Promise<State>;
 export type IdentityLease<Key, State> = (identity: Key) => Promise<State>;
-export { createEnvironmentTest } from './fixtures.js';
-export { createProcessEnvironmentDriver, type DriverDescriptor } from './driver.js';
+export { createEnvironmentTest, createEnvironmentLeaseTest, type EnvironmentLeaseInfo } from './fixtures.js';
+export { createProcessEnvironmentDriver, DriverError, type DriverDescriptor } from './driver.js';
+export { acquireEnvironmentLease, withEnvironmentLease, preservingCleanup, type EnvironmentLease, type LeaseOptions } from './lease.js';
 export declare function expectFontsReady(page: Page, options?: WaitOptions): Promise<void>;
 export declare function expectChartsReady(charts: Locator, options?: WaitOptions & {
     allowEmpty?: boolean;

package/dist/testing/index.js

@@ -189,36 +189,10 @@ export async function actionAndHtmxResponse(page, match, action, options = {}) {
 }
 /** Teardown runs even when readiness, the scenario or the browser assertion fails. */
 export async function withEnvironment(lifecycle, workerIndex, use) {
-    const environment = await lifecycle.start(workerIndex);
-    let failed = false;
-    let failure;
-    try {
-        await lifecycle.ready(environment);
-        return await use(environment);
-    }
-    catch (error) {
-        failed = true;
-        failure = error;
-        throw error;
-    }
-    finally {
-        try {
-            await lifecycle.stop(environment);
-        }
-        catch (error) {
-            if (failed)
-                throw new AggregateError([failure, error], 'Environment failed and teardown failed');
-            throw error;
-        }
-    }
+    return withEnvironmentLease(lifecycle, workerIndex, use);
 }
 export async function withScenario(control, input, scopeId, use) {
-    try {
-        return await use(await control.prepare(input, scopeId));
-    }
-    finally {
-        await control.dispose(scopeId);
-    }
+    return preservingCleanup(async () => use(await control.prepare(input, scopeId)), () => control.dispose(scopeId));
 }
 /** Instantiate per worker/environment; identities are materialised only when requested. */
 export function lazyIdentities(create) {
@@ -232,8 +206,10 @@ export function lazyIdentities(create) {
         return state;
     };
 }
-export { createEnvironmentTest } from './fixtures.js';
-export { createProcessEnvironmentDriver } from './driver.js';
+export { createEnvironmentTest, createEnvironmentLeaseTest } from './fixtures.js';
+export { createProcessEnvironmentDriver, DriverError } from './driver.js';
+import { preservingCleanup, withEnvironmentLease } from './lease.js';
+export { acquireEnvironmentLease, withEnvironmentLease, preservingCleanup } from './lease.js';
 export async function expectFontsReady(page, options = {}) {
     await page.waitForFunction(() => document.fonts.status === 'loaded', undefined, { timeout: timeout(options) });
 }

package/dist/testing/lease.d.ts

@@ -0,0 +1,11 @@
+import type { EnvironmentDescriptor, EnvironmentLifecycle } from './index.js';
+export interface EnvironmentLease<E extends EnvironmentDescriptor> {
+    environment: E;
+    close(): Promise<void>;
+}
+export interface LeaseOptions {
+    closeDriver?(): Promise<void>;
+}
+export declare function preservingCleanup<Result>(use: () => Promise<Result>, cleanup: () => Promise<void>): Promise<Result>;
+export declare function acquireEnvironmentLease<E extends EnvironmentDescriptor>(lifecycle: EnvironmentLifecycle<E>, workerIndex?: number, options?: LeaseOptions): Promise<EnvironmentLease<E>>;
+export declare function withEnvironmentLease<E extends EnvironmentDescriptor, Result>(lifecycle: EnvironmentLifecycle<E>, workerIndex: number, use: (environment: E) => Promise<Result>, options?: LeaseOptions): Promise<Result>;

package/dist/testing/lease.js

@@ -0,0 +1,44 @@
+export async function preservingCleanup(use, cleanup) {
+    let failed = false;
+    let failure;
+    try {
+        return await use();
+    }
+    catch (error) {
+        failed = true;
+        failure = error;
+        throw error;
+    }
+    finally {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            if (failed)
+                throw new AggregateError([failure, error], 'Operation and cleanup failed');
+            throw error;
+        }
+    }
+}
+export async function acquireEnvironmentLease(lifecycle, workerIndex = 0, options = {}) {
+    let environment;
+    try {
+        environment = await lifecycle.start(workerIndex);
+    }
+    catch (error) {
+        return preservingCleanup(async () => { throw error; }, async () => { await options.closeDriver?.(); });
+    }
+    let closing;
+    const close = () => closing ??= preservingCleanup(() => lifecycle.stop(environment), async () => { await options.closeDriver?.(); });
+    try {
+        await lifecycle.ready(environment);
+    }
+    catch (error) {
+        return preservingCleanup(async () => { throw error; }, close);
+    }
+    return { environment, close };
+}
+export async function withEnvironmentLease(lifecycle, workerIndex, use, options = {}) {
+    const lease = await acquireEnvironmentLease(lifecycle, workerIndex, options);
+    return preservingCleanup(() => use(lease.environment), lease.close);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iota-uz/sdk",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Canonical JavaScript distribution for iota-sdk.",
   "license": "MIT",
   "repository": {

package/dist/lens/ChartHost-DTnhnwkn.js

@@ -1,68 +0,0 @@
-import { jsxs as C, jsx as v } from "react/jsx-runtime";
-import { useRef as i, useState as H, useCallback as S, useEffect as p } from "react";
-import { u as $ } from "./index-BBtBPnTb.js";
-import "@iota-uz/sdk/client-host";
-function U({ input: o, panelId: E, onSelect: N, onHover: R, adapter: u, label: j, drillable: b = !1, resetZoomKey: g = 0 }) {
-  const d = i(null), t = i(), h = i(o), f = i({ onSelect: N, onHover: R }), [m, c] = H(), w = $();
-  h.current = o, f.current = { onSelect: N, onHover: R };
-  const s = S((e, a) => {
-    const r = e instanceof Error ? e : new Error(a);
-    return console.error(`[lens] chart panel ${E ?? "(unknown)"} failed to render`, r), r;
-  }, [E]);
-  return p(() => {
-    let e = !0;
-    const a = {
-      onSelect: (r, n, l) => {
-        var k, x;
-        return (x = (k = f.current).onSelect) == null ? void 0 : x.call(k, r, n, l);
-      },
-      onHover: (r) => {
-        var n, l;
-        return (l = (n = f.current).onHover) == null ? void 0 : l.call(n, r);
-      }
-    };
-    return (u ? Promise.resolve(u) : import("./index-CmXDbBaF.js").then(({ getChartAdapter: r }) => r(h.current.kind))).then((r) => {
-      if (!(!e || !d.current)) {
-        c(void 0);
-        try {
-          t.current = r.mount(d.current, h.current, a);
-        } catch (n) {
-          c(s(n, "chart failed to render"));
-        }
-      }
-    }).catch((r) => {
-      e && c(s(r, "chart adapter failed to load"));
-    }), () => {
-      var r;
-      e = !1, (r = t.current) == null || r.dispose(), t.current = void 0;
-    };
-  }, [u, s]), p(() => {
-    if (t.current)
-      try {
-        t.current.update(o);
-      } catch (e) {
-        c(s(e, "chart failed to update"));
-      }
-  }, [o, s]), p(() => {
-    var e, a;
-    g > 0 && ((a = (e = t.current) == null ? void 0 : e.resetZoom) == null || a.call(e));
-  }, [g]), /* @__PURE__ */ C(
-    "div",
-    {
-      className: `lens-chart-host${b ? " lens-chart-host-drillable" : ""}`,
-      "aria-label": j,
-      role: "img",
-      "data-drillable": b || void 0,
-      children: [
-        /* @__PURE__ */ v("div", { ref: d, className: "lens-chart-canvas" }),
-        m && /* @__PURE__ */ C("div", { className: "lens-chart-load-error", role: "alert", children: [
-          /* @__PURE__ */ v("span", { className: "lens-chart-load-error-message", children: w("chart.error", "Unable to render chart.") }),
-          m.message && /* @__PURE__ */ v("span", { className: "lens-chart-load-error-detail", children: m.message })
-        ] })
-      ]
-    }
-  );
-}
-export {
-  U as C
-};