lifecycleion 0.0.19 → 0.0.21

package/dist/{types-Mso0dYOS.d.ts → types-BONtIhQ5.d.ts}

@@ -246,12 +246,30 @@ interface AdapterResponse {
      */
     isTransportError?: boolean;
     /**
-     * Set to `false` when the adapter knows the request/response progressed far
-     * enough that replay is unsafe, even if `status` would normally be retried
-     * by the client (for example a mid-upload socket write failure after some
-     * bytes may already have left the process).
+     * Set to `false` when no attempt can succeed, whatever the method — a rejected
+     * TLS certificate, say. Honoured for every method, and it overrides
+     * `retryNonIdempotentMethods`.
+     *
+     * Do **not** set it for a failure that merely might have been delivered, such
+     * as one that struck mid-upload: that vetoes retries for methods where replay
+     * is safe by definition. Report
+     * {@link AdapterResponse.wasDefinitelyNotSent} instead, or report nothing.
+     *
+     * Only `false` carries meaning. `true` is a hint, and never authorizes
+     * replaying a non-idempotent request.
      */
     isRetryable?: boolean;
+    /**
+     * Set to `true` only when the adapter can prove no request bytes reached the
+     * server — a refused connection, a name that did not resolve. Absence means
+     * "not known", never "known to be safe".
+     *
+     * Deliberately separate from {@link AdapterResponse.isRetryable}, which is a
+     * hint that says nothing about delivery. The client uses this to decide whether
+     * a `POST` or `PATCH` may be retried after a transport failure, and ignores it
+     * when a real response came back.
+     */
+    wasDefinitelyNotSent?: boolean;
     /**
      * Final request headers actually used by the adapter after adapter-local
      * mutations (for example multipart Content-Type/Content-Length added by the
@@ -276,12 +294,19 @@ interface AdapterResponse {
      */
     isStreamed?: boolean;
     /**
-     * Set by NodeAdapter when response-body delivery fails after headers arrive
-     * (for example buffered-download truncation, writable errors, or upstream
-     * response-stream errors). The client treats this as a terminal stream
-     * failure: isStreamError: true. The real HTTP status is preserved (not
-     * zeroed) so observers can tell the server responded but body delivery still
-     * failed locally/in-flight.
+     * Set when response-body delivery fails after headers arrive — buffered
+     * download truncation, writable errors, upstream response-stream errors.
+     * NodeAdapter, FetchAdapter and MockAdapter all report it, and the client
+     * synthesizes it for a per-attempt timeout that strikes mid-body. XHRAdapter
+     * cannot: `XMLHttpRequest` zeroes the status on error.
+     *
+     * The client treats this as a terminal stream failure. The real HTTP status is
+     * preserved (not zeroed) so observers can tell the server responded but body
+     * delivery still failed.
+     *
+     * For replay decisions this groups with a real response, **not** with a
+     * transport failure: headers arrived, so the server processed the request and
+     * may have committed it, the same thing a 500 tells you.
      */
     isStreamError?: boolean;
     /**
@@ -395,6 +420,23 @@ interface AttemptEndEvent {
     attemptNumber: number;
     isRetry: boolean;
     willRetry: boolean;
+    /**
+     * Why no retry happened, when a retry was genuinely available to suppress — a
+     * policy is configured, it has attempts left, and the status alone would have
+     * allowed one. Absent otherwise, since nothing was suppressed.
+     *
+     * - `adapter_veto` — the adapter reported `isRetryable: false`. Not produced by
+     *   a real transport, which pairs that flag with the non-retryable `495`;
+     *   reachable from `MockAdapter` and custom adapters.
+     * - `stream_error` — the body failed after headers arrived, so the server
+     *   received the request and the outcome is unknown.
+     * - `non_idempotent_method` — a `POST` or `PATCH` with no proof the request
+     *   went undelivered. Set `retryNonIdempotentMethods` to allow it.
+     *
+     * Exists so a suppressed retry is self-explaining: `willRetry: false` alone is
+     * indistinguishable from a policy declining.
+     */
+    retrySuppressedReason?: 'adapter_veto' | 'stream_error' | 'non_idempotent_method';
     /** Present only when a retry has been scheduled after this attempt. */
     nextRetryDelayMS?: number;
     /** Epoch ms for the scheduled retry, when a retry has been scheduled. */
@@ -423,6 +465,20 @@ interface HTTPClientConfig {
     timeout?: number;
     cookieJar?: CookieJar | null;
     retryPolicy?: RetryPolicyOptions;
+    /**
+     * Whether a retry policy may replay `POST` and `PATCH`, the methods RFC 9110
+     * does not define as idempotent. Defaults to `false`.
+     *
+     * When `false`, such a request is never retried after a real HTTP response —
+     * a 500 still means the handler ran and may have committed — and after a
+     * transport failure only when the adapter reports
+     * {@link AdapterResponse.wasDefinitelyNotSent}. A bare transport failure is not
+     * enough, and neither is `isRetryable: true`.
+     *
+     * Set to `true` when writes are guarded by an idempotency key or are naturally
+     * safe to repeat. Idempotent methods are unaffected either way.
+     */
+    retryNonIdempotentMethods?: boolean;
     includeRequestID?: boolean;
     includeAttemptHeader?: boolean;
     userAgent?: string;
@@ -448,6 +504,11 @@ interface HTTPRequestOptions {
     timeout?: number;
     signal?: AbortSignal;
     retryPolicy?: RetryPolicyOptions | null;
+    /**
+     * Per-request override for {@link HTTPClientConfig.retryNonIdempotentMethods}.
+     * Falls back to the client config when omitted.
+     */
+    retryNonIdempotentMethods?: boolean;
     label?: string;
     onUploadProgress?: (event: HTTPProgressEvent) => void;
     onDownloadProgress?: (event: HTTPProgressEvent) => void;
@@ -865,4 +926,4 @@ type ResponseObserver = (response: HTTPResponse, request: AttemptRequest, phase:
 type ErrorObserver = (error: HTTPClientError, request: AttemptRequest, phase: ErrorObserverPhase) => void | Promise<void>;
 type RequestState = 'pending' | 'sending' | 'waiting_for_retry' | 'completed' | 'cancelled' | 'failed';
 
-export { type AdapterType as A, type InterceptorPhaseName as B, type ContentType as C, type QueryValue as D, type ErrorObserver as E, type RedirectHopInfo as F, type RequestInterceptorContext as G, type HTTPAdapter as H, type InterceptedRequest as I, type RequestPhase as J, type RequestPhaseName as K, type ResponseObserverPhase as L, type ResponseObserverPhaseName as M, type StreamResponseCancel as N, type StreamResponseContext as O, type StreamResponseInfo as P, type QueryObject as Q, type RequestState as R, type StreamResponseFactory as S, type WritableLike as W, type AdapterRequest as a, type AdapterResponse as b, type HTTPMethod as c, type HTTPRequestOptions as d, type HTTPResponse as e, type HTTPClientError as f, type HTTPProgressEvent as g, type AttemptStartEvent as h, type AttemptEndEvent as i, type HTTPClientConfig as j, type RequestInterceptor as k, type RequestInterceptorFilter as l, type ResponseObserver as m, type ResponseObserverFilter as n, type ErrorObserverFilter as o, type SubClientConfig as p, type AttemptRequest as q, type Cookie as r, type CookieInput as s, CookieJar as t, type CookieJarJSON as u, type ErrorCode as v, type ErrorObserverPhase as w, type ErrorObserverPhaseName as x, type InterceptorCancel as y, type InterceptorPhase as z };
+export { type AdapterType as A, type ErrorObserverPhase as B, type ContentType as C, type ErrorObserverPhaseName as D, type ErrorObserver as E, type InterceptorCancel as F, type InterceptorPhase as G, type HTTPAdapter as H, type InterceptedRequest as I, type InterceptorPhaseName as J, type QueryValue as K, type RedirectHopInfo as L, type RequestInterceptorContext as M, type RequestPhase as N, type RequestPhaseName as O, type ResponseObserverPhase as P, type QueryObject as Q, type RequestState as R, type StreamResponseCancel as S, type ResponseObserverPhaseName as T, type WritableLike as W, type AdapterRequest as a, type AdapterResponse as b, type AdapterProgressEvent as c, type HTTPMethod as d, type StreamResponseContext as e, type StreamResponseFactory as f, type StreamResponseInfo as g, type HTTPRequestOptions as h, type HTTPResponse as i, type HTTPClientError as j, type HTTPProgressEvent as k, type AttemptStartEvent as l, type AttemptEndEvent as m, type HTTPClientConfig as n, type RequestInterceptor as o, type RequestInterceptorFilter as p, type ResponseObserver as q, type ResponseObserverFilter as r, type ErrorObserverFilter as s, type SubClientConfig as t, type AttemptRequest as u, type Cookie as v, type CookieInput as w, CookieJar as x, type CookieJarJSON as y, type ErrorCode as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lifecycleion",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "type": "module",
   "description": "A collection of foundational TypeScript utilities for managing application lifecycle, logging, retries, events, and common programming patterns",
   "exports": {
@@ -54,6 +54,11 @@
       "import": "./dist/lib/error-to-string.js",
       "require": "./dist/lib/error-to-string.cjs"
     },
+    "./global-event-target": {
+      "types": "./dist/lib/global-event-target.d.ts",
+      "import": "./dist/lib/global-event-target.js",
+      "require": "./dist/lib/global-event-target.cjs"
+    },
     "./event-emitter": {
       "types": "./dist/lib/event-emitter.d.ts",
       "import": "./dist/lib/event-emitter.js",
@@ -185,6 +190,15 @@
       "require": "./dist/lib/http-client-mock/index.cjs"
     }
   },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/lib/safe-handle-callback.js",
+    "./dist/lib/safe-handle-callback.cjs",
+    "./dist/lib/logger/index.js",
+    "./dist/lib/logger/index.cjs"
+  ],
   "files": [
     "dist"
   ],
@@ -226,21 +240,26 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/keverw/lifecycleion"
+    "url": "git+https://github.com/keverw/lifecycleion.git"
+  },
+  "homepage": "https://github.com/keverw/lifecycleion#readme",
+  "bugs": {
+    "url": "https://github.com/keverw/lifecycleion/issues"
   },
   "overrides": {
-    "brace-expansion": "5.0.8",
-    "esbuild": "0.28.1"
+    "brace-expansion": "5.0.9",
+    "esbuild": "0.28.1",
+    "js-yaml": "4.3.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
-    "@playwright/test": "^1.62.0",
-    "@types/bun": "^1.3.14",
+    "@playwright/test": "^1.62.1",
+    "@types/bun": "1.3.14",
     "@types/node": "^24.13.3",
     "@types/qs": "^6.15.1",
     "@types/tr46": "^5.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.65.0",
-    "@typescript-eslint/parser": "^8.65.0",
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
     "eslint": "^9.39.5",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-check-file": "^3.3.2",
@@ -253,19 +272,19 @@
     "prettier": "^3.9.6",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.65.0"
+    "typescript-eslint": "^8.67.0"
   },
   "dependencies": {
     "bson-objectid": "^2.0.4",
     "chalk": "^5.6.2",
     "datamask": "^1.0.0",
     "date-fns": "^4.4.0",
-    "find-my-way": "^9.7.0",
+    "find-my-way": "^9.8.0",
     "qs": "^6.15.3",
     "string-width": "^8.2.2",
-    "tldts": "^7.4.9",
+    "tldts": "^7.4.10",
     "tr46": "^6.0.0",
     "ulid": "^3.0.2",
-    "uuid": "^14.0.1"
+    "uuid": "^14.0.2"
   }
 }