Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions examples/logger.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
import { consoleLogger, createDeadlineBudget } from "../src/index.js";

function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
return new Promise((resolve, reject) => {
if (signal.aborted) {
reject(signal.reason);
return;
}

const timeoutId = setTimeout(() => {
resolve();
}, ms);

signal.addEventListener(
"abort",
() => {
clearTimeout(timeoutId);
reject(signal.reason);
},
{ once: true }
);
});
}

async function main() {
const budget = createDeadlineBudget({
timeoutMs: 300,
onOperationEnd: consoleLogger,
});

await budget.run("fast-operation", { timeoutMs: 100 }, async (signal) => {
await abortableSleep(50, signal);
return "done";
});

await budget.run(
"slow-operation",
{
timeoutMs: 50,
fallback: "fallback result",
},
async (signal) => {
await abortableSleep(200, signal);
return "real result";
}
);
}

main().catch((error) => {
console.error(error);
process.exit(1);
});
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
"typecheck": "tsc --noEmit",
"example:basic": "tsx examples/basic.ts",
"example:fallback": "tsx examples/fallback.ts",
"example:expired": "tsx examples/expired-deadline.ts"
"example:expired": "tsx examples/expired-deadline.ts",
"example:logger": "tsx examples/logger.ts"
},
"repository": {
"type": "git",
Expand Down
77 changes: 71 additions & 6 deletions src/index.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,24 @@
export type DeadlineExceededReason = "budget already expired" | "step timeout";

export interface OperationEndEvent {
name: string;
durationMs: number;
timedOut: boolean;
usedFallback: boolean;
error: unknown;
remainingBudgetMs: number;
}

export type DeadlineBudgetOptions = {
timeoutMs: number;
onOperationEnd?: (event: OperationEndEvent) => void;
};

export type RunOptions<T> = {
timeoutMs?: number;
fallback?: T;
};

export type DeadlineExceededReason = "budget already expired" | "step timeout";

export class DeadlineExceededError extends Error {
public readonly operationName: string;
public readonly deadlineReason: DeadlineExceededReason;
Expand Down Expand Up @@ -36,6 +46,26 @@ export function isAbortError(error: unknown): boolean {
return false;
}

function emitOperationEnd(
callback: ((event: OperationEndEvent) => void) | undefined,
event: OperationEndEvent
): void {
try {
callback?.(event);
} catch {
// Observability callbacks must never break the request path.
}
}

export function consoleLogger(event: OperationEndEvent): void {
const status = event.timedOut ? "timeout" : event.error ? "error" : "ok";

console.log(
`[deadlinekit] ${event.name} ${status} in ${event.durationMs}ms ` +
`(${event.remainingBudgetMs}ms remaining)`
);
}

export function createDeadlineBudget(options: DeadlineBudgetOptions) {
const startedAt = Date.now();
const deadlineAt = startedAt + options.timeoutMs;
Expand All @@ -49,33 +79,68 @@ export function createDeadlineBudget(options: DeadlineBudgetOptions) {
runOptions: RunOptions<T>,
operation: (signal: AbortSignal) => Promise<T>
): Promise<T> {
const start = Date.now();
let timedOut = false;
let usedFallback = false;
let error: unknown = null;

const availableMs = remainingMs();

if (availableMs <= 0) {
timedOut = true;
usedFallback = "fallback" in runOptions;

const deadlineError = new DeadlineExceededError(
name,
"budget already expired"
);

emitOperationEnd(options.onOperationEnd, {
name,
durationMs: Date.now() - start,
timedOut,
usedFallback,
error: deadlineError,
remainingBudgetMs: 0,
});

if ("fallback" in runOptions) {
return runOptions.fallback as T;
}

throw new DeadlineExceededError(name, "budget already expired");
throw deadlineError;
}

const timeoutMs = Math.min(runOptions.timeoutMs ?? availableMs, availableMs);
const controller = new AbortController();

const timeoutId = setTimeout(() => {
timedOut = true;
controller.abort(new DeadlineExceededError(name, "step timeout"));
}, timeoutMs);

try {
return await operation(controller.signal);
} catch (error) {
if ("fallback" in runOptions && isAbortError(error)) {
} catch (caughtError) {
error = caughtError;

if ("fallback" in runOptions && isAbortError(caughtError)) {
usedFallback = true;
return runOptions.fallback as T;
}

throw error;
throw caughtError;
} finally {
clearTimeout(timeoutId);

emitOperationEnd(options.onOperationEnd, {
name,
durationMs: Date.now() - start,
timedOut,
usedFallback,
error,
remainingBudgetMs: remainingMs(),
});
}
}

Expand Down
97 changes: 97 additions & 0 deletions tests/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -159,4 +159,101 @@ describe("createDeadlineBudget", () => {

expect(isAbortError(error)).toBe(true);
});

it("calls onOperationEnd after a successful operation", async () => {
const events: unknown[] = [];

const budget = createDeadlineBudget({
timeoutMs: 100,
onOperationEnd: (event) => {
events.push(event);
},
});

const result = await budget.run("successful-operation", {}, async (signal) => {
await abortableSleep(10, signal);
return "success";
});

expect(result).toBe("success");
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({
name: "successful-operation",
timedOut: false,
usedFallback: false,
error: null,
});
});

it("calls onOperationEnd after a timeout with fallback", async () => {
const events: unknown[] = [];

const budget = createDeadlineBudget({
timeoutMs: 100,
onOperationEnd: (event) => {
events.push(event);
},
});

const result = await budget.run(
"timeout-with-fallback",
{
timeoutMs: 10,
fallback: "fallback",
},
async (signal) => {
await abortableSleep(50, signal);
return "real";
}
);

expect(result).toBe("fallback");
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({
name: "timeout-with-fallback",
timedOut: true,
usedFallback: true,
});
});

it("calls onOperationEnd after a thrown operation error", async () => {
const events: unknown[] = [];
const operationError = new Error("database failed");

const budget = createDeadlineBudget({
timeoutMs: 100,
onOperationEnd: (event) => {
events.push(event);
},
});

await expect(
budget.run("error-operation", {}, async () => {
throw operationError;
})
).rejects.toThrow("database failed");

expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({
name: "error-operation",
timedOut: false,
usedFallback: false,
error: operationError,
});
});

it("does not let onOperationEnd errors break the operation", async () => {
const budget = createDeadlineBudget({
timeoutMs: 100,
onOperationEnd: () => {
throw new Error("logger failed");
},
});

const result = await budget.run("safe-callback-operation", {}, async () => {
return "success";
});

expect(result).toBe("success");
});
});
Loading