superlib 0.1.0

package/dist/task/retry.js

@@ -0,0 +1,61 @@
+import { assert, ErrResult, Result } from "../basic/index.js";
+import { RealRandom } from "../random/index.js";
+import { multiplyDuration, sleep } from "../time/index.js";
+export function retry(taskOrOptions, optionsOrDependencies, dependencies) {
+    if (typeof taskOrOptions === "function") {
+        return runRetry(taskOrOptions, optionsOrDependencies, dependencies);
+    }
+    return (task) => () => runRetry(task, taskOrOptions, optionsOrDependencies);
+}
+async function runRetry(task, options, dependencies) {
+    const until = options.until ?? (() => true);
+    const delay = options.delay instanceof Function
+        ? options.delay
+        : JitteredRetryPolicy(ExponentialBackoffRetryPolicy(options.delay), {}, dependencies);
+    let attempt = 0;
+    while (true) {
+        let thrownError = undefined;
+        let resultError = undefined;
+        try {
+            const result = await task();
+            if (!(result instanceof Result) || result.isOk()) {
+                return result;
+            }
+            resultError = result;
+        }
+        catch (error) {
+            thrownError = error;
+        }
+        assert(!!(thrownError || resultError));
+        if (attempt < options.times && until(thrownError || resultError)) {
+            const sleepDuration = delay(attempt++);
+            await sleep(sleepDuration);
+        }
+        else {
+            if (thrownError) {
+                throw thrownError;
+            }
+            else {
+                return resultError;
+            }
+        }
+    }
+}
+export function ExponentialBackoffRetryPolicy(base) {
+    const baseDuration = Temporal.Duration.from(base);
+    return (attempt) => {
+        return multiplyDuration(baseDuration, 2 ** attempt);
+    };
+}
+export function JitteredRetryPolicy(base, options, dependencies) {
+    const random = dependencies?.random ?? new RealRandom();
+    const minFactor = options?.minFactor ?? 0;
+    const maxFactor = options?.maxFactor ?? 1;
+    assert(minFactor >= 0 && maxFactor > minFactor, `invalid jitter range: min=${minFactor} max=${maxFactor}`);
+    const basePolicy = base instanceof Function ? base : () => base;
+    return (attempt) => {
+        const baseDuration = Temporal.Duration.from(basePolicy(attempt));
+        const factor = random.nextNumber(minFactor, maxFactor);
+        return multiplyDuration(baseDuration, factor);
+    };
+}

package/dist/task/timeout.d.ts

@@ -0,0 +1,21 @@
+import type { Task, TaskMapper } from "./types";
+import { BaseError, Result } from "../basic";
+import { type DurationLike } from "../time";
+export interface TimeoutOptions {
+    timeout: DurationLike;
+    useResult?: boolean;
+}
+export type TimeoutErr = {
+    type: "timeout";
+    timeout: Temporal.Duration;
+};
+type TimeoutAsResult<Return, Options> = Options extends {
+    useResult: true;
+} ? Return extends Result<infer V, infer E> ? Result<V, E | TimeoutErr> : never : Return;
+export declare function timeout<T, O extends TimeoutOptions>(task: Task<T>, options: O): Promise<TimeoutAsResult<T, O>>;
+export declare function timeout<T, O extends TimeoutOptions>(options: O): TaskMapper<T, TimeoutAsResult<T, O>>;
+export declare class TimeoutError extends BaseError {
+    constructor(duration: Temporal.Duration);
+}
+export {};
+//# sourceMappingURL=timeout.d.ts.map

package/dist/task/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/task/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,EAAE,SAAS,EAAkB,MAAM,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAqC,KAAK,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9E,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,CAAA;IACrB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,MAAM,UAAU,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAA;CAAE,CAAA;AAExE,KAAK,eAAe,CAAC,MAAM,EAAE,OAAO,IAAI,OAAO,SAAS;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,GACvE,MAAM,SAAS,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GACrC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,GACzB,KAAK,GACP,MAAM,CAAA;AAGV,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,EACjD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACb,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AACjC,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,EACjD,OAAO,EAAE,CAAC,GACT,UAAU,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AA4CvC,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;CAGxC"}

package/dist/task/timeout.js

@@ -0,0 +1,38 @@
+import { BaseError, Err, ErrResult, Result } from "../basic/index.js";
+import { durationToMs, prettyPrintDuration } from "../time/index.js";
+export function timeout(taskOrOptions, options) {
+    if (typeof taskOrOptions === "function") {
+        return runTimeout(taskOrOptions, options);
+    }
+    return (task) => () => runTimeout(task, taskOrOptions);
+}
+async function runTimeout(task, options) {
+    const useResult = !!options.useResult;
+    const timeoutDuration = Temporal.Duration.from(options.timeout);
+    const timeoutMs = durationToMs(timeoutDuration);
+    // note: we can't use sleep here because we want to ensure timeoutPromise cancellation
+    let timeoutId = undefined;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new TimeoutError(timeoutDuration));
+        }, timeoutMs);
+    });
+    try {
+        return (await Promise.race([task(), timeoutPromise]).catch((e) => {
+            if (useResult) {
+                return Err({ type: "timeout", timeout: timeoutDuration });
+            }
+            throw e;
+        }));
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+export class TimeoutError extends BaseError {
+    constructor(duration) {
+        super(`Task has timeout after ${prettyPrintDuration(duration)}`);
+    }
+}

package/dist/task/types.d.ts

@@ -0,0 +1,3 @@
+export type Task<T> = () => Promise<T>;
+export type TaskMapper<I, O> = (i: Task<I>) => Task<O>;
+//# sourceMappingURL=types.d.ts.map

package/dist/task/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/task/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;AAEtC,MAAM,MAAM,UAAU,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAA"}

package/dist/task/types.js

@@ -0,0 +1 @@
+export {};

package/dist/time/Clock.d.ts

@@ -0,0 +1,18 @@
+import type { PublicInterface } from "../types";
+import type { DurationLike } from "./index";
+export type IClock = PublicInterface<AbstractClock>;
+export declare abstract class AbstractClock implements IClock {
+    abstract now(): Temporal.Instant;
+    nowDate(): Date;
+}
+export declare class Clock extends AbstractClock {
+    now(): Temporal.Instant;
+}
+export declare class TestClock extends AbstractClock {
+    private _now;
+    constructor(_now: Temporal.Instant);
+    now(): Temporal.Instant;
+    advance(duration: DurationLike): void;
+    reset(now: Temporal.Instant): void;
+}
+//# sourceMappingURL=Clock.d.ts.map

package/dist/time/Clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../src/time/Clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,MAAM,MAAM,MAAM,GAAG,eAAe,CAAC,aAAa,CAAC,CAAA;AAEnD,8BAAsB,aAAc,YAAW,MAAM;IACnD,QAAQ,CAAC,GAAG,IAAI,QAAQ,CAAC,OAAO;IAEhC,OAAO,IAAI,IAAI;CAGhB;AAED,qBAAa,KAAM,SAAQ,aAAa;IACtC,GAAG,IAAI,QAAQ,CAAC,OAAO;CAGxB;AAED,qBAAa,SAAU,SAAQ,aAAa;IAC9B,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,QAAQ,CAAC,OAAO;IAI1C,GAAG,IAAI,QAAQ,CAAC,OAAO;IAIvB,OAAO,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAIrC,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,GAAG,IAAI;CAGnC"}

package/dist/time/Clock.js

@@ -0,0 +1,26 @@
+export class AbstractClock {
+    nowDate() {
+        return new Date(this.now().epochMilliseconds);
+    }
+}
+export class Clock extends AbstractClock {
+    now() {
+        return Temporal.Now.instant();
+    }
+}
+export class TestClock extends AbstractClock {
+    _now;
+    constructor(_now) {
+        super();
+        this._now = _now;
+    }
+    now() {
+        return this._now;
+    }
+    advance(duration) {
+        this._now = this._now.add(Temporal.Duration.from(duration));
+    }
+    reset(now) {
+        this._now = now;
+    }
+}

package/dist/time/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./sleep";
+export * from "./Clock";
+export * from "./temporal";
+//# sourceMappingURL=index.d.ts.map

package/dist/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/time/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,cAAc,YAAY,CAAA"}

package/dist/time/index.js

@@ -0,0 +1,3 @@
+export * from "./sleep.js";
+export * from "./Clock.js";
+export * from "./temporal.js";

package/dist/time/sleep.d.ts

@@ -0,0 +1,3 @@
+import { type DurationLike } from "./index";
+export declare function sleep(duration: DurationLike): Promise<void>;
+//# sourceMappingURL=sleep.d.ts.map

package/dist/time/sleep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../src/time/sleep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAA;AAEzD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3D"}

package/dist/time/sleep.js

@@ -0,0 +1,5 @@
+import { durationToMs } from "./index.js";
+export function sleep(duration) {
+    const ms = durationToMs(Temporal.Duration.from(duration));
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/time/temporal.d.ts

@@ -0,0 +1,5 @@
+export type DurationLike = Omit<Temporal.DurationLike, "microseconds" | "nanoseconds"> | Omit<Temporal.Duration, "microseconds" | "nanoseconds">;
+export declare function multiplyDuration(base: Temporal.Duration, factor: number): Temporal.Duration;
+export declare function durationToMs(duration: Temporal.Duration): number;
+export declare function prettyPrintDuration(duration: Temporal.Duration): string;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/time/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../src/time/temporal.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,cAAc,GAAG,aAAa,CAAC,GAC3D,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa,CAAC,CAAA;AAE3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAW3F;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAIhE;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAkBvE"}

package/dist/time/temporal.js

@@ -0,0 +1,41 @@
+export function multiplyDuration(base, factor) {
+    return Temporal.Duration.from({
+        years: Math.round(base.years * factor),
+        months: Math.round(base.months * factor),
+        weeks: Math.round(base.weeks * factor),
+        days: Math.round(base.days * factor),
+        hours: Math.round(base.hours * factor),
+        minutes: Math.round(base.minutes * factor),
+        seconds: Math.round(base.seconds * factor),
+        milliseconds: Math.round(base.milliseconds * factor),
+    });
+}
+export function durationToMs(duration) {
+    const now = Temporal.Now.instant();
+    const target = now.add(Temporal.Duration.from(duration));
+    return target.epochMilliseconds - now.epochMilliseconds;
+}
+export function prettyPrintDuration(duration) {
+    // note: there is Intl.DurationFormat("en", { style: "narrow" }).format(duration) which should do the same thing but:
+    // 1. It's not available in node <= 22, Intl.DurationFormat is not available
+    // 2. Exact formatting output is dependent on ICU data and on some environments (CI) months get formatted as m instead of mo
+    // for these reasons it's better to always use bespoke implementation
+    const parts = [];
+    if (duration.years)
+        parts.push(`${duration.years}y`);
+    if (duration.months)
+        parts.push(`${duration.months}mo`);
+    if (duration.weeks)
+        parts.push(`${duration.weeks}w`);
+    if (duration.days)
+        parts.push(`${duration.days}d`);
+    if (duration.hours)
+        parts.push(`${duration.hours}h`);
+    if (duration.minutes)
+        parts.push(`${duration.minutes}m`);
+    if (duration.seconds)
+        parts.push(`${duration.seconds}s`);
+    if (duration.milliseconds)
+        parts.push(`${duration.milliseconds}ms`);
+    return parts.join(" ");
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type PublicInterface<T> = {
+    [K in keyof T]: T[K];
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA"}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "superlib",
+  "version": "0.1.0",
+  "description": "A missing standard library for TypeScript, providing utilities for async orchestration, error handling, filesystem abstraction, and common patterns",
+  "keywords": [
+    "async",
+    "result",
+    "stdlib",
+    "task",
+    "typescript",
+    "utilities"
+  ],
+  "license": "MIT",
+  "author": "Kris Kaczor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superlibdotdev/superlib.git"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./platform/filesystem": {
+      "types": "./dist/platform/filesystem/index.d.ts",
+      "default": "./dist/platform/filesystem/index.js"
+    },
+    "./platform/getPort": {
+      "types": "./dist/platform/getPort/index.d.ts",
+      "default": "./dist/platform/getPort/index.js"
+    },
+    "./platform/JsonHttpClient": {
+      "types": "./dist/platform/JsonHttpClient/index.d.ts",
+      "default": "./dist/platform/JsonHttpClient/index.js"
+    },
+    "./platform/ProcessContext": {
+      "types": "./dist/platform/ProcessContext/index.d.ts",
+      "default": "./dist/platform/ProcessContext/index.js"
+    },
+    "./platform/safeFetch": {
+      "types": "./dist/platform/safeFetch/index.d.ts",
+      "default": "./dist/platform/safeFetch/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run scripts/fix-imports.ts && cp ../../README.md .",
+    "lint": "oxlint --type-aware --type-check --deny-warnings",
+    "lint:fix": "bun run lint --fix --fix-dangerously --fix-suggestions",
+    "test": "bun test",
+    "test:vitest": "bun run scripts/transform-tests-for-vitest.ts && vitest run",
+    "fix": "cd ../.. && bun run fix"
+  },
+  "dependencies": {
+    "remeda": "^2.32.0",
+    "temporal-polyfill": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vitest": "^3.0.0",
+    "zod": "^4.3.5"
+  }
+}