slotlock 0.6.2 → 0.7.0

package/teams.d.ts

@@ -0,0 +1,25 @@
+import type { SlotlockSql } from './store.js';
+/** What the dashboard reads and changes of the organizations turned on (SLOTLOCK_DASHBOARD_ORGS=enabled). */
+export interface SlotlockDashboardTeams {
+    /** Of these organization ids, the ones turned on. */
+    enabled(ids: readonly string[]): Promise<ReadonlySet<string>>;
+    /** Turn Slotlock on for an organization, by an owner of it (`github:<id>`). True when it was off. */
+    enable(org: {
+        id: string;
+        login: string;
+    }, by: string): Promise<boolean>;
+    /** Turn it off: its keys stop at once, and its data stay. True when it was on. */
+    disable(id: string, by: string): Promise<boolean>;
+}
+/** The organizations turned on, through slotlock.enabled_organizations and its two writers. */
+export declare function createSlotlockDashboardTeams(sql: SlotlockSql): SlotlockDashboardTeams;
+/**
+ * Whether an organization is turned on, for `serve`'s keys with SLOTLOCK_DASHBOARD_ORGS=enabled:
+ * read through slotlock.enabled_organizations and kept for `ttlMs` (30 seconds), so turning one off
+ * stops its keys on every server within that, without a query per request.
+ */
+export declare function createSlotlockOrganizationCheck(sql: SlotlockSql, options?: {
+    ttlMs?: number;
+    now?: () => number;
+    maxEntries?: number;
+}): (orgId: string) => Promise<boolean>;

package/teams.js

@@ -0,0 +1,63 @@
+const ORGANIZATION_ID = /^[1-9]\d{0,19}$/;
+const GITHUB_LOGIN = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}$/;
+const PERSON = /^github:[1-9]\d{0,19}$/;
+function refuse(message) {
+    throw Object.assign(new Error(`Slotlock organizations: ${message}`), { code: 'invalid_organization' });
+}
+/** The organizations turned on, through slotlock.enabled_organizations and its two writers. */
+export function createSlotlockDashboardTeams(sql) {
+    return {
+        async enabled(ids) {
+            const valid = ids.filter((id) => ORGANIZATION_ID.test(id));
+            if (valid.length === 0)
+                return new Set();
+            const rows = await sql `
+        SELECT org_id FROM slotlock.enabled_organizations(${valid.join(',')}::text) AS org_id`;
+            return new Set(rows.map((row) => row.org_id));
+        },
+        async enable(org, by) {
+            if (!ORGANIZATION_ID.test(org.id) || !GITHUB_LOGIN.test(org.login) || !PERSON.test(by)) {
+                refuse('needs an organization id, its login and the person turning it on');
+            }
+            const [row] = await sql `
+        SELECT slotlock.enable_organization(${org.id}::text, ${org.login}::text, ${by}::text) AS changed`;
+            return row?.changed === true;
+        },
+        async disable(id, by) {
+            if (!ORGANIZATION_ID.test(id) || !PERSON.test(by))
+                refuse('needs an organization id and the person turning it off');
+            const [row] = await sql `
+        SELECT slotlock.disable_organization(${id}::text, ${by}::text) AS changed`;
+            return row?.changed === true;
+        },
+    };
+}
+/**
+ * Whether an organization is turned on, for `serve`'s keys with SLOTLOCK_DASHBOARD_ORGS=enabled:
+ * read through slotlock.enabled_organizations and kept for `ttlMs` (30 seconds), so turning one off
+ * stops its keys on every server within that, without a query per request.
+ */
+export function createSlotlockOrganizationCheck(sql, options = {}) {
+    const ttlMs = options.ttlMs ?? 30_000;
+    const now = options.now ?? Date.now;
+    const maxEntries = options.maxEntries ?? 10_000;
+    const known = new Map();
+    const teams = createSlotlockDashboardTeams(sql);
+    return (orgId) => {
+        if (!ORGANIZATION_ID.test(orgId))
+            return Promise.resolve(false);
+        const cached = known.get(orgId);
+        if (cached && now() - cached.at < ttlMs)
+            return cached.enabled;
+        const enabled = teams.enabled([orgId]).then((found) => found.has(orgId), (error) => {
+            // A failed read is not remembered: the next request asks again.
+            known.delete(orgId);
+            throw error;
+        });
+        known.delete(orgId);
+        known.set(orgId, { at: now(), enabled });
+        if (known.size > maxEntries)
+            known.delete(known.keys().next().value);
+        return enabled;
+    };
+}

package/timezone.d.ts

@@ -8,9 +8,8 @@ export interface LocalDateTime {
     millisecond?: number;
 }
 /**
- * Which instant a wall time names where the clocks change. RFC 5545 §3.3.5 reads a time in a fold
- * (an hour the clocks repeat) as its first instant, and a time in a gap (an hour they skip) with the
- * offset in force before the gap, which moves it forward by the gap: the defaults.
+ * Which instant a wall time names where the clocks change. RFC 5545 §3.3.5 defaults: a fold
+ * (repeated hour) reads as its first instant, a gap (skipped hour) is moved forward by the gap.
  */
 export interface WallTimeChoice {
     /** In a fold: the earlier instant (default), or the later one. */
@@ -20,45 +19,41 @@ export interface WallTimeChoice {
 }
 export interface TimeZoneConverter {
     /**
-     * Convert UTC-framed wall-clock fields to the instant that reads as those fields in this zone.
-     * By default the first instant for a fold, and shifted forward by the gap for a hole.
+     * UTC-framed wall-clock fields to the instant that reads as them in this zone (WallTimeChoice
+     * defaults).
      */
     wallFrameToUtc(wallFrameMs: number, choice?: WallTimeChoice): Date;
 }
 /**
- * The instant, in ms, that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone whose
- * offset at an instant `offsetAt` gives, in ms. The offsets in force within fourteen hours either
- * side are the candidates (no zone is further than that from UTC, so they include both sides of any
- * change the wall time is near); one that maps back to the wall time names it. Two do in a fold,
- * none in a gap, where the offset before the gap is the smaller one.
+ * The instant (ms) that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone with
+ * offsets from `offsetAt`. Candidates are the offsets within fourteen hours either side (no zone is
+ * further from UTC); one that maps back names it. Two do in a fold, none in a gap.
  */
 export declare function wallFrameToInstant(wallFrameMs: number, offsetAt: (utcMs: number) => number, choice?: WallTimeChoice): number;
 /**
- * Date.UTC remaps years 0..99 to 1900..1999. Slotlock accepts ISO calendar years down to 1,
- * so construct UTC frames through setUTCFullYear instead of inheriting that legacy quirk.
+ * Date.UTC remaps years 0..99 to 1900..1999 and Slotlock accepts years down to 1, so frames are
+ * built with setUTCFullYear.
  */
 export declare function utcFrame(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond: number): Date;
 /** The UTC day an instant falls in, as ZoneOffsets reads a zone's offsets: days since 1970. */
 export declare function zoneOffsetDay(utcMs: number): number;
 /**
- * How far either side of a wall time converting it to its instant reads the zone's offsets: no zone
- * is further than this from UTC. The days from one end to the other hold every offset it reads.
+ * How far either side of a wall time its conversion reads offsets: no zone is further than this
+ * from UTC.
  */
 export declare const ZONE_OFFSET_REACH_MS: number;
 /**
- * How many instants reading `timezone`'s offsets on UTC day `day` asks Intl for with none of them
- * kept, beyond the day's two midnights (one each): about twenty to find each change between them.
- * A caller that must charge the same for an input however much the process has kept charges each
- * midnight and this the first time it reads them.
+ * How many Intl reads finding the changes on UTC day `day` takes beyond its two midnights (about
+ * twenty per change). Callers that must charge the same whatever the process has cached charge this
+ * on first read.
  */
 export declare function zoneOffsetChangeReads(timezone: string, day: number): number;
 export declare function createTimeZoneConverter(timezone: string): TimeZoneConverter;
 /**
- * The spelling Slotlock keeps of an IANA zone name: Intl's, when Intl reads the name as itself in
- * another case (`europe/london` is `Europe/London`); otherwise the name as given (`US/Eastern` stays,
- * although this Node's ICU may call it `America/New_York`, so a stored name never depends on the
- * ICU version that wrote it). A UTC offset (`+05:00`, which Intl accepts as a zone) is not an IANA
- * name and is refused, as is anything Intl does not know: both with `code: 'invalid_timezone'`.
+ * The spelling Slotlock keeps of an IANA zone: Intl's when it reads the name as itself in another
+ * case (`europe/london` is `Europe/London`), else the name as given (`US/Eastern` stays, so a
+ * stored name never depends on the ICU version). A UTC offset such as `+05:00` and unknown names
+ * are refused with `code: 'invalid_timezone'`.
  */
 export declare function canonicalTimeZoneName(timezone: string): string;
 export interface ZonedCalendarDate {
@@ -68,9 +63,8 @@ export interface ZonedCalendarDate {
     isoWeekday: number;
 }
 /**
- * The civil date and ISO weekday an instant falls on in `timezone` — the inverse direction of
- * {@link zonedDateTimeToUtc}. Pricing reads "which day is this night" through here so a pickup at
- * 00:30 BST on a Friday is a Friday, not the Thursday its UTC timestamp reads as.
+ * The civil date and ISO weekday an instant falls on in `timezone` (the inverse of {@link
+ * zonedDateTimeToUtc}): a pickup at 00:30 BST on a Friday is a Friday, whatever UTC says.
  */
 export declare function zonedCalendarDate(instant: Date, timezone: string): ZonedCalendarDate;
 export interface ZonedWallTime {
@@ -80,9 +74,8 @@ export interface ZonedWallTime {
     time: string;
 }
 /**
- * The civil date and wall-clock time an instant reads as in `timezone`. Agreements and receipts
- * state a booking's start and end as a date and a time on the resource's own clock, not the
- * server's and not UTC.
+ * The civil date and wall-clock time an instant reads as in `timezone`, as agreements and receipts
+ * state a booking: on the resource's own clock.
  */
 export declare function zonedWallTime(instant: Date, timezone: string): ZonedWallTime;
 /** How far `timezone` is ahead of UTC at `instant`, in whole minutes (negative west of UTC). */
@@ -98,7 +91,7 @@ export interface ZonedDateTimeFields {
 }
 /**
  * The wall-clock fields an instant reads as in `timezone`, to the second: what a calendar writes
- * beside a TZID. Reads through the cached formatters, as every conversion here does.
+ * beside a TZID.
  */
 export declare function zonedDateTimeFields(instant: Date, timezone: string): ZonedDateTimeFields;
 export declare function zonedDateTimeToUtc(value: LocalDateTime, timezone: string, choice?: WallTimeChoice): Date;
@@ -111,8 +104,7 @@ export interface ZoneTransition {
     after: number;
 }
 /**
- * Every change of `timezone`'s offset from `fromMs` to `toMs`, as Intl reads the zone, from its
- * offsets a day at a time (ZoneOffsets): Gaza's clocks go forward on 20 October 2040 and back six
- * days later, which a search a week at a time missed.
+ * Every change of `timezone`'s offset from `fromMs` to `toMs`, read a day at a time (ZoneOffsets):
+ * a weekly search misses short-lived changes such as Gaza's six-day one in October 2040.
  */
 export declare function zoneTransitions(timezone: string, fromMs: number, toMs: number): ZoneTransition[];

package/timezone.js

@@ -1,10 +1,8 @@
 const FOURTEEN_HOURS_MS = 14 * 60 * 60 * 1000;
 /**
- * The instant, in ms, that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone whose
- * offset at an instant `offsetAt` gives, in ms. The offsets in force within fourteen hours either
- * side are the candidates (no zone is further than that from UTC, so they include both sides of any
- * change the wall time is near); one that maps back to the wall time names it. Two do in a fold,
- * none in a gap, where the offset before the gap is the smaller one.
+ * The instant (ms) that reads as `wallFrameMs` (wall-clock fields framed as UTC) in a zone with
+ * offsets from `offsetAt`. Candidates are the offsets within fourteen hours either side (no zone is
+ * further from UTC); one that maps back names it. Two do in a fold, none in a gap.
  */
 export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     const offsets = new Set([
@@ -25,8 +23,8 @@ export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     const shifted = wallFrameMs - Math.min(...offsets);
     if (choice.gap !== 'end')
         return shifted;
-    // The gap ends at the change: the first whole second after the instant read with the offset
-    // after the gap (which is still before it) whose offset differs from that one's.
+    // The gap ends at the change: the first whole second after the instant read with the after-gap
+    // offset whose offset differs from it.
     let before = wallFrameMs - Math.max(...offsets);
     const offsetBefore = offsetAt(before);
     let after = shifted;
@@ -40,8 +38,8 @@ export function wallFrameToInstant(wallFrameMs, offsetAt, choice = {}) {
     return after;
 }
 /**
- * Date.UTC remaps years 0..99 to 1900..1999. Slotlock accepts ISO calendar years down to 1,
- * so construct UTC frames through setUTCFullYear instead of inheriting that legacy quirk.
+ * Date.UTC remaps years 0..99 to 1900..1999 and Slotlock accepts years down to 1, so frames are
+ * built with setUTCFullYear.
  */
 export function utcFrame(year, month, day, hour, minute, second, millisecond) {
     const frame = new Date(0);
@@ -50,10 +48,8 @@ export function utcFrame(year, month, day, hour, minute, second, millisecond) {
     return frame;
 }
 /**
- * Formatters already built, by zone name. Building one costs far more than using it, and every
- * conversion needs one: a recurring series reads about three times an occurrence. A formatter never
- * changes, so one per zone serves every caller. Intl accepts every capitalisation of each zone's
- * name, so the map is emptied when it fills rather than growing with whatever names arrive.
+ * Formatters by zone name: building one costs far more than using it. Intl accepts any
+ * capitalisation of a name, so the map is emptied when full rather than growing.
  */
 const formatters = new Map();
 const MAX_CACHED_FORMATTERS = 256;
@@ -75,21 +71,19 @@ export function zoneOffsetDay(utcMs) {
     return Math.floor(utcMs / DAY_MS);
 }
 /**
- * How far either side of a wall time converting it to its instant reads the zone's offsets: no zone
- * is further than this from UTC. The days from one end to the other hold every offset it reads.
+ * How far either side of a wall time its conversion reads offsets: no zone is further than this
+ * from UTC.
  */
 export const ZONE_OFFSET_REACH_MS = FOURTEEN_HOURS_MS;
 /** How many midnights one block of a zone's offsets holds. */
 const BLOCK_DAYS = 512;
 const NO_CHANGES = [];
 /**
- * A zone's offsets, read from Intl a UTC day at a time and kept. Intl's formatToParts takes about
- * two microseconds and a conversion asks for four to six offsets, so a series that converts a time
- * at each of thousands of occurrences spent most of its time there (forty daily London series from
- * 2016, 35 seconds). Each UTC midnight's offset is read once; a day whose two midnights agree has
- * that offset throughout, and one whose midnights differ has each change in it narrowed to the
- * second (scanTransitions). A change and its reversal within one day would be missed; the tests
- * compare the zones whose clocks change most with an hourly search.
+ * A zone's offsets, read from Intl a UTC day at a time and kept: formatToParts costs about two
+ * microseconds and a conversion needs four to six offsets. Each midnight is read once; a day whose
+ * midnights agree has that offset throughout, and a day whose midnights differ has each change
+ * narrowed to the second (scanTransitions). A change and its reversal within one day would be
+ * missed; tests check the most volatile zones against an hourly search.
  */
 class ZoneOffsets {
     /** The offset at each UTC midnight read (NaN where none is), BLOCK_DAYS days to a block. */
@@ -102,7 +96,7 @@ class ZoneOffsets {
     }
     offsetAt(utcMs) {
         const day = zoneOffsetDay(utcMs);
-        // Not a time value: Intl refuses it, as it always has.
+        // Not a time value: let Intl refuse it.
         if (!Number.isFinite(day))
             return offsetAt(utcMs, this.formatter);
         let offset = this.midnight(day);
@@ -170,10 +164,8 @@ function dayStart(day) {
     return Math.min(Math.max(day * DAY_MS, -MAX_TIME_MS), MAX_TIME_MS);
 }
 /**
- * Each zone's offsets, by name, as createFormatter keeps formatters. A block of midnights takes 4
- * KB; once there are this many (16 MB, about 57 zone-centuries), every zone's are emptied, and so
- * are the days with changes once there are this many of those (zones change twice a year at most
- * but for a few).
+ * Each zone's offsets by name. A block of midnights is 4 KB; past this many blocks (16 MB) every
+ * zone's are emptied, and likewise for days with changes.
  */
 const zoneOffsetTables = new Map();
 const MAX_CACHED_BLOCKS = 4_096;
@@ -194,10 +186,9 @@ function zoneOffsets(timezone) {
     return offsets;
 }
 /**
- * How many instants reading `timezone`'s offsets on UTC day `day` asks Intl for with none of them
- * kept, beyond the day's two midnights (one each): about twenty to find each change between them.
- * A caller that must charge the same for an input however much the process has kept charges each
- * midnight and this the first time it reads them.
+ * How many Intl reads finding the changes on UTC day `day` takes beyond its two midnights (about
+ * twenty per change). Callers that must charge the same whatever the process has cached charge this
+ * on first read.
  */
 export function zoneOffsetChangeReads(timezone, day) {
     if (timezone === 'UTC')
@@ -222,8 +213,8 @@ function buildFormatter(timezone) {
     }
 }
 function offsetAt(utcMs, formatter) {
-    // Intl parts expose seconds but not milliseconds. Compute the zone offset against the same
-    // whole-second instant so sub-second input does not leak into the offset and get rounded away.
+    // Intl parts expose seconds, not milliseconds: compute the offset at the whole second so
+    // sub-second input is not rounded into it.
     const wholeSecondMs = Math.floor(utcMs / 1000) * 1000;
     const values = {};
     for (const part of formatter.formatToParts(new Date(wholeSecondMs))) {
@@ -246,17 +237,21 @@ export function createTimeZoneConverter(timezone) {
     };
 }
 /**
- * The spelling Slotlock keeps of an IANA zone name: Intl's, when Intl reads the name as itself in
- * another case (`europe/london` is `Europe/London`); otherwise the name as given (`US/Eastern` stays,
- * although this Node's ICU may call it `America/New_York`, so a stored name never depends on the
- * ICU version that wrote it). A UTC offset (`+05:00`, which Intl accepts as a zone) is not an IANA
- * name and is refused, as is anything Intl does not know: both with `code: 'invalid_timezone'`.
+ * The spelling Slotlock keeps of an IANA zone: Intl's when it reads the name as itself in another
+ * case (`europe/london` is `Europe/London`), else the name as given (`US/Eastern` stays, so a
+ * stored name never depends on the ICU version). A UTC offset such as `+05:00` and unknown names
+ * are refused with `code: 'invalid_timezone'`.
  */
 export function canonicalTimeZoneName(timezone) {
     const name = timezone.trim();
     const invalid = () => Object.assign(new Error(`Invalid timezone: ${timezone}`), { code: 'invalid_timezone' });
     if (!name || /^[+-]/.test(name))
         throw invalid();
+    // Each name resolves the same for the process's life (its time zone data does not change under
+    // it), and building a formatter to ask is the costly part: remembered, valid names only.
+    const known = canonicalNames.get(name);
+    if (known !== undefined)
+        return known;
     let resolved;
     try {
         resolved = new Intl.DateTimeFormat('en-US', { timeZone: name }).resolvedOptions().timeZone;
@@ -266,12 +261,18 @@ export function canonicalTimeZoneName(timezone) {
     }
     if (/^[+-]/.test(resolved))
         throw invalid();
-    return resolved.toLowerCase() === name.toLowerCase() ? resolved : name;
+    const canonical = resolved.toLowerCase() === name.toLowerCase() ? resolved : name;
+    if (canonicalNames.size >= MAX_CANONICAL_NAMES)
+        canonicalNames.clear();
+    canonicalNames.set(name, canonical);
+    return canonical;
 }
+/** Names canonicalTimeZoneName resolved; a few hundred zones exist, so this rarely fills. */
+const canonicalNames = new Map();
+const MAX_CANONICAL_NAMES = 2_000;
 /**
- * The civil date and ISO weekday an instant falls on in `timezone` — the inverse direction of
- * {@link zonedDateTimeToUtc}. Pricing reads "which day is this night" through here so a pickup at
- * 00:30 BST on a Friday is a Friday, not the Thursday its UTC timestamp reads as.
+ * The civil date and ISO weekday an instant falls on in `timezone` (the inverse of {@link
+ * zonedDateTimeToUtc}): a pickup at 00:30 BST on a Friday is a Friday, whatever UTC says.
  */
 export function zonedCalendarDate(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -279,9 +280,8 @@ export function zonedCalendarDate(instant, timezone) {
     return { date: civilDate(wall), isoWeekday: weekday === 0 ? 7 : weekday };
 }
 /**
- * The civil date and wall-clock time an instant reads as in `timezone`. Agreements and receipts
- * state a booking's start and end as a date and a time on the resource's own clock, not the
- * server's and not UTC.
+ * The civil date and wall-clock time an instant reads as in `timezone`, as agreements and receipts
+ * state a booking: on the resource's own clock.
  */
 export function zonedWallTime(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -295,7 +295,7 @@ export function zonedOffsetMinutes(instant, timezone) {
 }
 /**
  * The wall-clock fields an instant reads as in `timezone`, to the second: what a calendar writes
- * beside a TZID. Reads through the cached formatters, as every conversion here does.
+ * beside a TZID.
  */
 export function zonedDateTimeFields(instant, timezone) {
     const wall = wallFrame(instant, timezone);
@@ -356,9 +356,8 @@ export function zonedDateTimeToUtc(value, timezone, choice) {
     return createTimeZoneConverter(timezone).wallFrameToUtc(wallFrame, choice);
 }
 /**
- * Every change of `timezone`'s offset from `fromMs` to `toMs`, as Intl reads the zone, from its
- * offsets a day at a time (ZoneOffsets): Gaza's clocks go forward on 20 October 2040 and back six
- * days later, which a search a week at a time missed.
+ * Every change of `timezone`'s offset from `fromMs` to `toMs`, read a day at a time (ZoneOffsets):
+ * a weekly search misses short-lived changes such as Gaza's six-day one in October 2040.
  */
 export function zoneTransitions(timezone, fromMs, toMs) {
     if (timezone === 'UTC')
@@ -366,9 +365,8 @@ export function zoneTransitions(timezone, fromMs, toMs) {
     return zoneOffsets(timezone).transitions(Math.floor(fromMs / 1000) * 1000, Math.ceil(toMs / 1000) * 1000);
 }
 /**
- * The changes of the offset `offsetIn` reads from `fromMs` to `toMs`, found by comparing offsets
- * `stepMs` apart and narrowing each change to the second: a change and its reversal both within
- * one step are missed.
+ * Offset changes found by comparing `offsetIn` `stepMs` apart and narrowing each to the second; a
+ * change and its reversal within one step are missed.
  */
 function scanTransitions(offsetIn, fromMs, toMs, stepMs) {
     const found = [];
@@ -380,7 +378,6 @@ function scanTransitions(offsetIn, fromMs, toMs, stepMs) {
             at = next;
             continue;
         }
-        // The last whole second at `offset` and the first at another.
         let low = at;
         let high = next;
         while (high - low > 1000) {