@gwash3189/doover 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gwash3189
+
+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

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @gwash3189/doover
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A fluent, zero-dependency TypeScript retry library with configurable backoff strategies and lifecycle event hooks.
+
+## Installation
+
+```bash
+npm install @gwash3189/doover
+```
+
+## Usage
+
+```ts
+import Retry from '@gwash3189/doover'
+
+const retryable = Retry
+  .exponential
+  .attempts(3)
+  .work(async () => {
+    // ... perform work that might throw
+  })
+  .on('retry', (err) => {
+    // Returning true (or void) will cause a retry
+    // Returning false will cause the error to bubble immediately
+    return true
+  })
+  .on('exhausted', (err) => {
+    // Called when all retries are out before the error bubbles
+  })
+
+const result = await retryable
+```
+
+## API
+
+### Backoff Strategies
+
+- `Retry.exponential`: Exponential backoff (`delay * 2^(attempt - 1)`).
+- `Retry.linear`: Linear backoff (`delay * attempt`).
+- `Retry.constant`: Constant delay between attempts (`delay`).
+- `Retry.immediate`: Retries immediately with `0ms` delay.
+
+### Builder Methods
+
+- `.attempts(count: number)`: Maximum number of attempts (default: `3`).
+- `.delay(ms: number)`: Base delay in milliseconds between retries (default: `100`).
+- `.jitter(enabled?: boolean)`: Applies random jitter to the computed backoff delay.
+- `.work(fn: (attempt: number) => Promise<T> | T)`: The function to execute and retry if it throws.
+- `.on('retry', (err, attempt) => boolean | void | Promise<boolean | void>)`: Invoked when an attempt fails and retries remain. Returning `false` stops retrying and lets the error bubble immediately.
+- `.on('exhausted', (err, attempts) => void | Promise<void>)`: Invoked when all configured attempts have failed.
+
+## Development
+
+```bash
+npm test           # Run tests with Vitest
+npm run lint       # Run linter with Oxlint
+npm run type-check # Run TypeScript type checker
+npm run build      # Build ESM + CJS bundles with tsdown
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,147 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+// src/retry.ts
+function waitDelay(ms) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeDelay(strategy, baseDelayMs, attemptNumber, useJitter) {
+	if (baseDelayMs <= 0 || strategy === "none") return 0;
+	let delayMs;
+	switch (strategy) {
+		case "exponential":
+			delayMs = baseDelayMs * 2 ** (attemptNumber - 1);
+			break;
+		case "linear":
+			delayMs = baseDelayMs * attemptNumber;
+			break;
+		case "constant": delayMs = baseDelayMs;
+	}
+	if (useJitter) return Math.random() * delayMs;
+	return delayMs;
+}
+var RetryBuilder = class RetryBuilder {
+	config;
+	executionPromise;
+	constructor(config) {
+		this.config = {
+			strategy: config?.strategy ?? "exponential",
+			maxAttempts: config?.maxAttempts ?? 3,
+			baseDelayMs: config?.baseDelayMs ?? 100,
+			useJitter: config?.useJitter ?? false,
+			workFn: config?.workFn,
+			retryHandlers: [...config?.retryHandlers ?? []],
+			exhaustedHandlers: [...config?.exhaustedHandlers ?? []]
+		};
+	}
+	get exponential() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "exponential"
+		});
+	}
+	get linear() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "linear"
+		});
+	}
+	get constant() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "constant"
+		});
+	}
+	get immediate() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "none",
+			baseDelayMs: 0
+		});
+	}
+	attempts(count) {
+		if (!Number.isInteger(count) || count < 1) throw new RangeError("attempts must be an integer of at least 1");
+		return new RetryBuilder({
+			...this.config,
+			maxAttempts: count
+		});
+	}
+	delay(ms) {
+		if (ms < 0) throw new RangeError("delay must be a non-negative number");
+		return new RetryBuilder({
+			...this.config,
+			baseDelayMs: ms
+		});
+	}
+	jitter(enabled = true) {
+		return new RetryBuilder({
+			...this.config,
+			useJitter: enabled
+		});
+	}
+	work(fn) {
+		return new RetryBuilder({
+			...this.config,
+			workFn: fn
+		});
+	}
+	on(event, handler) {
+		if (event === "retry") return new RetryBuilder({
+			...this.config,
+			retryHandlers: [...this.config.retryHandlers, handler]
+		});
+		if (event === "exhausted") return new RetryBuilder({
+			...this.config,
+			exhaustedHandlers: [...this.config.exhaustedHandlers, handler]
+		});
+		throw new TypeError(`Unsupported event type: ${String(event)}`);
+	}
+	async run() {
+		return this.execute();
+	}
+	then(onfulfilled, onrejected) {
+		if (!this.executionPromise) this.executionPromise = this.execute();
+		return this.executionPromise.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	finally(onfinally) {
+		return this.then((value) => {
+			onfinally?.();
+			return value;
+		}, (reason) => {
+			onfinally?.();
+			throw reason;
+		});
+	}
+	async execute() {
+		const { workFn, maxAttempts, strategy, baseDelayMs, useJitter, retryHandlers, exhaustedHandlers } = this.config;
+		if (!workFn) throw new Error("No work function provided. Call .work(fn) before awaiting or running.");
+		let attempt = 0;
+		while (attempt < maxAttempts) {
+			attempt++;
+			try {
+				return await workFn(attempt);
+			} catch (error) {
+				if (attempt >= maxAttempts) {
+					for (const handler of exhaustedHandlers) await handler(error, attempt);
+					throw error;
+				}
+				let shouldContinue = true;
+				for (const handler of retryHandlers) if (await handler(error, attempt) === false) {
+					shouldContinue = false;
+					break;
+				}
+				if (!shouldContinue) throw error;
+				await waitDelay(computeDelay(strategy, baseDelayMs, attempt, useJitter));
+			}
+		}
+		throw new Error("Unreachable retry state");
+	}
+};
+const Retry = new RetryBuilder();
+
+exports.Retry = Retry;
+exports.RetryBuilder = RetryBuilder;
+exports.default = Retry;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/retry.ts"],"sourcesContent":["export type BackoffStrategy = 'exponential' | 'linear' | 'constant' | 'none'\n\nexport type RetryHandler = (\n  error: unknown,\n  attempt: number\n) => boolean | void | Promise<boolean | void>\n\nexport type ExhaustedHandler = (error: unknown, attempts: number) => void | Promise<void>\n\nexport type WorkFn<T = unknown> = (attempt: number) => Promise<T> | T\n\ninterface RetryConfig<T = unknown> {\n  strategy: BackoffStrategy\n  maxAttempts: number\n  baseDelayMs: number\n  useJitter: boolean\n  workFn?: WorkFn<T>\n  retryHandlers: RetryHandler[]\n  exhaustedHandlers: ExhaustedHandler[]\n}\n\nfunction waitDelay(ms: number): Promise<void> {\n  if (ms <= 0) {\n    return Promise.resolve()\n  }\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\nfunction computeDelay(\n  strategy: BackoffStrategy,\n  baseDelayMs: number,\n  attemptNumber: number,\n  useJitter: boolean\n): number {\n  if (baseDelayMs <= 0 || strategy === 'none') {\n    return 0\n  }\n\n  let delayMs: number\n  switch (strategy) {\n    case 'exponential':\n      delayMs = baseDelayMs * 2 ** (attemptNumber - 1)\n      break\n    case 'linear':\n      delayMs = baseDelayMs * attemptNumber\n      break\n    case 'constant':\n      delayMs = baseDelayMs\n      break\n  }\n\n  if (useJitter) {\n    return Math.random() * delayMs\n  }\n\n  return delayMs\n}\n\nexport class RetryBuilder<T = unknown> implements PromiseLike<T> {\n  private readonly config: RetryConfig<T>\n  private executionPromise?: Promise<T>\n\n  constructor(config?: Partial<RetryConfig<T>>) {\n    this.config = {\n      strategy: config?.strategy ?? 'exponential',\n      maxAttempts: config?.maxAttempts ?? 3,\n      baseDelayMs: config?.baseDelayMs ?? 100,\n      useJitter: config?.useJitter ?? false,\n      workFn: config?.workFn,\n      retryHandlers: [...(config?.retryHandlers ?? [])],\n      exhaustedHandlers: [...(config?.exhaustedHandlers ?? [])],\n    }\n  }\n\n  get exponential(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'exponential' })\n  }\n\n  get linear(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'linear' })\n  }\n\n  get constant(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'constant' })\n  }\n\n  get immediate(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'none', baseDelayMs: 0 })\n  }\n\n  attempts(count: number): RetryBuilder<T> {\n    if (!Number.isInteger(count) || count < 1) {\n      throw new RangeError('attempts must be an integer of at least 1')\n    }\n    return new RetryBuilder<T>({ ...this.config, maxAttempts: count })\n  }\n\n  delay(ms: number): RetryBuilder<T> {\n    if (ms < 0) {\n      throw new RangeError('delay must be a non-negative number')\n    }\n    return new RetryBuilder<T>({ ...this.config, baseDelayMs: ms })\n  }\n\n  jitter(enabled = true): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, useJitter: enabled })\n  }\n\n  work<R>(fn: WorkFn<R>): RetryBuilder<R> {\n    return new RetryBuilder<R>({\n      ...this.config,\n      workFn: fn,\n    })\n  }\n\n  on(event: 'retry', handler: RetryHandler): RetryBuilder<T>\n  on(event: 'exhausted', handler: ExhaustedHandler): RetryBuilder<T>\n  on(event: 'retry' | 'exhausted', handler: RetryHandler | ExhaustedHandler): RetryBuilder<T> {\n    if (event === 'retry') {\n      return new RetryBuilder<T>({\n        ...this.config,\n        retryHandlers: [...this.config.retryHandlers, handler as RetryHandler],\n      })\n    }\n\n    if (event === 'exhausted') {\n      return new RetryBuilder<T>({\n        ...this.config,\n        exhaustedHandlers: [...this.config.exhaustedHandlers, handler as ExhaustedHandler],\n      })\n    }\n\n    throw new TypeError(`Unsupported event type: ${String(event)}`)\n  }\n\n  async run(): Promise<T> {\n    return this.execute()\n  }\n\n  then<TResult1 = T, TResult2 = never>(\n    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined\n  ): Promise<TResult1 | TResult2> {\n    if (!this.executionPromise) {\n      this.executionPromise = this.execute()\n    }\n    return this.executionPromise.then(onfulfilled, onrejected)\n  }\n\n  catch<TResult = never>(\n    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null | undefined\n  ): Promise<T | TResult> {\n    return this.then(undefined, onrejected)\n  }\n\n  finally(onfinally?: (() => void) | null | undefined): Promise<T> {\n    return this.then(\n      (value) => {\n        onfinally?.()\n        return value\n      },\n      (reason) => {\n        onfinally?.()\n        throw reason\n      }\n    )\n  }\n\n  private async execute(): Promise<T> {\n    const {\n      workFn,\n      maxAttempts,\n      strategy,\n      baseDelayMs,\n      useJitter,\n      retryHandlers,\n      exhaustedHandlers,\n    } = this.config\n\n    if (!workFn) {\n      throw new Error('No work function provided. Call .work(fn) before awaiting or running.')\n    }\n\n    let attempt = 0\n\n    while (attempt < maxAttempts) {\n      attempt++\n\n      try {\n        return await workFn(attempt)\n      } catch (error) {\n        if (attempt >= maxAttempts) {\n          for (const handler of exhaustedHandlers) {\n            await handler(error, attempt)\n          }\n          throw error\n        }\n\n        let shouldContinue = true\n        for (const handler of retryHandlers) {\n          const decision = await handler(error, attempt)\n          if (decision === false) {\n            shouldContinue = false\n            break\n          }\n        }\n\n        if (!shouldContinue) {\n          throw error\n        }\n\n        const waitMs = computeDelay(strategy, baseDelayMs, attempt, useJitter)\n        await waitDelay(waitMs)\n      }\n    }\n\n    throw new Error('Unreachable retry state')\n  }\n}\n\nexport const Retry: RetryBuilder = new RetryBuilder()\n\nexport default Retry\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,36 @@
+type BackoffStrategy = 'exponential' | 'linear' | 'constant' | 'none';
+type RetryHandler = (error: unknown, attempt: number) => boolean | void | Promise<boolean | void>;
+type ExhaustedHandler = (error: unknown, attempts: number) => void | Promise<void>;
+type WorkFn<T = unknown> = (attempt: number) => Promise<T> | T;
+interface RetryConfig<T = unknown> {
+  strategy: BackoffStrategy;
+  maxAttempts: number;
+  baseDelayMs: number;
+  useJitter: boolean;
+  workFn?: WorkFn<T>;
+  retryHandlers: RetryHandler[];
+  exhaustedHandlers: ExhaustedHandler[];
+}
+export declare class RetryBuilder<T = unknown> implements PromiseLike<T> {
+  private readonly config;
+  private executionPromise?;
+  constructor(config?: Partial<RetryConfig<T>>);
+  get exponential(): RetryBuilder<T>;
+  get linear(): RetryBuilder<T>;
+  get constant(): RetryBuilder<T>;
+  get immediate(): RetryBuilder<T>;
+  attempts(count: number): RetryBuilder<T>;
+  delay(ms: number): RetryBuilder<T>;
+  jitter(enabled?: boolean): RetryBuilder<T>;
+  work<R>(fn: WorkFn<R>): RetryBuilder<R>;
+  on(event: 'retry', handler: RetryHandler): RetryBuilder<T>;
+  on(event: 'exhausted', handler: ExhaustedHandler): RetryBuilder<T>;
+  run(): Promise<T>;
+  then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+  finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+  private execute;
+}
+export declare const Retry: RetryBuilder;
+export { type BackoffStrategy, type ExhaustedHandler, Retry as default, type RetryHandler, type WorkFn };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/retry.ts"],"mappings":"A,KAAY;KAEA,gBACV,gBACA,qCACoB;KAEV,oBAAoB,gBAAgB,4BAA4B;KAEhE,OAAO,gBAAgB,oBAAoB,QAAQ,KAAK;UAE1D,YAAY;EACpB,UAAU;EACV;EACA;EACA;EACA,SAAS,OAAO;EAChB,eAAe;EACf,mBAAmB;;qBAwCR,aAAa,wBAAwB,YAAY;mBAC3C;UACT;EAER,YAAY,SAAS,QAAQ,YAAY;MAYrC,eAAe,aAAa;MAI5B,UAAU,aAAa;MAIvB,YAAY,aAAa;MAIzB,aAAa,aAAa;EAI9B,SAAS,gBAAgB,aAAa;EAOtC,MAAM,aAAa,aAAa;EAOhC,OAAO,oBAAiB,aAAa;EAIrC,KAAK,GAAG,IAAI,OAAO,KAAK,aAAa;EAOrC,GAAG,gBAAgB,SAAS,eAAe,aAAa;EACxD,GAAG,oBAAoB,SAAS,mBAAmB,aAAa;EAmB1D,OAAO,QAAQ;EAIrB,KAAK,WAAW,GAAG,kBACjB,gBAAgB,OAAO,MAAM,WAAW,YAAY,+BACpD,eAAe,oBAAoB,WAAW,YAAY,gCACzD,QAAQ,WAAW;EAOtB,MAAM,iBACJ,eAAe,oBAAoB,UAAU,YAAY,+BACxD,QAAQ,IAAI;EAIf,QAAQ,8CAA8C,QAAQ;UAahD;;qBAoDH,OAAO"}

package/dist/index.d.mts

@@ -0,0 +1,36 @@
+type BackoffStrategy = 'exponential' | 'linear' | 'constant' | 'none';
+type RetryHandler = (error: unknown, attempt: number) => boolean | void | Promise<boolean | void>;
+type ExhaustedHandler = (error: unknown, attempts: number) => void | Promise<void>;
+type WorkFn<T = unknown> = (attempt: number) => Promise<T> | T;
+interface RetryConfig<T = unknown> {
+  strategy: BackoffStrategy;
+  maxAttempts: number;
+  baseDelayMs: number;
+  useJitter: boolean;
+  workFn?: WorkFn<T>;
+  retryHandlers: RetryHandler[];
+  exhaustedHandlers: ExhaustedHandler[];
+}
+export declare class RetryBuilder<T = unknown> implements PromiseLike<T> {
+  private readonly config;
+  private executionPromise?;
+  constructor(config?: Partial<RetryConfig<T>>);
+  get exponential(): RetryBuilder<T>;
+  get linear(): RetryBuilder<T>;
+  get constant(): RetryBuilder<T>;
+  get immediate(): RetryBuilder<T>;
+  attempts(count: number): RetryBuilder<T>;
+  delay(ms: number): RetryBuilder<T>;
+  jitter(enabled?: boolean): RetryBuilder<T>;
+  work<R>(fn: WorkFn<R>): RetryBuilder<R>;
+  on(event: 'retry', handler: RetryHandler): RetryBuilder<T>;
+  on(event: 'exhausted', handler: ExhaustedHandler): RetryBuilder<T>;
+  run(): Promise<T>;
+  then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined): Promise<TResult1 | TResult2>;
+  catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null | undefined): Promise<T | TResult>;
+  finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+  private execute;
+}
+export declare const Retry: RetryBuilder;
+export { type BackoffStrategy, type ExhaustedHandler, Retry as default, type RetryHandler, type WorkFn };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/retry.ts"],"mappings":"A,KAAY;KAEA,gBACV,gBACA,qCACoB;KAEV,oBAAoB,gBAAgB,4BAA4B;KAEhE,OAAO,gBAAgB,oBAAoB,QAAQ,KAAK;UAE1D,YAAY;EACpB,UAAU;EACV;EACA;EACA;EACA,SAAS,OAAO;EAChB,eAAe;EACf,mBAAmB;;qBAwCR,aAAa,wBAAwB,YAAY;mBAC3C;UACT;EAER,YAAY,SAAS,QAAQ,YAAY;MAYrC,eAAe,aAAa;MAI5B,UAAU,aAAa;MAIvB,YAAY,aAAa;MAIzB,aAAa,aAAa;EAI9B,SAAS,gBAAgB,aAAa;EAOtC,MAAM,aAAa,aAAa;EAOhC,OAAO,oBAAiB,aAAa;EAIrC,KAAK,GAAG,IAAI,OAAO,KAAK,aAAa;EAOrC,GAAG,gBAAgB,SAAS,eAAe,aAAa;EACxD,GAAG,oBAAoB,SAAS,mBAAmB,aAAa;EAmB1D,OAAO,QAAQ;EAIrB,KAAK,WAAW,GAAG,kBACjB,gBAAgB,OAAO,MAAM,WAAW,YAAY,+BACpD,eAAe,oBAAoB,WAAW,YAAY,gCACzD,QAAQ,WAAW;EAOtB,MAAM,iBACJ,eAAe,oBAAoB,UAAU,YAAY,+BACxD,QAAQ,IAAI;EAIf,QAAQ,8CAA8C,QAAQ;UAahD;;qBAoDH,OAAO"}

package/dist/index.mjs

@@ -0,0 +1,144 @@
+// src/retry.ts
+function waitDelay(ms) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function computeDelay(strategy, baseDelayMs, attemptNumber, useJitter) {
+	if (baseDelayMs <= 0 || strategy === "none") return 0;
+	let delayMs;
+	switch (strategy) {
+		case "exponential":
+			delayMs = baseDelayMs * 2 ** (attemptNumber - 1);
+			break;
+		case "linear":
+			delayMs = baseDelayMs * attemptNumber;
+			break;
+		case "constant": delayMs = baseDelayMs;
+	}
+	if (useJitter) return Math.random() * delayMs;
+	return delayMs;
+}
+var RetryBuilder = class RetryBuilder {
+	config;
+	executionPromise;
+	constructor(config) {
+		this.config = {
+			strategy: config?.strategy ?? "exponential",
+			maxAttempts: config?.maxAttempts ?? 3,
+			baseDelayMs: config?.baseDelayMs ?? 100,
+			useJitter: config?.useJitter ?? false,
+			workFn: config?.workFn,
+			retryHandlers: [...config?.retryHandlers ?? []],
+			exhaustedHandlers: [...config?.exhaustedHandlers ?? []]
+		};
+	}
+	get exponential() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "exponential"
+		});
+	}
+	get linear() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "linear"
+		});
+	}
+	get constant() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "constant"
+		});
+	}
+	get immediate() {
+		return new RetryBuilder({
+			...this.config,
+			strategy: "none",
+			baseDelayMs: 0
+		});
+	}
+	attempts(count) {
+		if (!Number.isInteger(count) || count < 1) throw new RangeError("attempts must be an integer of at least 1");
+		return new RetryBuilder({
+			...this.config,
+			maxAttempts: count
+		});
+	}
+	delay(ms) {
+		if (ms < 0) throw new RangeError("delay must be a non-negative number");
+		return new RetryBuilder({
+			...this.config,
+			baseDelayMs: ms
+		});
+	}
+	jitter(enabled = true) {
+		return new RetryBuilder({
+			...this.config,
+			useJitter: enabled
+		});
+	}
+	work(fn) {
+		return new RetryBuilder({
+			...this.config,
+			workFn: fn
+		});
+	}
+	on(event, handler) {
+		if (event === "retry") return new RetryBuilder({
+			...this.config,
+			retryHandlers: [...this.config.retryHandlers, handler]
+		});
+		if (event === "exhausted") return new RetryBuilder({
+			...this.config,
+			exhaustedHandlers: [...this.config.exhaustedHandlers, handler]
+		});
+		throw new TypeError(`Unsupported event type: ${String(event)}`);
+	}
+	async run() {
+		return this.execute();
+	}
+	then(onfulfilled, onrejected) {
+		if (!this.executionPromise) this.executionPromise = this.execute();
+		return this.executionPromise.then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	finally(onfinally) {
+		return this.then((value) => {
+			onfinally?.();
+			return value;
+		}, (reason) => {
+			onfinally?.();
+			throw reason;
+		});
+	}
+	async execute() {
+		const { workFn, maxAttempts, strategy, baseDelayMs, useJitter, retryHandlers, exhaustedHandlers } = this.config;
+		if (!workFn) throw new Error("No work function provided. Call .work(fn) before awaiting or running.");
+		let attempt = 0;
+		while (attempt < maxAttempts) {
+			attempt++;
+			try {
+				return await workFn(attempt);
+			} catch (error) {
+				if (attempt >= maxAttempts) {
+					for (const handler of exhaustedHandlers) await handler(error, attempt);
+					throw error;
+				}
+				let shouldContinue = true;
+				for (const handler of retryHandlers) if (await handler(error, attempt) === false) {
+					shouldContinue = false;
+					break;
+				}
+				if (!shouldContinue) throw error;
+				await waitDelay(computeDelay(strategy, baseDelayMs, attempt, useJitter));
+			}
+		}
+		throw new Error("Unreachable retry state");
+	}
+};
+const Retry = new RetryBuilder();
+
+export { Retry, Retry as default, RetryBuilder };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/retry.ts"],"sourcesContent":["export type BackoffStrategy = 'exponential' | 'linear' | 'constant' | 'none'\n\nexport type RetryHandler = (\n  error: unknown,\n  attempt: number\n) => boolean | void | Promise<boolean | void>\n\nexport type ExhaustedHandler = (error: unknown, attempts: number) => void | Promise<void>\n\nexport type WorkFn<T = unknown> = (attempt: number) => Promise<T> | T\n\ninterface RetryConfig<T = unknown> {\n  strategy: BackoffStrategy\n  maxAttempts: number\n  baseDelayMs: number\n  useJitter: boolean\n  workFn?: WorkFn<T>\n  retryHandlers: RetryHandler[]\n  exhaustedHandlers: ExhaustedHandler[]\n}\n\nfunction waitDelay(ms: number): Promise<void> {\n  if (ms <= 0) {\n    return Promise.resolve()\n  }\n  return new Promise((resolve) => setTimeout(resolve, ms))\n}\n\nfunction computeDelay(\n  strategy: BackoffStrategy,\n  baseDelayMs: number,\n  attemptNumber: number,\n  useJitter: boolean\n): number {\n  if (baseDelayMs <= 0 || strategy === 'none') {\n    return 0\n  }\n\n  let delayMs: number\n  switch (strategy) {\n    case 'exponential':\n      delayMs = baseDelayMs * 2 ** (attemptNumber - 1)\n      break\n    case 'linear':\n      delayMs = baseDelayMs * attemptNumber\n      break\n    case 'constant':\n      delayMs = baseDelayMs\n      break\n  }\n\n  if (useJitter) {\n    return Math.random() * delayMs\n  }\n\n  return delayMs\n}\n\nexport class RetryBuilder<T = unknown> implements PromiseLike<T> {\n  private readonly config: RetryConfig<T>\n  private executionPromise?: Promise<T>\n\n  constructor(config?: Partial<RetryConfig<T>>) {\n    this.config = {\n      strategy: config?.strategy ?? 'exponential',\n      maxAttempts: config?.maxAttempts ?? 3,\n      baseDelayMs: config?.baseDelayMs ?? 100,\n      useJitter: config?.useJitter ?? false,\n      workFn: config?.workFn,\n      retryHandlers: [...(config?.retryHandlers ?? [])],\n      exhaustedHandlers: [...(config?.exhaustedHandlers ?? [])],\n    }\n  }\n\n  get exponential(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'exponential' })\n  }\n\n  get linear(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'linear' })\n  }\n\n  get constant(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'constant' })\n  }\n\n  get immediate(): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, strategy: 'none', baseDelayMs: 0 })\n  }\n\n  attempts(count: number): RetryBuilder<T> {\n    if (!Number.isInteger(count) || count < 1) {\n      throw new RangeError('attempts must be an integer of at least 1')\n    }\n    return new RetryBuilder<T>({ ...this.config, maxAttempts: count })\n  }\n\n  delay(ms: number): RetryBuilder<T> {\n    if (ms < 0) {\n      throw new RangeError('delay must be a non-negative number')\n    }\n    return new RetryBuilder<T>({ ...this.config, baseDelayMs: ms })\n  }\n\n  jitter(enabled = true): RetryBuilder<T> {\n    return new RetryBuilder<T>({ ...this.config, useJitter: enabled })\n  }\n\n  work<R>(fn: WorkFn<R>): RetryBuilder<R> {\n    return new RetryBuilder<R>({\n      ...this.config,\n      workFn: fn,\n    })\n  }\n\n  on(event: 'retry', handler: RetryHandler): RetryBuilder<T>\n  on(event: 'exhausted', handler: ExhaustedHandler): RetryBuilder<T>\n  on(event: 'retry' | 'exhausted', handler: RetryHandler | ExhaustedHandler): RetryBuilder<T> {\n    if (event === 'retry') {\n      return new RetryBuilder<T>({\n        ...this.config,\n        retryHandlers: [...this.config.retryHandlers, handler as RetryHandler],\n      })\n    }\n\n    if (event === 'exhausted') {\n      return new RetryBuilder<T>({\n        ...this.config,\n        exhaustedHandlers: [...this.config.exhaustedHandlers, handler as ExhaustedHandler],\n      })\n    }\n\n    throw new TypeError(`Unsupported event type: ${String(event)}`)\n  }\n\n  async run(): Promise<T> {\n    return this.execute()\n  }\n\n  then<TResult1 = T, TResult2 = never>(\n    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,\n    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined\n  ): Promise<TResult1 | TResult2> {\n    if (!this.executionPromise) {\n      this.executionPromise = this.execute()\n    }\n    return this.executionPromise.then(onfulfilled, onrejected)\n  }\n\n  catch<TResult = never>(\n    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null | undefined\n  ): Promise<T | TResult> {\n    return this.then(undefined, onrejected)\n  }\n\n  finally(onfinally?: (() => void) | null | undefined): Promise<T> {\n    return this.then(\n      (value) => {\n        onfinally?.()\n        return value\n      },\n      (reason) => {\n        onfinally?.()\n        throw reason\n      }\n    )\n  }\n\n  private async execute(): Promise<T> {\n    const {\n      workFn,\n      maxAttempts,\n      strategy,\n      baseDelayMs,\n      useJitter,\n      retryHandlers,\n      exhaustedHandlers,\n    } = this.config\n\n    if (!workFn) {\n      throw new Error('No work function provided. Call .work(fn) before awaiting or running.')\n    }\n\n    let attempt = 0\n\n    while (attempt < maxAttempts) {\n      attempt++\n\n      try {\n        return await workFn(attempt)\n      } catch (error) {\n        if (attempt >= maxAttempts) {\n          for (const handler of exhaustedHandlers) {\n            await handler(error, attempt)\n          }\n          throw error\n        }\n\n        let shouldContinue = true\n        for (const handler of retryHandlers) {\n          const decision = await handler(error, attempt)\n          if (decision === false) {\n            shouldContinue = false\n            break\n          }\n        }\n\n        if (!shouldContinue) {\n          throw error\n        }\n\n        const waitMs = computeDelay(strategy, baseDelayMs, attempt, useJitter)\n        await waitDelay(waitMs)\n      }\n    }\n\n    throw new Error('Unreachable retry state')\n  }\n}\n\nexport const Retry: RetryBuilder = new RetryBuilder()\n\nexport default Retry\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@gwash3189/doover",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "A fluent, lightweight TypeScript retry library with backoff strategies and lifecycle hooks.",
+  "license": "MIT",
+  "author": "gwash3189",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gwash3189/doover.git"
+  },
+  "homepage": "https://github.com/Gwash3189/doover#readme",
+  "bugs": {
+    "url": "https://github.com/Gwash3189/doover/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepublishOnly": "npm run type-check && npm run lint && npm run test && npm run build",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-v8": "^5.1.0",
+    "oxlint": "^1.90.0",
+    "prettier": "^3.9.10",
+    "tsdown": "^0.23.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "keywords": [
+    "retry",
+    "doover",
+    "backoff",
+    "exponential",
+    "resilience",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}