@oyaprotocol/utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Shutt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @oyaprotocol/utils
+
+Small shared utilities for hardened Oya kernel packages.
+
+## Public Entrypoint
+
+- `@oyaprotocol/utils`
+
+## Validation Helpers
+
+- `assertAsciiBytes(bytes, message)`
+- `assertBytes32HexString(value, label)`
+- `assertCanonicalCid(value, label)`: requires CIDv1, lowercase unpadded Base32, and a SHA-256 multihash with a 32-byte digest. Returns the original string; rejects whitespace, paths, URIs, CIDv0, alternate bases, nonminimal integer encodings, and invalid Base32 padding bits. Checks codec encoding without maintaining a codec registry allowlist. This validates identifier structure, not content or availability.
+- `assertNonEmptyString(value, label)`
+- `assertHexData(value, label)`
+- `assertHexString(value, label)`
+- `assertPositiveInteger(value, label)`
+- `assertNonNegativeInteger(value, label)`
+- `assertUint256(value, name)`: requires a bigint from `0n` through `(1n << 256n) - 1n`, returning the original value.
+- `assertHeadersObject(headers, label, options)`
+- `isPlainObject(value)`
+- `parseBytes(value, name, size?)`: validates `0x`-prefixed, byte-aligned hex, optionally requiring an exact byte count. Returns the original string without trimming; accepts `0x` when no size is required.
+
+## HTTP Utilities
+
+- `CreateHttpConfigOptions`
+- `HttpConfig`
+- `createHttpConfig(options, normalizeUrl?)`
+- `HttpFetchLike<TOptions, TResponse>`
+- `HttpPostFetchLike<TBody, TResponse>`
+- `HttpPostFetchOptions<TBody>`
+- `HttpStatusError`
+- `HttpStatusErrorOptions`
+- `HttpTextResponse`
+- `RETRYABLE_HTTP_NETWORK_ERROR_CODES` (runtime-immutable `ReadonlySet<string>` with the full ES2025 Set algebra API)
+- `hasRetryableNetworkErrorCode(error)`
+- `readErrorStringChain(error, key)`
+
+## Async Utilities
+
+- `assertTimerMs(value, name)`: validates a positive integer duration up to 2,147,483,647 ms, avoiding timer overflow.
+- `AbortSignalHandle`
+- `RunWithRetryAttemptContext`
+- `RunWithRetryOptions`
+- `createTimeoutSignal(timeoutMs)`
+- `combineAbortSignals(signals)`
+- `invokeWithAbort(createPromise, signal)`
+- `runWithRetry(options)`
+- `throwIfSignalAborted(signal, message, cause)`
+- `waitForRetryDelay(options)`

package/dist/async-utils.d.ts

@@ -0,0 +1,31 @@
+interface AbortSignalHandle {
+    signal: AbortSignal | undefined;
+    cleanup: (() => void) | null;
+}
+interface RunWithRetryAttemptContext {
+    attempt: number;
+    signal: AbortSignal | undefined;
+}
+interface RunWithRetryOptions<TResult> {
+    maxRetries: number;
+    retryDelayMs: number;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    abortErrorMessage: string;
+    shouldRetry(error: unknown): boolean;
+    normalizeError(error: unknown): Error;
+    run(context: RunWithRetryAttemptContext): Promise<TResult>;
+}
+declare function assertTimerMs(value: unknown, name: string): number;
+declare function createTimeoutSignal(timeoutMs: number): AbortSignalHandle;
+declare function combineAbortSignals(signals: Array<AbortSignal | undefined>): AbortSignalHandle;
+declare function invokeWithAbort<T>(createPromise: () => Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+declare function throwIfSignalAborted(signal: AbortSignal | undefined, message: string, cause: unknown): void;
+declare function waitForRetryDelay({ retryDelayMs, signal, abortErrorMessage, }: {
+    retryDelayMs: number;
+    signal: AbortSignal | undefined;
+    abortErrorMessage: string;
+}): Promise<void>;
+declare function runWithRetry<TResult>({ maxRetries, retryDelayMs, timeoutMs, signal, abortErrorMessage, shouldRetry, normalizeError, run, }: RunWithRetryOptions<TResult>): Promise<TResult>;
+export { assertTimerMs, combineAbortSignals, createTimeoutSignal, invokeWithAbort, runWithRetry, throwIfSignalAborted, waitForRetryDelay, };
+export type { AbortSignalHandle, RunWithRetryAttemptContext, RunWithRetryOptions, };

package/dist/async-utils.js

@@ -0,0 +1,186 @@
+import { assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, } from './validation-utils.js';
+function assertTimerMs(value, name) {
+    const duration = assertPositiveInteger(value, name);
+    if (duration > 2_147_483_647) {
+        throw new Error(`${name} must not exceed 2147483647 ms.`);
+    }
+    return duration;
+}
+function createTimeoutSignal(timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('Request timed out.')), timeoutMs);
+    controller.signal.addEventListener('abort', () => clearTimeout(timer), { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => clearTimeout(timer),
+    };
+}
+function combineAbortSignals(signals) {
+    const presentSignals = signals.filter((signal) => signal !== undefined);
+    if (presentSignals.length === 0) {
+        return {
+            signal: undefined,
+            cleanup: null,
+        };
+    }
+    if (presentSignals.length === 1) {
+        return {
+            signal: presentSignals[0],
+            cleanup: null,
+        };
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return {
+            signal: AbortSignal.any(presentSignals),
+            cleanup: null,
+        };
+    }
+    const controller = new AbortController();
+    const abortedSignal = presentSignals.find((signal) => signal.aborted);
+    if (abortedSignal) {
+        controller.abort(abortedSignal.reason);
+        return {
+            signal: controller.signal,
+            cleanup: null,
+        };
+    }
+    const listeners = [];
+    for (const signal of presentSignals) {
+        const listener = () => {
+            controller.abort(signal.reason);
+        };
+        signal.addEventListener('abort', listener, { once: true });
+        listeners.push({ signal, listener });
+    }
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            for (const { signal, listener } of listeners) {
+                signal.removeEventListener('abort', listener);
+            }
+        },
+    };
+}
+async function invokeWithAbort(createPromise, signal) {
+    if (!signal) {
+        return await createPromise();
+    }
+    if (signal.aborted) {
+        throw signal.reason ?? new Error('Operation aborted.');
+    }
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        const finishResolve = (value) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        };
+        const finishReject = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        };
+        const onAbort = () => {
+            finishReject(signal.reason ?? new Error('Operation aborted.'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        let promise;
+        try {
+            promise = createPromise();
+        }
+        catch (error) {
+            finishReject(error);
+            return;
+        }
+        promise.then(finishResolve, finishReject);
+    });
+}
+function throwIfSignalAborted(signal, message, cause) {
+    if (signal?.aborted) {
+        throw new Error(message, { cause });
+    }
+}
+async function waitForRetryDelay({ retryDelayMs, signal, abortErrorMessage, }) {
+    if (retryDelayMs <= 0) {
+        return;
+    }
+    throwIfSignalAborted(signal, abortErrorMessage, signal?.reason);
+    await new Promise((resolve) => {
+        if (!signal) {
+            setTimeout(resolve, retryDelayMs);
+            return;
+        }
+        let settled = false;
+        let timer = null;
+        const finish = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            signal.removeEventListener('abort', finish);
+            resolve();
+        };
+        signal.addEventListener('abort', finish, { once: true });
+        if (signal.aborted) {
+            finish();
+            return;
+        }
+        timer = setTimeout(finish, retryDelayMs);
+    });
+    throwIfSignalAborted(signal, abortErrorMessage, signal?.reason);
+}
+async function runWithRetry({ maxRetries, retryDelayMs, timeoutMs, signal, abortErrorMessage, shouldRetry, normalizeError, run, }) {
+    const retryLimit = assertNonNegativeInteger(maxRetries, 'maxRetries');
+    const retryDelay = assertNonNegativeInteger(retryDelayMs, 'retryDelayMs');
+    const requestTimeoutMs = assertPositiveInteger(timeoutMs, 'timeoutMs');
+    const callerAbortErrorMessage = assertNonEmptyString(abortErrorMessage, 'abortErrorMessage');
+    if (typeof shouldRetry !== 'function') {
+        throw new Error('shouldRetry must be provided as a function.');
+    }
+    if (typeof normalizeError !== 'function') {
+        throw new Error('normalizeError must be provided as a function.');
+    }
+    if (typeof run !== 'function') {
+        throw new Error('run must be provided as a function.');
+    }
+    let lastError = null;
+    for (let attempt = 1; attempt <= retryLimit + 1; attempt += 1) {
+        const timeoutSignal = createTimeoutSignal(requestTimeoutMs);
+        const requestSignal = combineAbortSignals([signal, timeoutSignal.signal]);
+        try {
+            return await invokeWithAbort(() => run({
+                attempt,
+                signal: requestSignal.signal,
+            }), requestSignal.signal);
+        }
+        catch (error) {
+            lastError = error;
+            throwIfSignalAborted(signal, callerAbortErrorMessage, error);
+            if (attempt <= retryLimit && shouldRetry(error)) {
+                await waitForRetryDelay({
+                    retryDelayMs: retryDelay,
+                    signal,
+                    abortErrorMessage: callerAbortErrorMessage,
+                });
+                continue;
+            }
+            break;
+        }
+        finally {
+            requestSignal.cleanup?.();
+            timeoutSignal.cleanup?.();
+        }
+    }
+    throw normalizeError(lastError);
+}
+export { assertTimerMs, combineAbortSignals, createTimeoutSignal, invokeWithAbort, runWithRetry, throwIfSignalAborted, waitForRetryDelay, };
+//# sourceMappingURL=async-utils.js.map

package/dist/async-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-utils.js","sourceRoot":"","sources":["../src/async-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,GACxB,MAAM,uBAAuB,CAAC;AAuB/B,SAAS,aAAa,CAAC,KAAc,EAAE,IAAY;IAC/C,MAAM,QAAQ,GAAG,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACpD,IAAI,QAAQ,GAAG,aAAa,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,iCAAiC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,QAAQ,CAAC;AACpB,CAAC;AAED,SAAS,mBAAmB,CAAC,SAAiB;IAC1C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC7F,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACvF,OAAO;QACH,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC;KACrC,CAAC;AACN,CAAC;AAED,SAAS,mBAAmB,CAAC,OAAuC;IAChE,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAyB,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC/F,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;YACH,MAAM,EAAE,SAAS;YACjB,OAAO,EAAE,IAAI;SAChB,CAAC;IACN,CAAC;IACD,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO;YACH,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;YACzB,OAAO,EAAE,IAAI;SAChB,CAAC;IACN,CAAC;IACD,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACxC,OAAO;YACH,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC;YACvC,OAAO,EAAE,IAAI;SAChB,CAAC;IACN,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,aAAa,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtE,IAAI,aAAa,EAAE,CAAC;QAChB,UAAU,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO;YACH,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE,IAAI;SAChB,CAAC;IACN,CAAC;IAED,MAAM,SAAS,GAA4D,EAAE,CAAC;IAC9E,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,GAAG,EAAE;YAClB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO;QACH,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,GAAG,EAAE;YACV,KAAK,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,SAAS,EAAE,CAAC;gBAC3C,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAClD,CAAC;QACL,CAAC;KACJ,CAAC;AACN,CAAC;AAED,KAAK,UAAU,eAAe,CAC1B,aAA+B,EAC/B,MAA+B;IAE/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,OAAO,MAAM,aAAa,EAAE,CAAC;IACjC,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,aAAa,GAAG,CAAC,KAAQ,EAAE,EAAE;YAC/B,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO;YACX,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC,CAAC;QACF,MAAM,YAAY,GAAG,CAAC,KAAc,EAAE,EAAE;YACpC,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO;YACX,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC7C,MAAM,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAG,EAAE;YACjB,YAAY,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;QACnE,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,IAAI,OAAmB,CAAC;QACxB,IAAI,CAAC;YACD,OAAO,GAAG,aAAa,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACP,CAAC;AAED,SAAS,oBAAoB,CACzB,MAA+B,EAC/B,OAAe,EACf,KAAc;IAEd,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,EAC7B,YAAY,EACZ,MAAM,EACN,iBAAiB,GAKpB;IACG,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO;IACX,CAAC;IACD,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAChC,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAClC,OAAO;QACX,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,KAAK,GAAyC,IAAI,CAAC;QACvD,MAAM,MAAM,GAAG,GAAG,EAAE;YAChB,IAAI,OAAO,EAAE,CAAC;gBACV,OAAO;YACX,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACjB,YAAY,CAAC,KAAK,CAAC,CAAC;YACxB,CAAC;YACD,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5C,OAAO,EAAE,CAAC;QACd,CAAC,CAAC;QAEF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,EAAE,CAAC;YACT,OAAO;QACX,CAAC;QACD,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IACH,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC;AAED,KAAK,UAAU,YAAY,CAAU,EACjC,UAAU,EACV,YAAY,EACZ,SAAS,EACT,MAAM,EACN,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,GAAG,GACwB;IAC3B,MAAM,UAAU,GAAG,wBAAwB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,wBAAwB,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IAC1E,MAAM,gBAAgB,GAAG,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACvE,MAAM,uBAAuB,GAAG,oBAAoB,CAChD,iBAAiB,EACjB,mBAAmB,CACtB,CAAC;IACF,IAAI,OAAO,WAAW,KAAK,UAAU,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,cAAc,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,SAAS,GAAY,IAAI,CAAC;IAE9B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC5D,MAAM,aAAa,GAAG,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;QAC5D,MAAM,aAAa,GAAG,mBAAmB,CAAC,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1E,IAAI,CAAC;YACD,OAAO,MAAM,eAAe,CACxB,GAAG,EAAE,CACD,GAAG,CAAC;gBACA,OAAO;gBACP,MAAM,EAAE,aAAa,CAAC,MAAM;aAC/B,CAAC,EACN,aAAa,CAAC,MAAM,CACvB,CAAC;QACN,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,SAAS,GAAG,KAAK,CAAC;YAClB,oBAAoB,CAAC,MAAM,EAAE,uBAAuB,EAAE,KAAK,CAAC,CAAC;YAC7D,IAAI,OAAO,IAAI,UAAU,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC9C,MAAM,iBAAiB,CAAC;oBACpB,YAAY,EAAE,UAAU;oBACxB,MAAM;oBACN,iBAAiB,EAAE,uBAAuB;iBAC7C,CAAC,CAAC;gBACH,SAAS;YACb,CAAC;YACD,MAAM;QACV,CAAC;gBAAS,CAAC;YACP,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;YAC1B,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9B,CAAC;IACL,CAAC;IAED,MAAM,cAAc,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,OAAO,EACH,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,GACpB,CAAC"}

package/dist/cid-utils.d.ts

@@ -0,0 +1,3 @@
+/** Validate the kernel's CIDv1 / lowercase unpadded Base32 / SHA-256 format. */
+declare function assertCanonicalCid(value: unknown, label: string): string;
+export { assertCanonicalCid };

package/dist/cid-utils.js

@@ -0,0 +1,43 @@
+const BASE32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+/** Validate the kernel's CIDv1 / lowercase unpadded Base32 / SHA-256 format. */
+function assertCanonicalCid(value, label) {
+    const invalid = () => new TypeError(`${label} must be a canonical CIDv1 in lowercase unpadded Base32 with a 32-byte SHA-256 digest.`);
+    // One-byte version/hash/length, a 1–9-byte codec varint, and a 32-byte digest.
+    // Bound the input before decoding; no trimming, URLs, paths, or alternate bases.
+    if (typeof value !== 'string' || value.length < 59 || value.length > 72 || !/^b[a-z2-7]+$/.test(value)) {
+        throw invalid();
+    }
+    const bytes = [];
+    let accumulator = 0;
+    let bitCount = 0;
+    for (const character of value.slice(1)) {
+        accumulator = (accumulator << 5) | BASE32_ALPHABET.indexOf(character);
+        bitCount += 5;
+        if (bitCount >= 8) {
+            bitCount -= 8;
+            bytes.push(accumulator >> bitCount);
+            accumulator &= (1 << bitCount) - 1;
+        }
+    }
+    // Reject redundant symbols and nonzero unused bits, not just '=' padding.
+    if (bitCount >= 5 || accumulator !== 0 || bytes[0] !== 1) {
+        throw invalid();
+    }
+    // A codec is an unsigned, minimally encoded varint of at most 63 bits.
+    // Do not freeze the evolving codec registry into this format validator.
+    let offset = 1;
+    while (offset <= 9 && (bytes[offset] & 0x80) !== 0) {
+        offset += 1;
+    }
+    if (offset > 9 || (offset > 1 && bytes[offset] === 0)) {
+        throw invalid();
+    }
+    offset += 1;
+    // Requiring these exact bytes also rejects nonminimal hash/length varints.
+    if (bytes[offset] !== 0x12 || bytes[offset + 1] !== 0x20 || bytes.length !== offset + 2 + 32) {
+        throw invalid();
+    }
+    return value;
+}
+export { assertCanonicalCid };
+//# sourceMappingURL=cid-utils.js.map

package/dist/cid-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cid-utils.js","sourceRoot":"","sources":["../src/cid-utils.ts"],"names":[],"mappings":"AAAA,MAAM,eAAe,GAAG,kCAAkC,CAAC;AAE3D,gFAAgF;AAChF,SAAS,kBAAkB,CAAC,KAAc,EAAE,KAAa;IACrD,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,SAAS,CAC/B,GAAG,KAAK,wFAAwF,CACnG,CAAC;IACF,+EAA+E;IAC/E,iFAAiF;IACjF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrG,MAAM,OAAO,EAAE,CAAC;IACpB,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,WAAW,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtE,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YAChB,QAAQ,IAAI,CAAC,CAAC;YACd,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,QAAQ,CAAC,CAAC;YACpC,WAAW,IAAI,CAAC,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,CAAC;QACvC,CAAC;IACL,CAAC;IACD,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,CAAC,IAAI,WAAW,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,OAAO,EAAE,CAAC;IACpB,CAAC;IAED,uEAAuE;IACvE,wEAAwE;IACxE,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpD,MAAM,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,CAAC,CAAC;IACZ,2EAA2E;IAC3E,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC;QAC3F,MAAM,OAAO,EAAE,CAAC;IACpB,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/http-utils.d.ts

@@ -0,0 +1,47 @@
+interface CreateHttpConfigOptions {
+    url: string;
+    headers: Record<string, string>;
+    timeoutMs: number;
+    maxRetries: number;
+    retryDelayMs: number;
+}
+interface HttpConfig {
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryDelayMs: number;
+}
+interface HttpPostFetchOptions<TBody> {
+    method: 'POST';
+    headers: Readonly<Record<string, string>>;
+    body: TBody;
+    signal?: AbortSignal | undefined;
+}
+interface HttpTextResponse {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    text(): Promise<string>;
+}
+interface HttpStatusErrorOptions {
+    operation: string;
+    status: number;
+    statusText?: string;
+    responseText?: string;
+}
+type HttpFetchLike<TOptions, TResponse> = (url: string, options: TOptions) => Promise<TResponse>;
+type HttpPostFetchLike<TBody, TResponse = HttpTextResponse> = HttpFetchLike<HttpPostFetchOptions<TBody>, TResponse>;
+declare const RETRYABLE_HTTP_NETWORK_ERROR_CODES: ReadonlySet<string>;
+declare class HttpStatusError extends Error {
+    readonly operation: string;
+    readonly status: number;
+    readonly statusText: string;
+    readonly responseText: string | undefined;
+    constructor({ operation, status, statusText, responseText }: HttpStatusErrorOptions);
+}
+declare function createHttpConfig({ url, headers, timeoutMs, maxRetries, retryDelayMs }: CreateHttpConfigOptions, normalizeConfigUrl?: (url: string) => string): HttpConfig;
+declare function readErrorStringChain(error: unknown, key: string): string[];
+declare function hasRetryableNetworkErrorCode(error: unknown): boolean;
+export { HttpStatusError, RETRYABLE_HTTP_NETWORK_ERROR_CODES, createHttpConfig, hasRetryableNetworkErrorCode, readErrorStringChain, };
+export type { CreateHttpConfigOptions, HttpConfig, HttpFetchLike, HttpPostFetchLike, HttpPostFetchOptions, HttpStatusErrorOptions, HttpTextResponse, };

package/dist/http-utils.js

@@ -0,0 +1,119 @@
+import { assertHeadersObject, assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, } from './validation-utils.js';
+function createReadonlySet(values) {
+    const set = new Set(values);
+    const readonlySet = {
+        get size() {
+            return set.size;
+        },
+        has(value) {
+            return set.has(value);
+        },
+        entries() {
+            return set.entries();
+        },
+        keys() {
+            return set.keys();
+        },
+        values() {
+            return set.values();
+        },
+        union(other) {
+            return set.union(other);
+        },
+        intersection(other) {
+            return set.intersection(other);
+        },
+        difference(other) {
+            return set.difference(other);
+        },
+        symmetricDifference(other) {
+            return set.symmetricDifference(other);
+        },
+        isSubsetOf(other) {
+            return set.isSubsetOf(other);
+        },
+        isSupersetOf(other) {
+            return set.isSupersetOf(other);
+        },
+        isDisjointFrom(other) {
+            return set.isDisjointFrom(other);
+        },
+        forEach(callback, thisArg) {
+            for (const value of set) {
+                callback.call(thisArg, value, value, readonlySet);
+            }
+        },
+        [Symbol.iterator]() {
+            return set.values();
+        },
+    };
+    return Object.freeze(readonlySet);
+}
+const RETRYABLE_HTTP_NETWORK_ERROR_CODES = createReadonlySet([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EAI_AGAIN',
+    'ENOTFOUND',
+    'EPIPE',
+    'ETIMEDOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_SOCKET',
+]);
+class HttpStatusError extends Error {
+    operation;
+    status;
+    statusText;
+    responseText;
+    constructor({ operation, status, statusText, responseText }) {
+        const normalizedOperation = assertNonEmptyString(operation, 'operation');
+        const normalizedStatus = assertNonNegativeInteger(status, 'status');
+        const normalizedStatusText = typeof statusText === 'string' && statusText.trim()
+            ? statusText.trim()
+            : 'Unknown Status';
+        super(`${normalizedOperation} failed with ${normalizedStatus} ${normalizedStatusText}.`);
+        this.name = 'HttpStatusError';
+        this.operation = normalizedOperation;
+        this.status = normalizedStatus;
+        this.statusText = normalizedStatusText;
+        this.responseText = responseText;
+    }
+}
+function normalizeUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+function createHttpConfig({ url, headers, timeoutMs, maxRetries, retryDelayMs }, normalizeConfigUrl = normalizeUrl) {
+    const normalizedUrl = assertNonEmptyString(normalizeConfigUrl(assertNonEmptyString(url, 'config.url')), 'config.url');
+    return Object.freeze({
+        url: normalizedUrl,
+        headers: assertHeadersObject(headers, 'config.headers', {
+            disallowedNames: ['content-type'],
+        }),
+        timeoutMs: assertPositiveInteger(timeoutMs, 'config.timeoutMs'),
+        maxRetries: assertNonNegativeInteger(maxRetries, 'config.maxRetries'),
+        retryDelayMs: assertNonNegativeInteger(retryDelayMs, 'config.retryDelayMs'),
+    });
+}
+function readErrorStringChain(error, key) {
+    const values = [];
+    let current = error;
+    while (current && typeof current === 'object') {
+        const value = current[key];
+        if (typeof value === 'string' && value) {
+            values.push(value);
+        }
+        current = current.cause;
+    }
+    return values;
+}
+function hasRetryableNetworkErrorCode(error) {
+    for (const code of readErrorStringChain(error, 'code')) {
+        if (RETRYABLE_HTTP_NETWORK_ERROR_CODES.has(code.toUpperCase())) {
+            return true;
+        }
+    }
+    return false;
+}
+export { HttpStatusError, RETRYABLE_HTTP_NETWORK_ERROR_CODES, createHttpConfig, hasRetryableNetworkErrorCode, readErrorStringChain, };
+//# sourceMappingURL=http-utils.js.map

package/dist/http-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-utils.js","sourceRoot":"","sources":["../src/http-utils.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { assertCanonicalCid } from './cid-utils.js';
+export { assertTimerMs, combineAbortSignals, createTimeoutSignal, invokeWithAbort, runWithRetry, throwIfSignalAborted, waitForRetryDelay, } from './async-utils.js';
+export type { AbortSignalHandle, RunWithRetryAttemptContext, RunWithRetryOptions, } from './async-utils.js';
+export { HttpStatusError, RETRYABLE_HTTP_NETWORK_ERROR_CODES, createHttpConfig, hasRetryableNetworkErrorCode, readErrorStringChain, } from './http-utils.js';
+export type { CreateHttpConfigOptions, HttpConfig, HttpFetchLike, HttpPostFetchLike, HttpPostFetchOptions, HttpStatusErrorOptions, HttpTextResponse, } from './http-utils.js';
+export { assertAsciiBytes, assertBytes32HexString, assertHeadersObject, assertHexData, assertHexString, assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, assertUint256, isPlainObject, parseBytes, } from './validation-utils.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { assertCanonicalCid } from './cid-utils.js';
+export { assertTimerMs, combineAbortSignals, createTimeoutSignal, invokeWithAbort, runWithRetry, throwIfSignalAborted, waitForRetryDelay, } from './async-utils.js';
+export { HttpStatusError, RETRYABLE_HTTP_NETWORK_ERROR_CODES, createHttpConfig, hasRetryableNetworkErrorCode, readErrorStringChain, } from './http-utils.js';
+export { assertAsciiBytes, assertBytes32HexString, assertHeadersObject, assertHexData, assertHexString, assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, assertUint256, isPlainObject, parseBytes, } from './validation-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACH,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,GACpB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACH,eAAe,EACf,kCAAkC,EAClC,gBAAgB,EAChB,4BAA4B,EAC5B,oBAAoB,GACvB,MAAM,iBAAiB,CAAC;AAWzB,OAAO,EACH,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,aAAa,EACb,aAAa,EACb,UAAU,GACb,MAAM,uBAAuB,CAAC"}

package/dist/validation-utils.d.ts

@@ -0,0 +1,14 @@
+declare function assertNonEmptyString(value: unknown, label: string): string;
+declare function assertPositiveInteger(value: unknown, label: string): number;
+declare function assertNonNegativeInteger(value: unknown, label: string): number;
+declare function assertUint256(value: unknown, name: string): bigint;
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function assertHeadersObject(headers: unknown, label: string, options?: {
+    disallowedNames?: string[];
+}): Readonly<Record<string, string>>;
+declare function assertAsciiBytes(bytes: Uint8Array, message: string): void;
+declare function assertHexString(value: unknown, label: string): string;
+declare function assertHexData(value: unknown, label: string): string;
+declare function assertBytes32HexString(value: unknown, label: string): string;
+declare function parseBytes(value: unknown, name: string, size?: number): string;
+export { assertAsciiBytes, assertBytes32HexString, assertHeadersObject, assertHexData, assertHexString, assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, assertUint256, isPlainObject, parseBytes, };

package/dist/validation-utils.js

@@ -0,0 +1,87 @@
+const UINT256_MAX = (1n << 256n) - 1n;
+function assertNonEmptyString(value, label) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function assertPositiveInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        throw new Error(`${label} must be a positive integer.`);
+    }
+    return value;
+}
+function assertNonNegativeInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`${label} must be a non-negative integer.`);
+    }
+    return value;
+}
+function assertUint256(value, name) {
+    if (typeof value !== 'bigint' || value < 0n || value > UINT256_MAX) {
+        throw new Error(`${name} must be a non-negative bigint fitting in 256 bits.`);
+    }
+    return value;
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function assertHeadersObject(headers, label, options = {}) {
+    if (!isPlainObject(headers)) {
+        throw new Error(`${label} must be a plain object.`);
+    }
+    const disallowedNames = new Set((options.disallowedNames ?? []).map((name) => name.toLowerCase()));
+    const validated = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (disallowedNames.has(key.toLowerCase())) {
+            throw new Error(`${label} must not include ${key.toLowerCase()}.`);
+        }
+        if (typeof value !== 'string') {
+            throw new Error(`${label}.${key} must be a string.`);
+        }
+        validated[key] = value;
+    }
+    return Object.freeze(validated);
+}
+function assertAsciiBytes(bytes, message) {
+    for (const byte of bytes) {
+        if (byte > 0x7f) {
+            throw new Error(message);
+        }
+    }
+}
+function assertHexString(value, label) {
+    const validated = assertNonEmptyString(value, label);
+    if (!/^0x[0-9a-fA-F]*$/.test(validated)) {
+        throw new Error(`${label} must be a 0x-prefixed hex string.`);
+    }
+    return validated;
+}
+function assertHexData(value, label) {
+    const validated = assertHexString(value, label);
+    if (validated.length === 2 || validated.length % 2 !== 0) {
+        throw new Error(`${label} must be non-empty byte-aligned hex data.`);
+    }
+    return validated;
+}
+function assertBytes32HexString(value, label) {
+    const validated = assertHexString(value, label);
+    if (validated.length !== 66) {
+        throw new Error(`${label} must be a 32-byte hex string.`);
+    }
+    return validated;
+}
+function parseBytes(value, name, size) {
+    if (typeof value !== 'string' ||
+        !/^0x(?:[0-9a-fA-F]{2})*$/.test(value) ||
+        (size !== undefined && value.length !== 2 + size * 2)) {
+        throw new Error(`${name} must be ${size === undefined ? 'byte-aligned' : `${size}-byte`} hex data.`);
+    }
+    return value;
+}
+export { assertAsciiBytes, assertBytes32HexString, assertHeadersObject, assertHexData, assertHexString, assertNonEmptyString, assertNonNegativeInteger, assertPositiveInteger, assertUint256, isPlainObject, parseBytes, };
+//# sourceMappingURL=validation-utils.js.map

package/dist/validation-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-utils.js","sourceRoot":"","sources":["../src/validation-utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oyaprotocol/utils",
+  "version": "0.1.0",
+  "description": "Oya utilities package.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oyaprotocol/oya-commitments.git",
+    "directory": "packages/utils"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.js.map",
+    "README.md",
+    "LICENSE"
+  ]
+}