Getting Started

Requirements

• Node.js 24 or later
• pnpm (or npm/yarn)

Installing from GitHub Packages

Packages are published to the GitHub Package Registry under the @studnicky scope. Add the registry to your .npmrc:

@studnicky:registry=https://npm.pkg.github.com

Then install any package:

pnpm add @studnicky/retry

Minimal usage example

import { Retry } from '@studnicky/retry';

// Create via static factory
const retry = Retry.create({ maxRetries: 3 });

// Or use the fluent builder
const retryWithClassifier = Retry.builder()
  .maxRetries(5)
  .build();

// Execute any async operation with automatic retry
const result = await retry.execute(async () => {
  const response = await fetch('https://api.example.com/data');
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
});

Extending a primitive

Every class exposes documented protected seams. Most are observer hooks for tracing and metrics; some packages also expose behavioral hooks that intentionally transform or redirect control flow. Subclass to add observability without touching the base class:

import { Retry } from '@studnicky/retry';
import type { RetryContextInterface } from '@studnicky/retry';

class InstrumentedRetry extends Retry {
  protected override onAttempt(ctx: RetryContextInterface): void {
    console.log(`[retry] attempt ${ctx.attemptNumber} of ${this.maxRetries}`);
  }

  protected override onSuccess(ctx: RetryContextInterface): void {
    console.log(`[retry] succeeded after ${ctx.attemptNumber} attempt(s)`);
  }

  protected override onGiveUp(ctx: RetryContextInterface, error: Error): void {
    console.error(`[retry] gave up after ${ctx.attemptNumber} attempts:`, error.message);
  }
}

const retry = new InstrumentedRetry({ maxRetries: 3 });

The base Retry class never logs; the observer hooks are no-ops by default. Override only what you need, and check each package page for which hooks are observational versus behavioral.

Next steps

• Architecture: the three design principles in depth
• Packages: the full workspace package index with API examples