@pithy-sh/leaderboard 0.1.2 → 0.1.3

package/dist/retention/prune.d.ts

@@ -0,0 +1,39 @@
+import type { LeaderboardBoard } from "../config/config";
+import type { LeaderboardDatabase } from "../data/tables";
+export declare function pruneBoard(db: LeaderboardDatabase, board: LeaderboardBoard, now: Date): Promise<number>;
+/**
+ * What a sweep over several boards deleted, and whether every board was swept (#371).
+ *
+ * The count sits behind the discriminant rather than beside a list of failures. A sweep that skipped a
+ * board deleted fewer rows than a sweep that did not, and `{ deleted: 4 }` cannot tell those apart —
+ * so `partial` spells the number differently, and a caller reaches it only by having been told the
+ * sweep was short.
+ */
+export type PruneOutcome = {
+    /** Every board with a retention limit was swept. */
+    state: "pruned";
+    /** Rows deleted across them all. */
+    deleted: number;
+} | {
+    /** Some boards were swept and at least one threw. */
+    state: "partial";
+    /** What the boards that were swept deleted — a total with a known hole in it. */
+    counted: {
+        deleted: number;
+    };
+    /** The key of every board whose prune threw. Non-empty, or this would be `pruned`. */
+    unpruned: string[];
+};
+/**
+ * Prune every board that configures a retention limit.
+ *
+ * **One board at a time (#371).** Retention is per board and boards are independent, so a board whose
+ * prune throws — a window key its config disagrees with, a D1 that stopped answering mid-sweep — used to
+ * discard every deletion the sweep had already made and take the rank pass down with it. It now costs its
+ * own entry and nothing else, and the boards it did not reach are named.
+ *
+ * **The guard takes no binding.** What a D1 write throws is throw-site context about somebody's database.
+ * The board key is this capability's own configuration and is the only thing anybody can act on.
+ */
+export declare function pruneBoards(db: LeaderboardDatabase, boards: readonly LeaderboardBoard[], now: Date): Promise<PruneOutcome>;
+//# sourceMappingURL=prune.d.ts.map

package/dist/retention/prune.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune.d.ts","sourceRoot":"","sources":["../../src/retention/prune.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAwB1D,wBAAsB,UAAU,CAAC,EAAE,EAAE,mBAAmB,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAuB7G;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,oDAAoD;IACpD,KAAK,EAAE,QAAQ,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,qDAAqD;IACrD,KAAK,EAAE,SAAS,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7B,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,mBAAmB,EACvB,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,YAAY,CAAC,CAWvB"}

package/dist/retention/prune.js

@@ -0,0 +1,65 @@
+import { previousWindowKeys, windowKeyAt } from "../window/schedule.js";
+import { entryStore } from "../entry/store.js";
+//#region src/retention/prune.ts
+/**
+* Retention: how long closed windows live.
+*
+* This is the capability's plainest expression of principle 1. Nothing in the market offers unbounded
+* leaderboard history — PlayFab meters retained versions and tier-gates them (its own tutorial defaults
+* to keeping one), and Game Center holds an expired occurrence about 30 days and says outright it is not
+* an archival store. Here, closed windows sit in the adopter's own D1 for exactly as long as they choose,
+* in plain SQL they can join against their own tables. And the default is to keep **everything**: storage
+* is never the cost driver (docs/costs.md — 3 GB at 10M players against a 10 GB cap), so nothing is
+* deleted unless the adopter asks. Retention here is about data hygiene and compliance, not cost.
+*
+* Two ways to ask, mutually exclusive per board (validated in config):
+*
+*   - `retain: N`     — keep the newest N closed windows. A product limit ("browse the last 12 weeks").
+*   - `retainDays: N` — delete windows whose data is older than N days. A compliance limit.
+*
+* An all-time board never closes a window, so retention does not apply to it.
+*/
+const DAY_MS = 864e5;
+async function pruneBoard(db, board, now) {
+	if (board.window === void 0) return 0;
+	if (board.retain !== void 0) {
+		const closed = previousWindowKeys(board.window, now, board.retain);
+		const oldestKept = closed.length > 0 ? closed[closed.length - 1] : windowKeyAt(board.window, now);
+		return entryStore(db).pruneWindowsBefore(board.key, oldestKept);
+	}
+	if (board.retainDays !== void 0) {
+		const cutoff = windowKeyAt(board.window, /* @__PURE__ */ new Date(now.getTime() - board.retainDays * DAY_MS));
+		return entryStore(db).pruneWindowsBefore(board.key, cutoff);
+	}
+	return 0;
+}
+/**
+* Prune every board that configures a retention limit.
+*
+* **One board at a time (#371).** Retention is per board and boards are independent, so a board whose
+* prune throws — a window key its config disagrees with, a D1 that stopped answering mid-sweep — used to
+* discard every deletion the sweep had already made and take the rank pass down with it. It now costs its
+* own entry and nothing else, and the boards it did not reach are named.
+*
+* **The guard takes no binding.** What a D1 write throws is throw-site context about somebody's database.
+* The board key is this capability's own configuration and is the only thing anybody can act on.
+*/
+async function pruneBoards(db, boards, now) {
+	let deleted = 0;
+	const unpruned = [];
+	for (const board of boards) try {
+		deleted += await pruneBoard(db, board, now);
+	} catch {
+		unpruned.push(board.key);
+	}
+	return unpruned.length === 0 ? {
+		state: "pruned",
+		deleted
+	} : {
+		state: "partial",
+		counted: { deleted },
+		unpruned
+	};
+}
+//#endregion
+export { pruneBoard, pruneBoards };

package/dist/seeds/example.d.ts

@@ -0,0 +1,11 @@
+import { type SeedSet } from "@pithy-sh/core/src/seed/seed";
+/**
+ * A tiny demo board's worth of entries — the three canonical example users ({@link EXAMPLE_ADA} et al.)
+ * on an all-time board named `demo`. The `userId`s are the shared cast from `@pithy-sh/core`, so these
+ * scores belong to the same users `auth` seeds and `ledger`/`multiplayer` also reference: `pithy seed`
+ * fills a fresh backend with connected data, not isolated rows. Composed in only when the project turns
+ * on `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and `staging` — an example fixture
+ * never targets production, regardless of that setting.
+ */
+export declare const leaderboardExampleSeed: SeedSet;
+//# sourceMappingURL=example.d.ts.map

package/dist/seeds/example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example.d.ts","sourceRoot":"","sources":["../../src/seeds/example.ts"],"names":[],"mappings":"AAIA,OAAO,EAA2B,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAcrF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,OA6CnC,CAAC"}

package/dist/seeds/example.js

@@ -0,0 +1,67 @@
+import { LeaderboardEntry } from "../data/entry.js";
+import { LEADERBOARD_ENTRIES_TABLE } from "../data/tables.js";
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed } from "@pithy-sh/core/src/seed/seed";
+//#region src/seeds/example.ts
+/**
+* Where the example set sorts among the whole project's seed registry. It runs after `auth` (100),
+* whose example seeds the users these entries belong to, so the owning identities exist first — the
+* order encodes that dependency, exactly like the migration registry. It need not line up with
+* {@link LEADERBOARD_MIGRATION_ORDER} (a different registry, composed separately by `pithy seed`).
+*/
+const LEADERBOARD_EXAMPLE_SEED_ORDER = 200;
+const now = () => /* @__PURE__ */ new Date();
+/**
+* A tiny demo board's worth of entries — the three canonical example users ({@link EXAMPLE_ADA} et al.)
+* on an all-time board named `demo`. The `userId`s are the shared cast from `@pithy-sh/core`, so these
+* scores belong to the same users `auth` seeds and `ledger`/`multiplayer` also reference: `pithy seed`
+* fills a fresh backend with connected data, not isolated rows. Composed in only when the project turns
+* on `seed.includeExamples` (`pithy.config.ts`), and only for `dev` and `staging` — an example fixture
+* never targets production, regardless of that setting.
+*/
+const leaderboardExampleSeed = defineSeed({
+	name: "example",
+	order: LEADERBOARD_EXAMPLE_SEED_ORDER,
+	environments: ["dev", "staging"],
+	example: true,
+	d1: [d1SeedGroup("app", LEADERBOARD_ENTRIES_TABLE, LeaderboardEntry, [
+		{
+			id: 1,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_ADA.id,
+			score: 300,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		},
+		{
+			id: 2,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_GRACE.id,
+			score: 250,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		},
+		{
+			id: 3,
+			boardId: "demo",
+			windowKey: "all",
+			userId: EXAMPLE_ALAN.id,
+			score: 200,
+			achievedAt: now(),
+			submittedAt: now(),
+			visible: true,
+			hidden: false,
+			rank: null
+		}
+	])]
+});
+//#endregion
+export { leaderboardExampleSeed };

package/dist/session/bookmark.d.ts

@@ -0,0 +1,47 @@
+import type { D1Database } from "@cloudflare/workers-types";
+import { type LeaderboardDatabase } from "../data/tables";
+/**
+ * Read-your-own-writes across D1 read replication.
+ *
+ * D1 replicas "may be arbitrarily out of date" and Cloudflare publishes no staleness bound. On a
+ * leaderboard that lands exactly where a player notices: submit a score, read the board, and your own
+ * submission is missing. It reads as a lost write, not as replication lag, and it is the one
+ * inconsistency a ranking product cannot shrug off.
+ *
+ * The D1 Sessions API is the fix. Every query through a session is sequentially consistent with the
+ * session's bookmark, so threading a bookmark from a write to the player's next read guarantees they see
+ * themselves. The bookmark travels on {@link BOOKMARK_HEADER}: responses return the newest one, and a
+ * client echoes it back on the next request.
+ *
+ * The header is safe to expose and safe to ignore. It is an opaque replication watermark, not a
+ * credential — it carries no identity and grants nothing. A client that never echoes it is not broken,
+ * only unprotected against lag; a client that sends a stale or unparseable one is anchored no earlier
+ * than the write it names. Every route is authenticated regardless, so a bookmark cannot widen access.
+ */
+/** The header a bookmark travels on, in both directions. */
+export declare const BOOKMARK_HEADER = "x-pithy-d1-bookmark";
+/**
+ * Where a session with no bookmark starts.
+ *
+ * Writes anchor at the primary — a submission must land there, and the bookmark it returns is what makes
+ * the player's next read see it. Reads with no bookmark are unconstrained and may serve from any replica:
+ * that is the point of replication, and a reader who has not written has nothing of their own to miss.
+ */
+type SessionStart = "first-primary" | "first-unconstrained";
+export interface LeaderboardSession {
+    /** The Kysely database bound to this session. Every query through it is sequentially consistent. */
+    db: LeaderboardDatabase;
+    /** The newest bookmark across this session's queries, or null if it ran none. */
+    bookmark(): string | null;
+}
+/**
+ * Open a D1 session anchored at `bookmark` when the client sent one, or at `start` when it did not.
+ *
+ * An unparseable or expired bookmark is D1's to reject, not ours to pre-validate: it is opaque to us, and
+ * guessing at its shape here would just be a second place to get it wrong.
+ */
+export declare function leaderboardSession(d1: D1Database, bookmark: string | undefined, start: SessionStart): LeaderboardSession;
+/** The bookmark a client echoed back, or undefined. */
+export declare function readBookmark(headers: Headers): string | undefined;
+export {};
+//# sourceMappingURL=bookmark.d.ts.map

package/dist/session/bookmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookmark.d.ts","sourceRoot":"","sources":["../../src/session/bookmark.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,KAAK,mBAAmB,EAAuB,MAAM,gBAAgB,CAAC;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AAEH,4DAA4D;AAC5D,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD;;;;;;GAMG;AACH,KAAK,YAAY,GAAG,eAAe,GAAG,qBAAqB,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,EAAE,EAAE,mBAAmB,CAAC;IACxB,iFAAiF;IACjF,QAAQ,IAAI,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,UAAU,EACd,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,YAAY,GAClB,kBAAkB,CAQpB;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEjE"}

package/dist/session/bookmark.js

@@ -0,0 +1,41 @@
+import { leaderboardDatabase } from "../data/tables.js";
+//#region src/session/bookmark.ts
+/**
+* Read-your-own-writes across D1 read replication.
+*
+* D1 replicas "may be arbitrarily out of date" and Cloudflare publishes no staleness bound. On a
+* leaderboard that lands exactly where a player notices: submit a score, read the board, and your own
+* submission is missing. It reads as a lost write, not as replication lag, and it is the one
+* inconsistency a ranking product cannot shrug off.
+*
+* The D1 Sessions API is the fix. Every query through a session is sequentially consistent with the
+* session's bookmark, so threading a bookmark from a write to the player's next read guarantees they see
+* themselves. The bookmark travels on {@link BOOKMARK_HEADER}: responses return the newest one, and a
+* client echoes it back on the next request.
+*
+* The header is safe to expose and safe to ignore. It is an opaque replication watermark, not a
+* credential — it carries no identity and grants nothing. A client that never echoes it is not broken,
+* only unprotected against lag; a client that sends a stale or unparseable one is anchored no earlier
+* than the write it names. Every route is authenticated regardless, so a bookmark cannot widen access.
+*/
+/** The header a bookmark travels on, in both directions. */
+const BOOKMARK_HEADER = "x-pithy-d1-bookmark";
+/**
+* Open a D1 session anchored at `bookmark` when the client sent one, or at `start` when it did not.
+*
+* An unparseable or expired bookmark is D1's to reject, not ours to pre-validate: it is opaque to us, and
+* guessing at its shape here would just be a second place to get it wrong.
+*/
+function leaderboardSession(d1, bookmark, start) {
+	const session = d1.withSession(bookmark ?? start);
+	return {
+		db: leaderboardDatabase(session),
+		bookmark: () => session.getBookmark()
+	};
+}
+/** The bookmark a client echoed back, or undefined. */
+function readBookmark(headers) {
+	return headers.get("x-pithy-d1-bookmark")?.trim() || void 0;
+}
+//#endregion
+export { BOOKMARK_HEADER, leaderboardSession, readBookmark };

package/dist/version.generated.d.ts

@@ -0,0 +1,5 @@
+/** This package's npm name — the join key against a release feed. */
+export declare const PACKAGE_NAME = "@pithy-sh/leaderboard";
+/** This package's version, stamped from its own package.json at generation time. */
+export declare const PACKAGE_VERSION = "0.1.3";
+//# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.generated.d.ts","sourceRoot":"","sources":["../src/version.generated.ts"],"names":[],"mappings":"AAWA,qEAAqE;AACrE,eAAO,MAAM,YAAY,0BAA0B,CAAC;AAEpD,oFAAoF;AACpF,eAAO,MAAM,eAAe,UAAU,CAAC"}

package/dist/version.generated.js

@@ -0,0 +1,7 @@
+//#region src/version.generated.ts
+/** This package's npm name — the join key against a release feed. */
+const PACKAGE_NAME = "@pithy-sh/leaderboard";
+/** This package's version, stamped from its own package.json at generation time. */
+const PACKAGE_VERSION = "0.1.3";
+//#endregion
+export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/window/schedule.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Window keys. A board's `window` is a CRON expression; the window a score falls into is keyed by the
+ * instant that CRON last fired at or before the score. Omitting the schedule means one all-time window.
+ *
+ * CRON — rather than a fixed `daily|weekly|monthly|all-time` enum — is what lets a board align to the
+ * calendar. Apple caps leaderboard recurrence at 30 days and expresses it as a fixed duration, so a
+ * calendar month (28/29/30/31 days) is not expressible there and a calendar year is impossible; Google
+ * Play Games Services ships daily/weekly/all-time and no monthly at all. `0 0 1 * *` and `0 0 1 1 *`
+ * cost us nothing extra because `rank: { materialize: <cron> }` already needs a parser.
+ *
+ * Every derivation is UTC-anchored. The host's local timezone must never move a window boundary, or the
+ * same submission would key differently on two Workers.
+ */
+/** The window key for a board with no schedule: one window, open forever. */
+export declare const ALL_TIME_WINDOW = "all";
+/**
+ * Validate a board's schedule at config time, so a typo fails at assembly rather than on the first
+ * submission. An expression that parses but never fires (`0 0 30 2 *` — February 30) is rejected too:
+ * it would strand every score with no window to key it to.
+ */
+export declare function assertValidSchedule(schedule: string): void;
+/** The key of the window `at` falls into: the ISO instant the board's CRON last fired at or before it. */
+export declare function windowKeyAt(schedule: string | undefined, at: Date): string;
+/**
+ * The keys of the `count` windows closed behind the one `at` falls into, newest first. Retention prunes
+ * everything older than the last of these.
+ */
+export declare function previousWindowKeys(schedule: string | undefined, at: Date, count: number): string[];
+//# sourceMappingURL=schedule.d.ts.map

package/dist/window/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../../src/window/schedule.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AAEH,6EAA6E;AAC7E,eAAO,MAAM,eAAe,QAAQ,CAAC;AAuDrC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ1D;AAED,0GAA0G;AAC1G,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAS1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAYlG"}

package/dist/window/schedule.js

@@ -0,0 +1,106 @@
+import { LeaderboardInvalidScheduleError } from "../error/errors.js";
+import { Cron } from "croner";
+//#region src/window/schedule.ts
+/**
+* Window keys. A board's `window` is a CRON expression; the window a score falls into is keyed by the
+* instant that CRON last fired at or before the score. Omitting the schedule means one all-time window.
+*
+* CRON — rather than a fixed `daily|weekly|monthly|all-time` enum — is what lets a board align to the
+* calendar. Apple caps leaderboard recurrence at 30 days and expresses it as a fixed duration, so a
+* calendar month (28/29/30/31 days) is not expressible there and a calendar year is impossible; Google
+* Play Games Services ships daily/weekly/all-time and no monthly at all. `0 0 1 * *` and `0 0 1 1 *`
+* cost us nothing extra because `rank: { materialize: <cron> }` already needs a parser.
+*
+* Every derivation is UTC-anchored. The host's local timezone must never move a window boundary, or the
+* same submission would key differently on two Workers.
+*/
+/** The window key for a board with no schedule: one window, open forever. */
+const ALL_TIME_WINDOW = "all";
+/**
+* Lookback rungs for {@link lastFireAtOrBefore}, smallest first.
+*
+* croner can only walk *forward* (`nextRun`); its `previousRun` reports a live job's last execution, not
+* a historical period start, so finding the window a past instant falls into means searching back. The
+* ladder keeps that search cheap for every cadence: a rung is tried only if the finer one found no fire,
+* so a per-minute board settles on the first rung after one step and a yearly board reaches the last rung
+* having walked one. That bounds the forward walk to roughly one period per rung instead of letting a
+* frequent board enumerate a year of fires. The final rung spans four years: `0 0 29 2 *` — a leap-day
+* board — only fires when February has 29 days.
+*/
+const MINUTE_MS = 6e4;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+const LOOKBACK_LADDER_MS = [
+	MINUTE_MS,
+	HOUR_MS,
+	DAY_MS,
+	8 * DAY_MS,
+	40 * DAY_MS,
+	400 * DAY_MS,
+	1500 * DAY_MS
+];
+/** How far ahead {@link assertValidSchedule} looks for a fire before calling an expression dead. */
+const NEVER_FIRES_HORIZON = LOOKBACK_LADDER_MS[LOOKBACK_LADDER_MS.length - 1];
+function compile(schedule) {
+	try {
+		return new Cron(schedule, { timezone: "UTC" });
+	} catch (cause) {
+		throw new LeaderboardInvalidScheduleError({ detail: `Board schedule ${JSON.stringify(schedule)} is not a valid CRON expression.` }, { cause });
+	}
+}
+/**
+* The latest fire at or before `at`, or null if the ladder's deepest rung found none.
+*
+* An instant exactly on a boundary belongs to the window it opens, not the one it closes — hence
+* `<= target` rather than `<`. Off by one here and a score landing precisely on the boundary files into
+* the window that just closed.
+*/
+function lastFireAtOrBefore(cron, at) {
+	const target = at.getTime();
+	for (const lookback of LOOKBACK_LADDER_MS) {
+		let candidate = null;
+		let cursor = cron.nextRun(new Date(target - lookback));
+		while (cursor && cursor.getTime() <= target) {
+			candidate = cursor;
+			cursor = cron.nextRun(cursor);
+		}
+		if (candidate) return candidate;
+	}
+	return null;
+}
+/**
+* Validate a board's schedule at config time, so a typo fails at assembly rather than on the first
+* submission. An expression that parses but never fires (`0 0 30 2 *` — February 30) is rejected too:
+* it would strand every score with no window to key it to.
+*/
+function assertValidSchedule(schedule) {
+	if (!compile(schedule).nextRun(new Date(Date.now() - NEVER_FIRES_HORIZON))) throw new LeaderboardInvalidScheduleError({
+		message: "That board's window schedule never fires.",
+		detail: `Board schedule ${JSON.stringify(schedule)} parses but never fires, so no window could ever open.`
+	});
+}
+/** The key of the window `at` falls into: the ISO instant the board's CRON last fired at or before it. */
+function windowKeyAt(schedule, at) {
+	if (schedule === void 0) return "all";
+	const start = lastFireAtOrBefore(compile(schedule), at);
+	if (!start) throw new LeaderboardInvalidScheduleError({ detail: `Board schedule ${JSON.stringify(schedule)} has no fire at or before ${at.toISOString()}.` });
+	return start.toISOString();
+}
+/**
+* The keys of the `count` windows closed behind the one `at` falls into, newest first. Retention prunes
+* everything older than the last of these.
+*/
+function previousWindowKeys(schedule, at, count) {
+	if (schedule === void 0 || count <= 0) return [];
+	const cron = compile(schedule);
+	const keys = [];
+	let cursor = lastFireAtOrBefore(cron, at);
+	for (let i = 0; i < count; i++) {
+		if (!cursor) break;
+		cursor = lastFireAtOrBefore(cron, /* @__PURE__ */ new Date(cursor.getTime() - 1));
+		if (cursor) keys.push(cursor.toISOString());
+	}
+	return keys;
+}
+//#endregion
+export { ALL_TIME_WINDOW, assertValidSchedule, previousWindowKeys, windowKeyAt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/leaderboard",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -8,20 +8,25 @@
     "directory": "packages/leaderboard"
   },
   "files": [
+    "dist",
     "src",
     "pithy.manifest.json",
     "docs",
-    "!src/**/*.test.*"
+    "!src/**/*.test.*",
+    "!dist/**/*.test.*"
   ],
   "type": "module",
   "engines": {
     "node": ">=22"
   },
   "exports": {
-    "./src/*": "./src/*.ts"
+    "./src/*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",
@@ -33,20 +38,26 @@
   "dependencies": {
     "@cloudflare/workers-types": "^5.20260729.1",
     "@hono/zod-validator": "^0.9.0",
-    "@pithy-sh/core": "^0.1.2",
-    "croner": "^10.0.1",
-    "hono": "^4.13.2",
-    "kysely": "^0.29.0",
-    "zod": "^4.0.0"
+    "@pithy-sh/core": "^0.1.3",
+    "croner": "^10.0.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.0.0",
     "@pithy-sh/tsconfig": "workspace:*",
     "@types/node": "^22.15.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
     "kysely-d1": "^0.4.0",
+    "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.0",
-    "wrangler": "^4.115.0"
+    "wrangler": "^4.115.0",
+    "zod": "^4.4.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.4.0"
   }
 }

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/leaderboard";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.1.2";
+export const PACKAGE_VERSION = "0.1.3";