curfew 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,184 @@
-# Temporary Holding Version
+# curfew
 
-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.
+Run batches from an (async) iterable and stop **before** a time budget runs out.
+
+Built for AWS Lambda (15 min hard limit) and similar time-limited runtimes: instead of being killed mid-batch, `curfew` won't start a batch that probably can't finish, and tells you to reschedule the rest.
+
+- No runtime dependencies
+- Pluggable time budget and duration estimator
+- In-flight batches are never killed; they get an `AbortSignal` instead
+
+## Install
+
+```sh
+npm install curfew
+```
+
+Requires Node.js 22+. Ships ESM and CommonJS.
+
+## Quick start (AWS Lambda)
+
+```ts
+import { LambdaBudget, runBatches } from 'curfew'
+
+export const handler = async (event, context) => {
+  let offset = event.offset
+
+  try {
+    const { batchesProcessed, mayHaveMore } = await runBatches(
+      fetchPages(offset),
+      async (page, { signal }) => {
+        await processPage(page, { signal })
+        offset++
+      },
+      { budget: new LambdaBudget(context, 60_000) },
+    )
+
+    if (mayHaveMore) {
+      await reenqueue({ offset: event.offset + batchesProcessed })
+    }
+  } catch (error) {
+    // The signal aborted mid-page: an expected timeout, not a failure.
+    // `curfew` passes handler errors through, so catch it here and resume from the interrupted page.
+    if (!(error instanceof Error && error.name === 'AbortError')) throw error
+    await reenqueue({ offset })
+  }
+}
+```
+
+## Example
+
+[`examples/basic.ts`](examples/basic.ts) processes 10 pages with a 1-second budget per run. It shows the three ways a run ends, and how to resume after each:
+
+- **Budget runs out mid-page.** `saveItem` passes `ctx.signal` to its async work, so it rejects with an `AbortError`. The example's `runOnce` catches that error (`curfew` passes handler errors through) and resumes from the interrupted page, which is why page processing must be idempotent.
+- **The next page won't fit.** `reason` is `estimate-exceeds-budget`, and the next run starts at the following page.
+- **All pages done.** `reason` is `done`.
+
+```sh
+npm run build && node examples/basic.ts
+```
+
+```
+run 1: starting at page 0
+  stopped: budget ran out during page 4
+run 2: starting at page 4
+  stopped: estimate-exceeds-budget
+run 3: starting at page 5
+  stopped: done
+all pages processed
+```
+
+Requires Node.js 22.18+ to run `.ts` files directly.
+
+## How it works
+
+Before pulling each batch, `runBatches` checks the budget. It stops and returns `mayHaveMore: true` with a `reason` if:
+
+- the budget is used up (`StopReason.BUDGET_EXHAUSTED`), or
+- the estimated batch duration is longer than the time remaining (`StopReason.ESTIMATE_EXCEEDS_BUDGET`).
+
+When the source runs out, it returns `mayHaveMore: false` with `StopReason.DONE`.
+
+```ts
+import { StopReason } from 'curfew'
+
+if (result.reason === StopReason.ESTIMATE_EXCEEDS_BUDGET) {
+  console.log('stopped with time left; consider a smaller batch size')
+}
+```
+
+The duration of a batch covers both fetching it from the source (`iterator.next()`) and running the handler, so slow async sources such as DB cursors or paginated APIs are counted. Durations are measured with `performance.now()`, so system clock changes don't affect the estimate.
+
+Batches run one at a time. Items from a sync iterable are passed to the handler as is: a sync iterable of promises hands the handler the promises themselves, not their values. A batch that has started is never interrupted: when the budget runs out, `ctx.signal` aborts with a `TimeoutError` reason (the same as `AbortSignal.timeout()`), so cooperative code such as `fetch(url, { signal })` can stop early.
+
+- If fetching a batch overruns the budget, the handler still runs, but `ctx.signal` is already aborted. Check `signal.aborted` first if that matters.
+- The abort timer is armed once, from `budget.remainingMs()` at the start of the run. With a custom budget that isn't based on the clock, the signal and the decision to stop can disagree.
+- For budgets longer than about 24.8 days (the `setTimeout` limit), including `Infinity`, the signal never aborts. The budget check before each batch still applies.
+
+Handler errors propagate unchanged.
+
+The budget is checked before pulling the next item, so no item is ever pulled and then dropped. As a result, `mayHaveMore: true` means "there may be more work", not "there is more work": if the budget runs out just as the source is exhausted, the next run simply processes 0 batches and returns `mayHaveMore: false`.
+
+### The source is not closed
+
+`runBatches` never calls `iterator.return()`, whether it finishes, stops early or the handler throws. You own the source's cleanup. You can resume either by offset (`batchesProcessed`) in a new invocation, or by passing the same iterator or generator to `runBatches` again. An array (or any iterable that creates a fresh iterator each time) starts again from the beginning, so resume it by offset instead:
+
+```ts
+const source = generateWork()
+const first = await runBatches(source, handle, { budget })
+if (first.mayHaveMore) await runBatches(source, handle, { budget: nextBudget })
+```
+
+## Budgets
+
+```ts
+import { DeadlineBudget, FixedBudget, LambdaBudget } from 'curfew'
+
+new FixedBudget(13 * 60_000)              // 13 minutes from now
+new DeadlineBudget(new Date('2026-12-01')) // until an absolute time (Date or epoch ms)
+new LambdaBudget(context, 60_000)          // Lambda remaining time minus a 60 s margin
+```
+
+### Custom budget
+
+Implement `TimeBudget`:
+
+```ts
+import type { TimeBudget } from 'curfew'
+
+class JobBudget implements TimeBudget {
+  constructor(private job: { expiresAt: number }) {}
+  remainingMs() {
+    return this.job.expiresAt - Date.now()
+  }
+}
+```
+
+## Estimators
+
+By default, the estimate is the longest batch seen so far (`MaxEstimator`), so `runBatches` errs toward stopping early. Before any batch has run, the estimate is `0`, so the first batch runs as long as any time remains. Pass `new MaxEstimator(initialMs)` to require that much time for the first batch:
+
+```ts
+import { MaxEstimator, runBatches } from 'curfew'
+
+await runBatches(source, handle, { budget, estimator: new MaxEstimator(30_000) })
+```
+
+### Custom estimator
+
+Implement `Estimator`. `record` is called with each batch's duration, and `estimateMs` is consulted before each batch:
+
+```ts
+import type { Estimator } from 'curfew'
+
+class EwmaEstimator implements Estimator {
+  private value = 0
+  constructor(private alpha = 0.3) {}
+  record(ms: number) {
+    this.value = this.value === 0 ? ms : this.alpha * ms + (1 - this.alpha) * this.value
+  }
+  estimateMs() {
+    return this.value
+  }
+}
+```
+
+## API
+
+```ts
+runBatches<T>(
+  source: Iterable<T> | AsyncIterable<T>,
+  handler: (batch: T, ctx: { signal: AbortSignal; index: number }) => Promise<void> | void,
+  options: { budget: TimeBudget; estimator?: Estimator },
+): Promise<{ batchesProcessed: number; mayHaveMore: boolean; reason: StopReason }>
+
+enum StopReason {
+  DONE = 'done',
+  BUDGET_EXHAUSTED = 'budget-exhausted',
+  ESTIMATE_EXCEEDS_BUDGET = 'estimate-exceeds-budget',
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// src/budgets/DeadlineBudget.ts
+var DeadlineBudget = class {
+	deadline;
+	constructor(deadline) {
+		this.deadline = deadline instanceof Date ? deadline.getTime() : deadline;
+	}
+	remainingMs() {
+		return this.deadline - Date.now();
+	}
+};
+// src/budgets/FixedBudget.ts
+var FixedBudget = class extends DeadlineBudget {
+	constructor(durationMs) {
+		super(Date.now() + durationMs);
+	}
+};
+// src/budgets/LambdaBudget.ts
+var LambdaBudget = class {
+	context;
+	safetyMarginMs;
+	constructor(context, safetyMarginMs) {
+		this.context = context;
+		this.safetyMarginMs = safetyMarginMs;
+	}
+	remainingMs() {
+		return this.context.getRemainingTimeInMillis() - this.safetyMarginMs;
+	}
+};
+// src/estimators/MaxEstimator.ts
+var MaxEstimator = class {
+	max;
+	constructor(initialMs = 0) {
+		this.max = initialMs;
+	}
+	record(ms) {
+		this.max = Math.max(this.max, ms);
+	}
+	estimateMs() {
+		return this.max;
+	}
+};
+// src/runner/StopReason.ts
+let StopReason = /* @__PURE__ */ function(StopReason) {
+	StopReason["DONE"] = "done";
+	StopReason["BUDGET_EXHAUSTED"] = "budget-exhausted";
+	StopReason["ESTIMATE_EXCEEDS_BUDGET"] = "estimate-exceeds-budget";
+	return StopReason;
+}({});
+// src/runner/RunBatches.ts
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+async function runBatches(source, handler, { budget, estimator = new MaxEstimator() }) {
+	const batches = getIterator(source);
+	const deadline = abortWhenBudgetRunsOut(budget);
+	let batchesProcessed = 0;
+	try {
+		while (true) {
+			const reason = reasonToStopBeforeNextBatch(budget, estimator);
+			if (reason) return {
+				batchesProcessed,
+				mayHaveMore: true,
+				reason
+			};
+			const startedAt = performance.now();
+			const next = await batches.next();
+			if (next.done) return {
+				batchesProcessed,
+				mayHaveMore: false,
+				reason: "done"
+			};
+			await handler(next.value, {
+				signal: deadline.signal,
+				index: batchesProcessed
+			});
+			estimator.record(performance.now() - startedAt);
+			batchesProcessed++;
+		}
+	} finally {
+		deadline.cancel();
+	}
+}
+function reasonToStopBeforeNextBatch(budget, estimator) {
+	const remainingMs = budget.remainingMs();
+	if (!(remainingMs > 0)) return "budget-exhausted";
+	if (!(estimator.estimateMs() <= remainingMs)) return "estimate-exceeds-budget";
+	return null;
+}
+function abortWhenBudgetRunsOut(budget) {
+	const controller = new AbortController();
+	const remainingMs = budget.remainingMs();
+	const delayMs = remainingMs > 0 ? remainingMs : 0;
+	if (delayMs > MAX_TIMER_DELAY_MS) return {
+		signal: controller.signal,
+		cancel: () => {}
+	};
+	const timer = setTimeout(() => controller.abort(new DOMException("Budget exhausted", "TimeoutError")), delayMs);
+	timer.unref();
+	return {
+		signal: controller.signal,
+		cancel: () => clearTimeout(timer)
+	};
+}
+function getIterator(source) {
+	return isAsyncIterable(source) ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+}
+function isAsyncIterable(source) {
+	return typeof source[Symbol.asyncIterator] === "function";
+}
+exports.DeadlineBudget = DeadlineBudget;
+exports.FixedBudget = FixedBudget;
+exports.LambdaBudget = LambdaBudget;
+exports.MaxEstimator = MaxEstimator;
+exports.StopReason = StopReason;
+exports.runBatches = runBatches;

package/dist/index.d.cts

@@ -0,0 +1,52 @@
+interface TimeBudget {
+  remainingMs(): number;
+}
+export declare class DeadlineBudget implements TimeBudget {
+  private readonly deadline;
+  constructor(deadline: Date | number);
+  remainingMs(): number;
+}
+export declare class FixedBudget extends DeadlineBudget {
+  constructor(durationMs: number);
+}
+interface LambdaContextLike {
+  getRemainingTimeInMillis(): number;
+}
+export declare class LambdaBudget implements TimeBudget {
+  private readonly context;
+  private readonly safetyMarginMs;
+  constructor(context: LambdaContextLike, safetyMarginMs: number);
+  remainingMs(): number;
+}
+interface Estimator {
+  record(ms: number): void;
+  estimateMs(): number;
+}
+export declare class MaxEstimator implements Estimator {
+  private max;
+  constructor(initialMs?: number);
+  record(ms: number): void;
+  estimateMs(): number;
+}
+interface BatchContext {
+  signal: AbortSignal;
+  index: number;
+}
+type BatchHandler<T> = (batch: T, ctx: BatchContext) => Promise<void> | void;
+type BatchSource<T> = Iterable<T> | AsyncIterable<T>;
+interface RunOptions {
+  budget: TimeBudget;
+  estimator?: Estimator;
+}
+export declare enum StopReason {
+  DONE = "done",
+  BUDGET_EXHAUSTED = "budget-exhausted",
+  ESTIMATE_EXCEEDS_BUDGET = "estimate-exceeds-budget"
+}
+interface RunResult {
+  batchesProcessed: number;
+  mayHaveMore: boolean;
+  reason: StopReason;
+}
+export declare function runBatches<T>(source: BatchSource<T>, handler: BatchHandler<T>, { budget, estimator }: RunOptions): Promise<RunResult>;
+export type { BatchContext, BatchHandler, BatchSource, Estimator, LambdaContextLike, RunOptions, RunResult, TimeBudget };

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+interface TimeBudget {
+  remainingMs(): number;
+}
+export declare class DeadlineBudget implements TimeBudget {
+  private readonly deadline;
+  constructor(deadline: Date | number);
+  remainingMs(): number;
+}
+export declare class FixedBudget extends DeadlineBudget {
+  constructor(durationMs: number);
+}
+interface LambdaContextLike {
+  getRemainingTimeInMillis(): number;
+}
+export declare class LambdaBudget implements TimeBudget {
+  private readonly context;
+  private readonly safetyMarginMs;
+  constructor(context: LambdaContextLike, safetyMarginMs: number);
+  remainingMs(): number;
+}
+interface Estimator {
+  record(ms: number): void;
+  estimateMs(): number;
+}
+export declare class MaxEstimator implements Estimator {
+  private max;
+  constructor(initialMs?: number);
+  record(ms: number): void;
+  estimateMs(): number;
+}
+interface BatchContext {
+  signal: AbortSignal;
+  index: number;
+}
+type BatchHandler<T> = (batch: T, ctx: BatchContext) => Promise<void> | void;
+type BatchSource<T> = Iterable<T> | AsyncIterable<T>;
+interface RunOptions {
+  budget: TimeBudget;
+  estimator?: Estimator;
+}
+export declare enum StopReason {
+  DONE = "done",
+  BUDGET_EXHAUSTED = "budget-exhausted",
+  ESTIMATE_EXCEEDS_BUDGET = "estimate-exceeds-budget"
+}
+interface RunResult {
+  batchesProcessed: number;
+  mayHaveMore: boolean;
+  reason: StopReason;
+}
+export declare function runBatches<T>(source: BatchSource<T>, handler: BatchHandler<T>, { budget, estimator }: RunOptions): Promise<RunResult>;
+export type { BatchContext, BatchHandler, BatchSource, Estimator, LambdaContextLike, RunOptions, RunResult, TimeBudget };

package/dist/index.mjs

@@ -0,0 +1,108 @@
+// src/budgets/DeadlineBudget.ts
+var DeadlineBudget = class {
+	deadline;
+	constructor(deadline) {
+		this.deadline = deadline instanceof Date ? deadline.getTime() : deadline;
+	}
+	remainingMs() {
+		return this.deadline - Date.now();
+	}
+};
+// src/budgets/FixedBudget.ts
+var FixedBudget = class extends DeadlineBudget {
+	constructor(durationMs) {
+		super(Date.now() + durationMs);
+	}
+};
+// src/budgets/LambdaBudget.ts
+var LambdaBudget = class {
+	context;
+	safetyMarginMs;
+	constructor(context, safetyMarginMs) {
+		this.context = context;
+		this.safetyMarginMs = safetyMarginMs;
+	}
+	remainingMs() {
+		return this.context.getRemainingTimeInMillis() - this.safetyMarginMs;
+	}
+};
+// src/estimators/MaxEstimator.ts
+var MaxEstimator = class {
+	max;
+	constructor(initialMs = 0) {
+		this.max = initialMs;
+	}
+	record(ms) {
+		this.max = Math.max(this.max, ms);
+	}
+	estimateMs() {
+		return this.max;
+	}
+};
+// src/runner/StopReason.ts
+let StopReason = /* @__PURE__ */ function(StopReason) {
+	StopReason["DONE"] = "done";
+	StopReason["BUDGET_EXHAUSTED"] = "budget-exhausted";
+	StopReason["ESTIMATE_EXCEEDS_BUDGET"] = "estimate-exceeds-budget";
+	return StopReason;
+}({});
+// src/runner/RunBatches.ts
+const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+async function runBatches(source, handler, { budget, estimator = new MaxEstimator() }) {
+	const batches = getIterator(source);
+	const deadline = abortWhenBudgetRunsOut(budget);
+	let batchesProcessed = 0;
+	try {
+		while (true) {
+			const reason = reasonToStopBeforeNextBatch(budget, estimator);
+			if (reason) return {
+				batchesProcessed,
+				mayHaveMore: true,
+				reason
+			};
+			const startedAt = performance.now();
+			const next = await batches.next();
+			if (next.done) return {
+				batchesProcessed,
+				mayHaveMore: false,
+				reason: "done"
+			};
+			await handler(next.value, {
+				signal: deadline.signal,
+				index: batchesProcessed
+			});
+			estimator.record(performance.now() - startedAt);
+			batchesProcessed++;
+		}
+	} finally {
+		deadline.cancel();
+	}
+}
+function reasonToStopBeforeNextBatch(budget, estimator) {
+	const remainingMs = budget.remainingMs();
+	if (!(remainingMs > 0)) return "budget-exhausted";
+	if (!(estimator.estimateMs() <= remainingMs)) return "estimate-exceeds-budget";
+	return null;
+}
+function abortWhenBudgetRunsOut(budget) {
+	const controller = new AbortController();
+	const remainingMs = budget.remainingMs();
+	const delayMs = remainingMs > 0 ? remainingMs : 0;
+	if (delayMs > MAX_TIMER_DELAY_MS) return {
+		signal: controller.signal,
+		cancel: () => {}
+	};
+	const timer = setTimeout(() => controller.abort(new DOMException("Budget exhausted", "TimeoutError")), delayMs);
+	timer.unref();
+	return {
+		signal: controller.signal,
+		cancel: () => clearTimeout(timer)
+	};
+}
+function getIterator(source) {
+	return isAsyncIterable(source) ? source[Symbol.asyncIterator]() : source[Symbol.iterator]();
+}
+function isAsyncIterable(source) {
+	return typeof source[Symbol.asyncIterator] === "function";
+}
+export { DeadlineBudget, FixedBudget, LambdaBudget, MaxEstimator, StopReason, runBatches };

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "curfew",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Run batches from an (async) iterable and stop before a time budget runs out.",
+  "keywords": [
+    "batch",
+    "deadline",
+    "timeout",
+    "time-budget",
+    "lambda",
+    "aws-lambda",
+    "abortsignal",
+    "graceful-shutdown"
+  ],
+  "license": "MIT",
+  "author": "Pushkal Guha Choudhury",
+  "homepage": "https://github.com/Maganlal-Meghraj/curfew#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Maganlal-Meghraj/curfew.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc",
+    "lint": "eslint .",
+    "lint:pkg": "publint && attw --pack .",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run lint:pkg"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.20.5",
+    "eslint": "^10.14.0",
+    "publint": "^0.3.25",
+    "tsdown": "0.23.7",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "^5.1.0"
+  }
+}