@pmeweb/content 2.0.0 → 2.1.0

package/README.md

@@ -8,7 +8,7 @@ collections in `src/content.schema.json`; this package is what reads that declar
 | `@pmeweb/content/types` | `CollectionDecl`, `Field`, `ScheduleDecl`, `ContentSchema` | sites, portal |
 | `@pmeweb/content/zodFrom` | declaration -> Astro zod schema (needs `astro`) | sites |
 | `@pmeweb/content/fields` | `isDate`, `isDateTime`, `isTime`, `isDayDate`, `TIME_RE` | portal tier 1, `zodFrom` |
-| `@pmeweb/content/schedule` | `scheduleState`, `visibleOnSite`, `portalPreview`, `scheduleErrors`, `jourQuebec`, `quebecDay` | sites, portal |
+| `@pmeweb/content/schedule` | `scheduleState`, `visibleOnSite`, `portalPreview`, `scheduleErrors`, `jourQuebec`, `quebecDay`, `quebecMidnight`, `nextQuebecDay`, `scheduledCollections`, `entryBoundaries`, `nextChangeAt`, `Schedule` | sites, portal |
 | `@pmeweb/content/collection` | `titleFieldError`, `thumbnailError`, `richErrors`, `collectionErrors`, `schemaErrors`, `richBodyField`, `hasThumbnails` | portal, `zodFrom` |
 | `@pmeweb/content/published` | `getPublished`, the one filter every site's pages go through | sites |
 | `@pmeweb/content/prose.css` | the structure of a row of images in a rich body | sites' `Prose.astro` |
@@ -29,7 +29,12 @@ collections in `src/content.schema.json`; this package is what reads that declar
   a `datetime` at its instant.
 - `removeAt`: one path or several; the first that yields a value wins. `dates[].debut` takes the
   latest value in the array. Always read as a Quebec day: the entry stays through that whole day
-  and comes off at the next day's rebuild. A site that declares a schedule needs a daily rebuild.
+  and comes off at the start of the next one.
+
+A site that declares a schedule serves `/schedule.json` (`{ next }`, built with
+`scheduledCollections`, `entryBoundaries` and `nextChangeAt`; the boilerplate ships the endpoint),
+and the portal's hourly scheduler rebuilds it once `next` has passed (its deploy hook goes in the
+admin's « Publication planifiée » card).
 
 ## The portal preview
 
@@ -40,6 +45,18 @@ reads both once, `const APERCU = portalPreview(process.env)`, and filters with
 drafts in the preview, removed ones only in a preview that asked for them. Only the exact
 string `'1'` counts, and the past flag means nothing without the preview flag.
 
+## 2.1.0
+
+Additive, for `/schedule.json`:
+
+- `scheduledCollections(schema)`: the collections that declare a valid `schedule`, in order.
+- `entryBoundaries(data, decl)`: every instant at which `scheduleState` of that entry changes, by
+  the same rules (none for a draft; a removal at or before the publication is not a change).
+- `nextChangeAt(candidates, now)`: the earliest one strictly after `now`, as `toISOString()`, or
+  `null`. `Schedule` is the `{ next }` shape the endpoint serves.
+- `quebecMidnight(day)` (the instant a Quebec day starts) and `nextQuebecDay(day)`, for a site
+  that adds instants its declaration does not name (jessyoga).
+
 ## 2.0.0
 
 Four declaration keys:

package/dist/schedule.d.ts

@@ -18,6 +18,18 @@ export interface SchedulableLike {
         draft?: unknown;
     };
 }
+/**
+ * The instant a Quebec calendar day starts (00:00 in America/Toronto), as epoch ms; NaN for
+ * anything that is not a real `YYYY-MM-DD`.
+ *
+ * Toronto changes its clock at 02:00 local, so midnight always exists, once, at UTC-4 (daylight)
+ * or UTC-5 (standard). 04:00Z is that midnight when the day starts on daylight time; when it starts
+ * on standard time, 04:00Z is still 23:00 the evening before, so 05:00Z is the first candidate
+ * that falls on `day`. The earlier candidate that falls on the day is its start.
+ */
+export declare function quebecMidnight(day: string): number;
+/** The calendar day after `day`, or null when `day` is not one. */
+export declare function nextQuebecDay(day: string): string | null;
 /**
  * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
  * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
@@ -50,6 +62,43 @@ export declare function scheduleErrors(c: SchedulableLike): string[];
  * anything.
  */
 export declare function scheduleState(data: Record<string, unknown>, c: SchedulableLike, now: Date): ScheduleState;
+/**
+ * The collections of a site's `content.schema.json` that declare a VALID `schedule`, in
+ * declaration order. A site's `/schedule.json` walks exactly these, so a collection that gains a
+ * `schedule` later is covered without anybody remembering to add it -- the silent failure of a
+ * hand-kept list is a site that quietly stops aging. An invalid declaration is left out because
+ * `scheduleState` answers `live` for it at every instant: it has no boundary to report.
+ */
+export declare function scheduledCollections(schema: Record<string, SchedulableLike>): string[];
+/**
+ * Every instant at which `scheduleState` of this entry changes, and only those, in time order.
+ *
+ * THE SAME RULES AS `scheduleState`, read from the same helpers, which is why this lives here:
+ * publication is `publishInstant`; removal is the start of the Quebec day AFTER `removeDay`. A
+ * `draft` has none: it is hidden by a rule that has nothing to do with the clock. A removal that
+ * falls at or before the publication is not a change of its own (`scheduled` beats `removed`, so
+ * the entry goes straight from `scheduled` to `removed` at the publication), and is left out.
+ *
+ * A site's `/schedule.json` is the earliest of these across its entries (`nextChangeAt`), and the
+ * portal's hourly scheduler rebuilds the site once that instant has passed. A boundary missing
+ * here is a site that silently stops aging.
+ *
+ * Only what the DECLARATION says. A site that filters by time on fields its `schedule` does not
+ * name (jessyoga's per-date `publierLe`, its `prixFin`) must add those instants itself.
+ */
+export declare function entryBoundaries(data: Record<string, unknown>, c: SchedulableLike): number[];
+/**
+ * The earliest candidate strictly after `now`, as ISO (`toISOString`), or null when nothing is
+ * pending. STRICTLY after: an instant that has arrived was already rendered by the build computing
+ * this. A non-finite candidate is dropped, not allowed to make the answer « nothing », and so is
+ * one past year 9999, whose ISO form (`+010000-...`) the portal would refuse as unreadable.
+ */
+export declare function nextChangeAt(candidates: Iterable<number>, now: number): string | null;
+/** What `/schedule.json` serves. One field, so a reader cannot pick the wrong one. */
+export interface Schedule {
+    /** An ISO instant, or null when nothing is pending. */
+    next: string | null;
+}
 /**
  * What kind of build this is, read from the two variables the portal's builder sets.
  *

package/dist/schedule.js

@@ -11,9 +11,10 @@
 // during the evening it describes. So `now` is turned into the day it is in `America/Toronto`,
 // with Intl doing the clock changes, and compared as a `YYYY-MM-DD` string.
 //
-// A STATIC SITE APPLIES THIS WHEN IT BUILDS. `now` is build time; the daily rebuild (06:00
-// Quebec) is what makes an entry come off « the morning after ». A collection that declares a
-// schedule on a site with no daily rebuild keeps showing it until someone publishes.
+// A STATIC SITE APPLIES THIS WHEN IT BUILDS. `now` is build time; the site serves the next instant
+// its output changes at `/schedule.json` (`scheduledCollections` + `entryBoundaries` +
+// `nextChangeAt`), and the portal's hourly scheduler (pmeweb-portail/src/server/schedule/) rebuilds
+// it once that instant has passed.
 import { isDate, isDateTime } from './fields.js';
 /** The zone every PmeWeb client lives in. One constant, named where it is used. */
 export const QUEBEC = 'America/Toronto';
@@ -27,6 +28,31 @@ function quebecDayOf(ms) {
         p[part.type] = part.value;
     return `${p.year}-${p.month}-${p.day}`;
 }
+/**
+ * The instant a Quebec calendar day starts (00:00 in America/Toronto), as epoch ms; NaN for
+ * anything that is not a real `YYYY-MM-DD`.
+ *
+ * Toronto changes its clock at 02:00 local, so midnight always exists, once, at UTC-4 (daylight)
+ * or UTC-5 (standard). 04:00Z is that midnight when the day starts on daylight time; when it starts
+ * on standard time, 04:00Z is still 23:00 the evening before, so 05:00Z is the first candidate
+ * that falls on `day`. The earlier candidate that falls on the day is its start.
+ */
+export function quebecMidnight(day) {
+    if (!isDate(day))
+        return Number.NaN;
+    for (const h of [4, 5]) {
+        const ms = Date.parse(`${day}T0${h}:00:00.000Z`);
+        if (quebecDayOf(ms) === day)
+            return ms;
+    }
+    return Number.NaN;
+}
+/** The calendar day after `day`, or null when `day` is not one. */
+export function nextQuebecDay(day) {
+    if (!isDate(day))
+        return null;
+    return new Date(Date.parse(`${day}T00:00:00.000Z`) + 86_400_000).toISOString().slice(0, 10);
+}
 /**
  * The Quebec calendar day `now` falls on, as UTC midnight of that day -- the same shape a `date`
  * field has once a site's zod has read it, so the two compare directly (`fin >= jourQuebec(now)`).
@@ -192,6 +218,84 @@ export function scheduleState(data, c, now) {
     const d = removeDay(data, c);
     return d !== null && quebecDayOf(now.getTime()) > d ? 'removed' : 'live';
 }
+/**
+ * The collections of a site's `content.schema.json` that declare a VALID `schedule`, in
+ * declaration order. A site's `/schedule.json` walks exactly these, so a collection that gains a
+ * `schedule` later is covered without anybody remembering to add it -- the silent failure of a
+ * hand-kept list is a site that quietly stops aging. An invalid declaration is left out because
+ * `scheduleState` answers `live` for it at every instant: it has no boundary to report.
+ */
+export function scheduledCollections(schema) {
+    return Object.entries(schema)
+        .filter(([, c]) => c.schedule !== undefined && scheduleErrors(c).length === 0)
+        .map(([name]) => name);
+}
+/** The instant `publishAt` takes effect: a `date` at the start of its Quebec day, a `datetime` at
+ *  its instant. The mirror of `isScheduled`: scheduled before it, not scheduled from it on. */
+function publishInstant(data, c) {
+    const key = c.schedule?.publishAt;
+    if (typeof key !== 'string')
+        return null;
+    const f = c.fields[key];
+    if (!f)
+        return null;
+    if (f.kind === 'datetime')
+        return instant(data[key]);
+    const d = quebecDay(data[key], f.kind);
+    const ms = d === null ? Number.NaN : quebecMidnight(d);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Every instant at which `scheduleState` of this entry changes, and only those, in time order.
+ *
+ * THE SAME RULES AS `scheduleState`, read from the same helpers, which is why this lives here:
+ * publication is `publishInstant`; removal is the start of the Quebec day AFTER `removeDay`. A
+ * `draft` has none: it is hidden by a rule that has nothing to do with the clock. A removal that
+ * falls at or before the publication is not a change of its own (`scheduled` beats `removed`, so
+ * the entry goes straight from `scheduled` to `removed` at the publication), and is left out.
+ *
+ * A site's `/schedule.json` is the earliest of these across its entries (`nextChangeAt`), and the
+ * portal's hourly scheduler rebuilds the site once that instant has passed. A boundary missing
+ * here is a site that silently stops aging.
+ *
+ * Only what the DECLARATION says. A site that filters by time on fields its `schedule` does not
+ * name (jessyoga's per-date `publierLe`, its `prixFin`) must add those instants itself.
+ */
+export function entryBoundaries(data, c) {
+    if (!c.schedule || scheduleErrors(c).length > 0)
+        return [];
+    const draftKey = c.schedule.draft;
+    if (typeof draftKey === 'string' && data[draftKey] === true)
+        return [];
+    const out = [];
+    const publish = publishInstant(data, c);
+    if (publish !== null)
+        out.push(publish);
+    const removal = removeDay(data, c);
+    const after = removal === null ? null : nextQuebecDay(removal);
+    const remove = after === null ? Number.NaN : quebecMidnight(after);
+    if (Number.isFinite(remove) && (publish === null || remove > publish))
+        out.push(remove);
+    return out;
+}
+/** The last instant `toISOString` writes with a four-digit year, the only shape the portal reads. */
+const LAST_ISO = Date.parse('9999-12-31T23:59:59.999Z');
+/**
+ * The earliest candidate strictly after `now`, as ISO (`toISOString`), or null when nothing is
+ * pending. STRICTLY after: an instant that has arrived was already rendered by the build computing
+ * this. A non-finite candidate is dropped, not allowed to make the answer « nothing », and so is
+ * one past year 9999, whose ISO form (`+010000-...`) the portal would refuse as unreadable.
+ */
+export function nextChangeAt(candidates, now) {
+    let best = null;
+    for (const at of candidates) {
+        if (!Number.isFinite(at) || at <= now || at > LAST_ISO)
+            continue;
+        if (best === null || at < best)
+            best = at;
+    }
+    return best === null ? null : new Date(best).toISOString();
+}
 export function portalPreview(env) {
     const active = env.PMEWEB_PORTAL_PREVIEW === '1';
     return { active, showPast: active && env.PMEWEB_PORTAL_PREVIEW_PAST === '1' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmeweb/content",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "PmeWeb content contract: content.schema.json types, zodFrom, field checks, scheduling. Read by every site's build and by the client portal.",
   "type": "module",
   "license": "MIT",