@pinet/transport-core 0.2.2 → 0.2.6

package/README.md

@@ -8,6 +8,11 @@ Tiny transport-neutral contracts package for the `extensions` repo.
 - canonical `OutboundMessage` contract
 - normalized outbound `content` shape for transport-aware rendering with plain-text fallback
 - canonical `MessageAdapter` transport interface
+- shared zero-dependency async primitives via the `@pinet/transport-core/async`
+  subpath: `sleep` (abortable delay), `withTimeout`, `computeBackoffDelay`
+  (capped + jittered exponential backoff), and `AbortError`/`TimeoutError`
+  helpers. Retry _drivers_ stay bespoke at call sites; this module only owns
+  the primitives they compose.
 
 ## What stays out of scope
 

package/dist/async.d.ts

@@ -0,0 +1,44 @@
+/** Create an Error whose name is "AbortError", matching DOM abort semantics. */
+export declare function createAbortError(message?: string): Error;
+/** True when the value is an Error whose name is "AbortError". */
+export declare function isAbortError<T>(error: T): boolean;
+export interface SleepOptions {
+    /** Optional signal that aborts the sleep early; the promise rejects with an AbortError. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve after `ms` milliseconds. When `options.signal` is provided and
+ * aborts first, the timer is cleared and the promise rejects with an
+ * AbortError (also when the signal is already aborted on entry).
+ */
+export declare function sleep(ms: number, options?: SleepOptions): Promise<void>;
+/** Create an Error whose name is "TimeoutError". */
+export declare function createTimeoutError(timeoutMs: number, label?: string): Error;
+/** True when the value is an Error whose name is "TimeoutError". */
+export declare function isTimeoutError<T>(error: T): boolean;
+/**
+ * Reject with a TimeoutError when the promise does not settle within
+ * `timeoutMs`. The guard timer is unref'd so it never keeps the process
+ * alive. Non-Error rejections from the wrapped promise are normalized to
+ * Error instances.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label?: string): Promise<T>;
+export interface BackoffOptions {
+    /** Delay for attempt 0, before capping and jitter. */
+    initialMs: number;
+    /** Upper bound applied before jitter. */
+    maxMs: number;
+    /** Exponential growth factor per attempt. Default 2. */
+    factor?: number;
+    /** Jitter as a ratio of the capped delay (±ratio). Default 0.25; 0 disables jitter. */
+    jitterRatio?: number;
+    /** Random sample in [0, 1). Injectable for deterministic tests; defaults to Math.random(). */
+    random?: number;
+}
+/**
+ * Compute a capped, jittered exponential-backoff delay for a retry attempt.
+ * Attempt numbers below zero are treated as zero. With the defaults the
+ * result is `min(initialMs * 2^attempt, maxMs)` scaled by a random factor
+ * in [0.75, 1.25), rounded to the nearest millisecond.
+ */
+export declare function computeBackoffDelay(attempt: number, options: BackoffOptions): number;

package/dist/async.js

@@ -0,0 +1,89 @@
+// Shared async primitives for pi transports and bridges.
+//
+// These are the zero-dependency building blocks that were previously
+// hand-rolled per package (abortable delays, promise timeouts, jittered
+// exponential backoff). Retry *drivers* stay bespoke at call sites — this
+// module only owns the primitives they compose.
+/** Create an Error whose name is "AbortError", matching DOM abort semantics. */
+export function createAbortError(message = "Operation aborted") {
+    const error = new Error(message);
+    error.name = "AbortError";
+    return error;
+}
+/** True when the value is an Error whose name is "AbortError". */
+export function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+/**
+ * Resolve after `ms` milliseconds. When `options.signal` is provided and
+ * aborts first, the timer is cleared and the promise rejects with an
+ * AbortError (also when the signal is already aborted on entry).
+ */
+export function sleep(ms, options = {}) {
+    const { signal } = options;
+    if (!signal) {
+        return new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        });
+    }
+    if (signal.aborted) {
+        return Promise.reject(createAbortError());
+    }
+    const abortSignal = signal;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            abortSignal.removeEventListener("abort", onAbort);
+            reject(createAbortError());
+        }
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Create an Error whose name is "TimeoutError". */
+export function createTimeoutError(timeoutMs, label) {
+    const error = new Error(label ? `${label} timed out after ${timeoutMs}ms` : `Timed out after ${timeoutMs}ms`);
+    error.name = "TimeoutError";
+    return error;
+}
+/** True when the value is an Error whose name is "TimeoutError". */
+export function isTimeoutError(error) {
+    return error instanceof Error && error.name === "TimeoutError";
+}
+/**
+ * Reject with a TimeoutError when the promise does not settle within
+ * `timeoutMs`. The guard timer is unref'd so it never keeps the process
+ * alive. Non-Error rejections from the wrapped promise are normalized to
+ * Error instances.
+ */
+export function withTimeout(promise, timeoutMs, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(createTimeoutError(timeoutMs, label)), timeoutMs);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/**
+ * Compute a capped, jittered exponential-backoff delay for a retry attempt.
+ * Attempt numbers below zero are treated as zero. With the defaults the
+ * result is `min(initialMs * 2^attempt, maxMs)` scaled by a random factor
+ * in [0.75, 1.25), rounded to the nearest millisecond.
+ */
+export function computeBackoffDelay(attempt, options) {
+    const factor = options.factor ?? 2;
+    const jitterRatio = options.jitterRatio ?? 0.25;
+    const random = options.random ?? Math.random();
+    const base = options.initialMs * Math.pow(factor, Math.max(0, attempt));
+    const capped = Math.min(base, options.maxMs);
+    const jittered = capped * (1 - jitterRatio + random * 2 * jitterRatio);
+    return Math.round(jittered);
+}

package/dist/index.d.ts

@@ -1,4 +1,9 @@
 export type RuntimeScopeSource = "explicit" | "compatibility";
+export type TransportJsonValue = unknown;
+export type TransportJsonObject = Record<string, TransportJsonValue>;
+export type TransportRichBlock = TransportJsonObject;
+export type AdapterCapabilityParams = TransportJsonObject;
+export type AdapterCapabilityPayload = TransportJsonObject;
 export declare const DEFAULT_COMPATIBILITY_SCOPE_KEY = "default";
 export interface WorkspaceInstallScopeCarrier {
     provider: string;
@@ -43,7 +48,7 @@ export interface InboundMessage {
     text: string;
     timestamp: string;
     isChannelMention?: boolean;
-    metadata?: Record<string, unknown>;
+    metadata?: TransportJsonObject;
     scope?: RuntimeScopeCarrier;
 }
 export interface NormalizedMessageContent {
@@ -54,7 +59,7 @@ export interface NormalizedMessageContent {
      * This remains intentionally Slack-shaped for the current publish-readiness
      * track while a future transport-neutral rich-content model is considered.
      */
-    slackBlocks?: ReadonlyArray<Record<string, unknown>>;
+    slackBlocks?: ReadonlyArray<TransportRichBlock>;
 }
 export interface OutboundAttachmentFile {
     path: string;
@@ -67,12 +72,12 @@ export interface OutboundMessage {
     channel: string;
     text: string;
     content?: NormalizedMessageContent;
-    blocks?: ReadonlyArray<Record<string, unknown>>;
+    blocks?: ReadonlyArray<TransportRichBlock>;
     files?: ReadonlyArray<OutboundAttachmentFile>;
     agentName?: string;
     agentEmoji?: string;
     agentOwnerToken?: string;
-    metadata?: Record<string, unknown>;
+    metadata?: TransportJsonObject;
     scope?: RuntimeScopeCarrier;
 }
 export interface AdapterThreadClaimEffect {
@@ -84,10 +89,10 @@ export interface AdapterCapabilityEffects {
 }
 export interface AdapterCapabilityRequest {
     capability: string;
-    params: Record<string, unknown>;
+    params: AdapterCapabilityParams;
 }
 export interface AdapterCapabilityResult {
-    result: Record<string, unknown>;
+    result: AdapterCapabilityPayload;
     effects?: AdapterCapabilityEffects;
 }
 export interface MessageAdapter {

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@pinet/transport-core",
-  "version": "0.2.2",
+  "version": "0.2.6",
   "type": "module",
   "description": "Transport-neutral message contracts for pi transports",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/gugu91/extensions.git",
+    "url": "git+https://github.com/gugu91/pinet.git",
     "directory": "transport-core"
   },
   "publishConfig": {
@@ -16,6 +16,7 @@
   "main": "./dist/index.js",
   "exports": {
     ".": "./dist/index.js",
+    "./async": "./dist/async.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -27,7 +28,7 @@
   "scripts": {
     "build": "node ../scripts/build-package.mjs",
     "prepack": "pnpm run build",
-    "lint": "eslint . --ext .ts",
+    "lint": "oxlint .",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test *.test.ts"
   },