@rexezuge/shared 0.0.0-stage → 1.0.1

package/dist/SubrequestMeter.d.ts

@@ -0,0 +1,204 @@
+/**
+ * What one Worker invocation may spend, counted.
+ *
+ * ## Provenance
+ *
+ * Taken from Edge-Sonic's `packages/shared/src/utils/SubrequestMeter.ts`. It is
+ * the only subrequest-accounting helper among the nine repos and the most
+ * heavily measured; it is reproduced with its code unchanged and its prose
+ * generalised away from Edge-Sonic's own layer names and issue docs. No other
+ * repo carries a competing copy.
+ *
+ * ### Why this exists at all
+ *
+ * Cloudflare counts a **subrequest** per invocation and kills the invocation when
+ * the count is exceeded — it does not throw something a `catch` can see, so the
+ * whole invocation dies with `Too many subrequests by single Worker invocation`
+ * and everything after the ceiling is lost. The only defence is to never issue the
+ * request that crosses it.
+ *
+ * A subrequest is not only `fetch`. The platform's own D1 limits page states:
+ *
+ * > Queries per Worker invocation (read subrequest limits) — 1000 (Workers Paid) / **50 (Free)**
+ *
+ * So a D1 query is a subrequest, and on the Free plan a `KV` read, a Durable
+ * Object RPC and a Secrets Store read are subrequests too. Budgeting **only**
+ * `fetch` shipped a real bug: a scan chunk cost ~40 counted requests and ~200
+ * uncounted ones, every chunk died at the ceiling, and the scan only ever
+ * "finished" because each dead invocation left a little progress behind.
+ *
+ * ### Why the count is pessimistic
+ *
+ * The platform does not say whether a D1 `batch()` of N statements costs 1 or N.
+ * The D1 page counts *queries*, which reads as N; the Workers page counts
+ * subrequests, which reads as 1. So the meter charges **one per statement**, which
+ * is the reading that cannot kill an invocation. If the friendlier reading turns
+ * out to be right, the meter over-counts and a chunk does slightly less work per
+ * poll — a cost in throughput, never a correctness or availability problem. That
+ * asymmetry is the whole reason to choose it: an over-count is a slow scan, an
+ * under-count is a dead one.
+ *
+ * Measured on a Free account on 2026-10-05 there are two budgets: external `fetch`
+ * is 50 and **D1 statements are 1,000**, in a separate pool — 1,000 D1 statements
+ * and 50 outbound requests in one invocation survive together. A D1 overrun
+ * *throws* and an ordinary `catch` sees it; the external ceiling does not. This
+ * counter's single ceiling covers both, which is the conservative choice: bounding
+ * both by the resource that cannot be handled when it runs out is the choice that
+ * cannot take the product down. That is not a licence to catch and continue — a
+ * swallowed limit is still a limit.
+ *
+ * ### Why it is an interface and not a class everywhere
+ *
+ * Charge points below the layer that decides the budget accept the **interface**
+ * as a constructor dependency, and the composition root hands them the one counter
+ * for the invocation. Nothing that only spends subrequests constructs a meter.
+ */
+/**
+ * What spent the subrequests, for the operator-facing breakdown.
+ *
+ * `d1` is separated from `kv` and `fetch` because the three have different
+ * remedies: a chunk that ran out on `fetch` needs a bigger request budget on a
+ * Paid plan, and one that ran out on `d1` needs a smaller page size. Collapsing
+ * them into a single number is how the ceiling became invisible in the first
+ * place.
+ */
+type SubrequestKind = 'd1' | 'kv' | 'fetch' | 'rpc' | 'secret';
+declare const SUBREQUEST_KINDS: readonly SubrequestKind[];
+/**
+ * The counter every charge point writes to.
+ *
+ * A method rather than a mutable field so a charge point can be handed the
+ * *interface* and the test that owns the ceiling keeps the only real instance.
+ * `charge` is the whole write surface; `spent` and `byKind` are the only read
+ * surface a charge point needs.
+ */
+interface SubrequestMeter {
+    /**
+     * Record `count` subrequests issued.
+     *
+     * Never throws and never refuses. A meter that could reject would turn "the
+     * budget ran out" into an error at a charge point deep inside a DAO, which is
+     * the one place that cannot afford to decide anything — the decision belongs
+     * *before* the work, in `canAfford`.
+     */
+    charge(count?: number, kind?: SubrequestKind): void;
+    /**
+     * Subrequests issued so far in this invocation.
+     */
+    readonly spent: number;
+    /**
+     * The ceiling this counter enforces, or `Infinity` when it enforces none.
+     */
+    readonly ceiling: number;
+    /**
+     * How many more fit, floored at zero.
+     */
+    readonly remaining: number;
+    /**
+     * Whether the ceiling has been reached.
+     */
+    readonly exhausted: boolean;
+    /**
+     * Whether `count` more would still fit.
+     */
+    canAfford(count?: number): boolean;
+    /**
+     * Lower this meter's effective ceiling for the current unit of work. Never
+     * raises it — a narrower budget may only tighten the platform's ceiling, so a
+     * caller asking for more than the platform allows is clamped rather than
+     * trusted. The same asymmetry as everywhere else here: an over-count costs
+     * throughput, an under-count costs an invocation.
+     */
+    setCeiling(limit: number): void;
+}
+/**
+ * One counter per Worker invocation.
+ *
+ * `reset()` rather than a fresh instance per chunk because the counter is owned by
+ * the **request scope**, which is created once per invocation: a chunk does not own
+ * the budget, it borrows the invocation's. Constructing a new counter per chunk
+ * would be a second place that decides what the ceiling is.
+ */
+declare class SubrequestCounter implements SubrequestMeter {
+    private readonly limit;
+    private counts;
+    /**
+     * Spend per kind, so a result can report *what* ran out rather than only that
+     * something did. A single total is what made this ceiling un-diagnosable: the
+     * operator saw "paused" and the possible causes have different fixes.
+     */
+    private readonly byKindSpent;
+    /**
+     * The platform's ceiling, or a narrower one `setCeiling` imposed for the current
+     * unit of work. Restored to `limit` by `reset()`, so a narrowed ceiling cannot
+     * leak past the chunk that asked for it.
+     */
+    private effective;
+    constructor(limit?: number);
+    charge(count?: number, kind?: SubrequestKind): void;
+    get spent(): number;
+    /**
+     * The **effective** ceiling: the platform's, or a narrower one a caller imposed.
+     */
+    get ceiling(): number;
+    get remaining(): number;
+    get exhausted(): boolean;
+    canAfford(count?: number): boolean;
+    setCeiling(limit: number): void;
+    /**
+     * Zero the count and restore the platform's ceiling.
+     *
+     * One method rather than a public `counts` field so "start measuring again" is a
+     * named operation, and so the per-kind breakdown cannot drift out of step with
+     * the total — exactly the kind of second-answer defect this file exists to
+     * prevent. The ceiling is **restored**, not kept: a narrowed ceiling belongs to
+     * the unit of work that asked for it.
+     */
+    reset(): void;
+    /**
+     * Spend per kind, as a plain object. A copy, so a caller cannot reach in and
+     * change the totals the operator is shown.
+     */
+    breakdown(): Record<SubrequestKind, number>;
+}
+/**
+ * A meter that enforces nothing, for a caller that has not been given one.
+ *
+ * `Infinity` rather than a small number, because the alternative is a default
+ * ceiling that a test would satisfy by accident — the failure this file is about
+ * is a path that spends nothing because nothing was watching it, and a limit of 50
+ * would hide that behind a passing assertion.
+ */
+declare const UNMETERED_SUBREQUESTS: SubrequestMeter;
+/**
+ * What an invocation spent, broken down.
+ *
+ * A total alone is what made this ceiling undiagnosable. An operator whose scan
+ * keeps pausing was told "paused" and nothing else, while the causes have
+ * different fixes.
+ */
+interface SubrequestSpend extends Record<SubrequestKind, number> {
+    /**
+     * Every subrequest spent, whatever its kind. The number the ceiling is enforced
+     * against.
+     */
+    readonly total: number;
+}
+/**
+ * Flatten a meter's breakdown into a report, total included.
+ *
+ * A function rather than a method on the counter so the *shape* the rest of the
+ * system passes around — including the zeroes for kinds that spent nothing — is
+ * built in one place. A caller that assembled it by hand would omit an absent kind,
+ * and the operator surface would render a missing field as a missing measurement
+ * rather than as `0`.
+ */
+declare function subrequestSpend(byKind: Record<SubrequestKind, number>, total: number): SubrequestSpend;
+/**
+ * Nothing spent, for a code path that did no work — so a zero report is a
+ * *measurement* rather than an absent field.
+ */
+declare const NO_SUBREQUESTS_SPENT: SubrequestSpend;
+export { SubrequestCounter, UNMETERED_SUBREQUESTS, SUBREQUEST_KINDS, subrequestSpend, NO_SUBREQUESTS_SPENT };
+export type { SubrequestMeter, SubrequestKind, SubrequestSpend };
+//# sourceMappingURL=SubrequestMeter.d.ts.map

package/dist/SubrequestMeter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubrequestMeter.d.ts","sourceRoot":"","sources":["../src/SubrequestMeter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH;;;;;;;;GAQG;AACH,KAAK,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE/D,QAAA,MAAM,gBAAgB,EAAE,SAAS,cAAc,EAA2C,CAAC;AAE3F;;;;;;;GAOG;AACH,UAAU,eAAe;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACpD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,cAAM,iBAAkB,YAAW,eAAe;IAgBpC,OAAO,CAAC,QAAQ,CAAC,KAAK;IAflC,OAAO,CAAC,MAAM,CAAa;IAE3B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiF;IAC7G;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAS;gBAEG,KAAK,GAAE,MAAiB;IAI9C,MAAM,CAAC,KAAK,SAAI,EAAE,IAAI,GAAE,cAAqB,GAAG,IAAI;IAM3D,IAAW,KAAK,IAAI,MAAM,CAEzB;IAED;;OAEG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED,IAAW,SAAS,IAAI,MAAM,CAG7B;IAED,IAAW,SAAS,IAAI,OAAO,CAE9B;IAEM,SAAS,CAAC,KAAK,SAAI,GAAG,OAAO;IAI7B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAStC;;;;;;;;OAQG;IACI,KAAK,IAAI,IAAI;IAMpB;;;OAGG;IACI,SAAS,IAAI,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC;CAGnD;AAED;;;;;;;GAOG;AACH,QAAA,MAAM,qBAAqB,EAAE,eAAiD,CAAC;AAE/E;;;;;;GAMG;AACH,UAAU,eAAgB,SAAQ,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC;IAC9D;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,iBAAS,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAE/F;AAED;;;GAGG;AACH,QAAA,MAAM,oBAAoB,EAAE,eAAmF,CAAC;AAEhH,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,CAAC;AAC7G,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/SubrequestMeter.js

@@ -0,0 +1,169 @@
+/**
+ * What one Worker invocation may spend, counted.
+ *
+ * ## Provenance
+ *
+ * Taken from Edge-Sonic's `packages/shared/src/utils/SubrequestMeter.ts`. It is
+ * the only subrequest-accounting helper among the nine repos and the most
+ * heavily measured; it is reproduced with its code unchanged and its prose
+ * generalised away from Edge-Sonic's own layer names and issue docs. No other
+ * repo carries a competing copy.
+ *
+ * ### Why this exists at all
+ *
+ * Cloudflare counts a **subrequest** per invocation and kills the invocation when
+ * the count is exceeded — it does not throw something a `catch` can see, so the
+ * whole invocation dies with `Too many subrequests by single Worker invocation`
+ * and everything after the ceiling is lost. The only defence is to never issue the
+ * request that crosses it.
+ *
+ * A subrequest is not only `fetch`. The platform's own D1 limits page states:
+ *
+ * > Queries per Worker invocation (read subrequest limits) — 1000 (Workers Paid) / **50 (Free)**
+ *
+ * So a D1 query is a subrequest, and on the Free plan a `KV` read, a Durable
+ * Object RPC and a Secrets Store read are subrequests too. Budgeting **only**
+ * `fetch` shipped a real bug: a scan chunk cost ~40 counted requests and ~200
+ * uncounted ones, every chunk died at the ceiling, and the scan only ever
+ * "finished" because each dead invocation left a little progress behind.
+ *
+ * ### Why the count is pessimistic
+ *
+ * The platform does not say whether a D1 `batch()` of N statements costs 1 or N.
+ * The D1 page counts *queries*, which reads as N; the Workers page counts
+ * subrequests, which reads as 1. So the meter charges **one per statement**, which
+ * is the reading that cannot kill an invocation. If the friendlier reading turns
+ * out to be right, the meter over-counts and a chunk does slightly less work per
+ * poll — a cost in throughput, never a correctness or availability problem. That
+ * asymmetry is the whole reason to choose it: an over-count is a slow scan, an
+ * under-count is a dead one.
+ *
+ * Measured on a Free account on 2026-10-05 there are two budgets: external `fetch`
+ * is 50 and **D1 statements are 1,000**, in a separate pool — 1,000 D1 statements
+ * and 50 outbound requests in one invocation survive together. A D1 overrun
+ * *throws* and an ordinary `catch` sees it; the external ceiling does not. This
+ * counter's single ceiling covers both, which is the conservative choice: bounding
+ * both by the resource that cannot be handled when it runs out is the choice that
+ * cannot take the product down. That is not a licence to catch and continue — a
+ * swallowed limit is still a limit.
+ *
+ * ### Why it is an interface and not a class everywhere
+ *
+ * Charge points below the layer that decides the budget accept the **interface**
+ * as a constructor dependency, and the composition root hands them the one counter
+ * for the invocation. Nothing that only spends subrequests constructs a meter.
+ */
+const SUBREQUEST_KINDS = ['d1', 'kv', 'fetch', 'rpc', 'secret'];
+/**
+ * One counter per Worker invocation.
+ *
+ * `reset()` rather than a fresh instance per chunk because the counter is owned by
+ * the **request scope**, which is created once per invocation: a chunk does not own
+ * the budget, it borrows the invocation's. Constructing a new counter per chunk
+ * would be a second place that decides what the ceiling is.
+ */
+class SubrequestCounter {
+    limit;
+    counts = 0;
+    /**
+     * Spend per kind, so a result can report *what* ran out rather than only that
+     * something did. A single total is what made this ceiling un-diagnosable: the
+     * operator saw "paused" and the possible causes have different fixes.
+     */
+    byKindSpent = { d1: 0, kv: 0, fetch: 0, rpc: 0, secret: 0 };
+    /**
+     * The platform's ceiling, or a narrower one `setCeiling` imposed for the current
+     * unit of work. Restored to `limit` by `reset()`, so a narrowed ceiling cannot
+     * leak past the chunk that asked for it.
+     */
+    effective;
+    constructor(limit = Infinity) {
+        this.limit = limit;
+        this.effective = limit;
+    }
+    charge(count = 1, kind = 'd1') {
+        if (count <= 0)
+            return;
+        this.counts += count;
+        this.byKindSpent[kind] += count;
+    }
+    get spent() {
+        return this.counts;
+    }
+    /**
+     * The **effective** ceiling: the platform's, or a narrower one a caller imposed.
+     */
+    get ceiling() {
+        return this.effective;
+    }
+    get remaining() {
+        if (this.effective === Infinity)
+            return Infinity;
+        return Math.max(0, this.effective - this.counts);
+    }
+    get exhausted() {
+        return this.counts >= this.effective;
+    }
+    canAfford(count = 1) {
+        return this.counts + count <= this.effective;
+    }
+    setCeiling(limit) {
+        // An unmetered counter stays unmetered: a ceiling of `Infinity` cannot be
+        // lowered to a finite one, because the callers that would impose one are the
+        // *production* ones and a test double asking for a bound must not start
+        // refusing statements.
+        if (!Number.isFinite(this.effective) || !Number.isFinite(limit))
+            return;
+        this.effective = Math.max(0, Math.min(this.effective, Math.floor(limit)));
+    }
+    /**
+     * Zero the count and restore the platform's ceiling.
+     *
+     * One method rather than a public `counts` field so "start measuring again" is a
+     * named operation, and so the per-kind breakdown cannot drift out of step with
+     * the total — exactly the kind of second-answer defect this file exists to
+     * prevent. The ceiling is **restored**, not kept: a narrowed ceiling belongs to
+     * the unit of work that asked for it.
+     */
+    reset() {
+        this.counts = 0;
+        this.effective = this.limit;
+        for (const kind of SUBREQUEST_KINDS)
+            this.byKindSpent[kind] = 0;
+    }
+    /**
+     * Spend per kind, as a plain object. A copy, so a caller cannot reach in and
+     * change the totals the operator is shown.
+     */
+    breakdown() {
+        return { ...this.byKindSpent };
+    }
+}
+/**
+ * A meter that enforces nothing, for a caller that has not been given one.
+ *
+ * `Infinity` rather than a small number, because the alternative is a default
+ * ceiling that a test would satisfy by accident — the failure this file is about
+ * is a path that spends nothing because nothing was watching it, and a limit of 50
+ * would hide that behind a passing assertion.
+ */
+const UNMETERED_SUBREQUESTS = new SubrequestCounter(Infinity);
+/**
+ * Flatten a meter's breakdown into a report, total included.
+ *
+ * A function rather than a method on the counter so the *shape* the rest of the
+ * system passes around — including the zeroes for kinds that spent nothing — is
+ * built in one place. A caller that assembled it by hand would omit an absent kind,
+ * and the operator surface would render a missing field as a missing measurement
+ * rather than as `0`.
+ */
+function subrequestSpend(byKind, total) {
+    return { total, d1: byKind.d1, kv: byKind.kv, fetch: byKind.fetch, rpc: byKind.rpc, secret: byKind.secret };
+}
+/**
+ * Nothing spent, for a code path that did no work — so a zero report is a
+ * *measurement* rather than an absent field.
+ */
+const NO_SUBREQUESTS_SPENT = subrequestSpend({ d1: 0, kv: 0, fetch: 0, rpc: 0, secret: 0 }, 0);
+export { SubrequestCounter, UNMETERED_SUBREQUESTS, SUBREQUEST_KINDS, subrequestSpend, NO_SUBREQUESTS_SPENT };
+//# sourceMappingURL=SubrequestMeter.js.map

package/dist/SubrequestMeter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubrequestMeter.js","sourceRoot":"","sources":["../src/SubrequestMeter.ts"],"names":[],"mappings":"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"}

package/dist/TimeZoneUtil.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Time-zone validation and wall-clock helpers.
+ *
+ * ## Provenance
+ *
+ * Taken from Mail-Otter's `TimeZoneUtil.ts` (the only repo that factored the
+ * zone-local day start behind a helper). It is well-documented and IANA-correct;
+ * no other repo carries a competing copy, so it is kept with one fix.
+ *
+ * ## Design decision
+ *
+ * Mail-Otter's `normalize` used `this.isValid(timeZone) ? (timeZone as string).trim() : …`,
+ * a type-cast to paper over the fact that `isValid` returns `boolean` and so
+ * does not narrow `string | null | undefined`. The kit bans that pattern (no
+ * non-null assertions, no `as`-laundering), so the runtime check is a module-level
+ * **type guard** and `normalize` runs on the narrowed value. Same behaviour, no
+ * cast.
+ *
+ * `getLocalDayStartUnixSeconds` keeps the two-pass DST handling and the warning
+ * not to build it with `new Date('YYYY-MM-DDT00:00:00')` — a zone-less date-time
+ * string parses in the runtime's zone, which is always UTC in Workers, silently
+ * ignoring `timeZone` entirely.
+ */
+declare const DEFAULT_TIME_ZONE = "UTC";
+declare class TimeZoneUtil {
+    static isValid(timeZone: string | null | undefined): boolean;
+    static normalize(timeZone: string | null | undefined): string;
+    static todayInZone(timeZone: string | null | undefined, now?: Date): string;
+    /**
+     * Unix seconds of local midnight for the calendar day containing `now`.
+     *
+     * Two passes are needed because the zone offset depends on the instant: read
+     * the wall clock in the target zone, treat that as UTC to derive the offset,
+     * then re-anchor local midnight with the offset. The offset is sampled at
+     * `now` rather than at the target midnight, which is exact except within a
+     * few hours of a DST transition — irrelevant for a 24-hour window.
+     *
+     * Do NOT build this with `new Date('YYYY-MM-DDT00:00:00')`. A date-time
+     * string with no zone designator parses in the *runtime's* zone, and the
+     * Workers runtime is always UTC, which silently ignores `timeZone` entirely.
+     *
+     * An unknown zone falls back to UTC rather than throwing.
+     */
+    static getLocalDayStartUnixSeconds(now: Date, timeZone: string | null | undefined): number;
+}
+export { TimeZoneUtil, DEFAULT_TIME_ZONE };
+//# sourceMappingURL=TimeZoneUtil.d.ts.map

package/dist/TimeZoneUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeZoneUtil.d.ts","sourceRoot":"","sources":["../src/TimeZoneUtil.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,QAAA,MAAM,iBAAiB,QAAQ,CAAC;AAkChC,cAAM,YAAY;WACF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;WAIrD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM;WAItD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM;IAK9F;;;;;;;;;;;;;;OAcG;WACW,2BAA2B,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM;CAelG;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/TimeZoneUtil.js

@@ -0,0 +1,101 @@
+/**
+ * Time-zone validation and wall-clock helpers.
+ *
+ * ## Provenance
+ *
+ * Taken from Mail-Otter's `TimeZoneUtil.ts` (the only repo that factored the
+ * zone-local day start behind a helper). It is well-documented and IANA-correct;
+ * no other repo carries a competing copy, so it is kept with one fix.
+ *
+ * ## Design decision
+ *
+ * Mail-Otter's `normalize` used `this.isValid(timeZone) ? (timeZone as string).trim() : …`,
+ * a type-cast to paper over the fact that `isValid` returns `boolean` and so
+ * does not narrow `string | null | undefined`. The kit bans that pattern (no
+ * non-null assertions, no `as`-laundering), so the runtime check is a module-level
+ * **type guard** and `normalize` runs on the narrowed value. Same behaviour, no
+ * cast.
+ *
+ * `getLocalDayStartUnixSeconds` keeps the two-pass DST handling and the warning
+ * not to build it with `new Date('YYYY-MM-DDT00:00:00')` — a zone-less date-time
+ * string parses in the runtime's zone, which is always UTC in Workers, silently
+ * ignoring `timeZone` entirely.
+ */
+const DEFAULT_TIME_ZONE = 'UTC';
+const WALL_CLOCK_FORMAT = {
+    hour12: false,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+};
+/**
+ * A run-time check that narrows to `string`, so callers do not have to cast.
+ *
+ * `new Intl.DateTimeFormat` throws a `RangeError` on an unknown zone; the guard
+ * catches it and answers `false` for `null`/`undefined`/non-strings in one place.
+ */
+function isTimeZoneString(value) {
+    if (!value || typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return false;
+    // Trim-then-validate, so `normalize`'s `.trim()` is load-bearing: Mail-Otter's
+    // guard validated the *untrimmed* string, so a whitespace-padded IANA zone
+    // threw in `Intl` and silently fell back to UTC. A padded zone is a typo, not an
+    // unknown zone, so it is trimmed and accepted rather than defaulted.
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: trimmed });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+class TimeZoneUtil {
+    static isValid(timeZone) {
+        return isTimeZoneString(timeZone);
+    }
+    static normalize(timeZone) {
+        return isTimeZoneString(timeZone) ? timeZone.trim() : DEFAULT_TIME_ZONE;
+    }
+    static todayInZone(timeZone, now = new Date()) {
+        const zone = this.normalize(timeZone);
+        return new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now);
+    }
+    /**
+     * Unix seconds of local midnight for the calendar day containing `now`.
+     *
+     * Two passes are needed because the zone offset depends on the instant: read
+     * the wall clock in the target zone, treat that as UTC to derive the offset,
+     * then re-anchor local midnight with the offset. The offset is sampled at
+     * `now` rather than at the target midnight, which is exact except within a
+     * few hours of a DST transition — irrelevant for a 24-hour window.
+     *
+     * Do NOT build this with `new Date('YYYY-MM-DDT00:00:00')`. A date-time
+     * string with no zone designator parses in the *runtime's* zone, and the
+     * Workers runtime is always UTC, which silently ignores `timeZone` entirely.
+     *
+     * An unknown zone falls back to UTC rather than throwing.
+     */
+    static getLocalDayStartUnixSeconds(now, timeZone) {
+        const zone = this.normalize(timeZone);
+        const parts = new Intl.DateTimeFormat('en-CA', { timeZone: zone, ...WALL_CLOCK_FORMAT }).formatToParts(now);
+        const part = (type) => parts.find((p) => p.type === type)?.value ?? '0';
+        const year = Number(part('year'));
+        const month = Number(part('month'));
+        const day = Number(part('day'));
+        // Some ICU builds report midnight as hour 24 under `hour12: false`.
+        const hour = Number(part('hour')) % 24;
+        const minute = Number(part('minute'));
+        const second = Number(part('second'));
+        const wallClockAsUtcMs = Date.UTC(year, month - 1, day, hour, minute, second);
+        const zoneOffsetMs = wallClockAsUtcMs - now.getTime();
+        return Math.floor((Date.UTC(year, month - 1, day, 0, 0, 0) - zoneOffsetMs) / 1000);
+    }
+}
+export { TimeZoneUtil, DEFAULT_TIME_ZONE };
+//# sourceMappingURL=TimeZoneUtil.js.map

package/dist/TimeZoneUtil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimeZoneUtil.js","sourceRoot":"","sources":["../src/TimeZoneUtil.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEhC,MAAM,iBAAiB,GAA+B;IACpD,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,GAAG,EAAE,SAAS;IACd,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAgC;IACxD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACjC,+EAA+E;IAC/E,2EAA2E;IAC3E,iFAAiF;IACjF,qEAAqE;IACrE,IAAI,CAAC;QACH,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,YAAY;IACT,MAAM,CAAC,OAAO,CAAC,QAAmC;QACvD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAEM,MAAM,CAAC,SAAS,CAAC,QAAmC;QACzD,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;IAC1E,CAAC;IAEM,MAAM,CAAC,WAAW,CAAC,QAAmC,EAAE,MAAY,IAAI,IAAI,EAAE;QACnF,MAAM,IAAI,GAAW,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC9C,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7H,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACI,MAAM,CAAC,2BAA2B,CAAC,GAAS,EAAE,QAAmC;QACtF,MAAM,IAAI,GAAW,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5G,MAAM,IAAI,GAAG,CAAC,IAAkC,EAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,GAAG,CAAC;QAC9G,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAChC,oEAAoE;QACpE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC;QACvC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,MAAM,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9E,MAAM,YAAY,GAAG,gBAAgB,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;QACtD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;IACrF,CAAC;CACF;AAED,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/TimestampUtil.d.ts

@@ -0,0 +1,53 @@
+import { type Clock } from './Clock';
+/**
+ * Unix timestamps, in seconds and milliseconds.
+ *
+ * ## Provenance
+ *
+ * Converged from all nine `TimestampUtil.ts` copies. They fall into three
+ * shapes: Durable-DAV's minimal two-method set (`getCurrentUnixTimestampInSeconds`
+ * + `addDays`) with a deliberate "seconds everywhere" argument; AWS's compact set
+ * plus an **injectable `Clock`** on the current-time readers; and the full
+ * ChordDHT/Mail-Otter set (`…InMilliseconds`, `addMinutes`, `addHours`,
+ * `subtractMinutes`, `subtractDays`, `convertIso…`) reading `Date.now()` directly.
+ *
+ * ## Design decisions
+ *
+ * - The **full method set** is kept: the union of the three shapes loses nothing
+ *   and each method exists because at least two repos independently reached for
+ *   it.
+ * - The current-time reads go through an **injectable `Clock`** defaulting to
+ *   `SYSTEM_CLOCK` (AWS's shape). Reading the clock through one seam lets a test
+ *   pin "now" without racing `Date.now()`, and a caller cannot accidentally store
+ *   milliseconds in a column compared against seconds.
+ * - Seconds is the storage unit (Durable-DAV's argument): where millisecond
+ *   precision is genuinely wanted — ordering within a single pass — reach for
+ *   `…InMilliseconds` (or `clock.now()`) explicitly, so the unit is visible at the
+ *   call site. `add*`/`subtract*` operate on the **second** unit and are pure
+ *   calendar arithmetic, never `Date` arithmetic, so they cannot pick up a
+ *   timezone or a DST transition.
+ */
+declare class TimestampUtil {
+    /**
+     * Now, in whole milliseconds.
+     *
+     * @param clock Inject a `FixedClock` to pin "now" in a test; production leaves
+     * it defaulted.
+     */
+    static getCurrentUnixTimestampInMilliseconds(clock?: Clock): number;
+    /**
+     * Now, in whole seconds. The default storage unit.
+     *
+     * @param clock Inject a `FixedClock` to pin "now" in a test; production leaves
+     * it defaulted.
+     */
+    static getCurrentUnixTimestampInSeconds(clock?: Clock): number;
+    static addMinutes(timestamp: number, minutes: number): number;
+    static addHours(timestamp: number, hours: number): number;
+    static addDays(timestamp: number, days: number): number;
+    static subtractMinutes(timestamp: number, minutes: number): number;
+    static subtractDays(timestamp: number, days: number): number;
+    static convertIsoToUnixTimestampInSeconds(isoString: string): number;
+}
+export { TimestampUtil };
+//# sourceMappingURL=TimestampUtil.d.ts.map

package/dist/TimestampUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TimestampUtil.d.ts","sourceRoot":"","sources":["../src/TimestampUtil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,cAAM,aAAa;IACjB;;;;;OAKG;WACW,qCAAqC,CAAC,KAAK,GAAE,KAAoB,GAAG,MAAM;IAIxF;;;;;OAKG;WACW,gCAAgC,CAAC,KAAK,GAAE,KAAoB,GAAG,MAAM;WAIrE,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;WAItD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;WAIlD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;WAIhD,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;WAI3D,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;WAIrD,kCAAkC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAG5E;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}