dsh-model-pool 0.0.0-stage → 0.1.0

package/lib/peak.js

@@ -0,0 +1,495 @@
+/**
+* Peak/idle period resolution for the pool's priority strategy.
+*
+* Pure: no timers, no I/O, no host services. Every function takes the instant it
+* reasons about, so one routing decision is reproducible from `(now, config)`
+* alone and the tests never depend on the wall clock.
+*
+* The defaults implement the requested policy: Beijing time, Monday to Friday
+* 09:00-12:00 and 14:00-18:00 are **peak**; every other moment — weekends and every
+* statutory holiday — is **idle**.
+*
+* The holiday dates are not defined here. A worked calendar cannot be derived from a
+* rule, so the Host fetches and caches it (`lib/holiday-calendar.js`) and passes the
+* resolved date sets in as `holidays` / `makeupWorkdays`. Keeping the data out of
+* this module is what lets it stay pure while the dates still stay current.
+*
+* @module dsh-model-pool/lib/peak
+*/
+
+/** Peak period id. */
+export const PEAK = "peak";
+
+/** Idle period id. */
+export const OFF_PEAK = "offPeak";
+
+/** Time zone the defaults are expressed in. */
+export const DEFAULT_PEAK_TIME_ZONE = "Asia/Shanghai";
+
+/** Default peak windows, in local time. */
+export const DEFAULT_PEAK_WINDOWS = ["09:00-12:00", "14:00-18:00"];
+
+/** Default peak weekdays: ISO 1 = Monday … 7 = Sunday. */
+export const DEFAULT_PEAK_WEEKDAYS = [1, 2, 3, 4, 5];
+
+/** Minutes in one wall-clock day. */
+const MINUTES_PER_DAY = 1440;
+
+/** Milliseconds in one wall-clock day. */
+const DAY_MS = 86_400_000;
+
+/** Priority base for a provider the effective ranking does not list. */
+const UNRANKED_PRIORITY = 1000;
+
+/**
+* How many days `nextChangeAt` looks ahead before giving up.
+* Sized for the longest idle run the fetched calendar can produce: the 2026 Spring
+* Festival closes 2026-02-15..02-23, so the next peak starts 11 days after the last
+* working Friday. 16 leaves room for a longer future block without turning a routing
+* decision into a long scan.
+*/
+const LOOKAHEAD_DAYS = 16;
+
+/** English short weekday names, as the ICU formatter spells them. */
+const WEEKDAY_BY_SHORT = { Sun: 7, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+
+/** Formatter per time zone, reused across calls (construction is the expensive part). */
+const FORMATTERS = new Map();
+
+/** Whether one time zone is accepted by `Intl`, cached. */
+const ZONE_USABLE = new Map();
+
+/**
+* One `Intl` formatter for a time zone.
+* @param timeZone - IANA zone name.
+* @returns the cached formatter.
+*/
+function formatterFor(timeZone) {
+	let formatter = FORMATTERS.get(timeZone);
+	if (formatter === undefined) {
+		formatter = new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			hourCycle: "h23",
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			weekday: "short",
+		});
+		FORMATTERS.set(timeZone, formatter);
+	}
+	return formatter;
+}
+
+/**
+* Whether `Intl` knows a time zone.
+* @param timeZone - IANA zone name.
+* @returns true when a formatter can be built for it.
+*/
+function zoneUsable(timeZone) {
+	const cached = ZONE_USABLE.get(timeZone);
+	if (cached !== undefined) return cached;
+	let usable = true;
+	try {
+		formatterFor(timeZone).format(0);
+	} catch {
+		usable = false;
+	}
+	ZONE_USABLE.set(timeZone, usable);
+	return usable;
+}
+
+/**
+* Resolve a configured time zone to one that can actually be read.
+* An empty or unknown zone falls back to the default, so a typo can never break
+* routing — it only means "Beijing time".
+* @param raw - configured zone.
+* @returns a usable IANA zone name.
+*/
+export function resolveTimeZone(raw) {
+	if (typeof raw !== "string") return DEFAULT_PEAK_TIME_ZONE;
+	const zone = raw.trim();
+	if (zone === "") return DEFAULT_PEAK_TIME_ZONE;
+	if (typeof Intl === "undefined") return DEFAULT_PEAK_TIME_ZONE;
+	return zoneUsable(zone) ? zone : DEFAULT_PEAK_TIME_ZONE;
+}
+
+/**
+* Two-digit zero padding.
+* @param value - number to pad.
+* @returns the padded string.
+*/
+function pad(value) {
+	return String(value).padStart(2, "0");
+}
+
+/**
+* UTC wall-clock reading of an instant shifted by a fixed offset.
+* The fallback path for a runtime without `Intl` support for the zone.
+* @param epochMs - the instant.
+* @param offsetMinutes - minutes east of UTC.
+* @returns the wall-clock parts.
+*/
+function offsetParts(epochMs, offsetMinutes) {
+	const shifted = new Date(epochMs + offsetMinutes * 60_000);
+	const date = `${shifted.getUTCFullYear()}-${pad(shifted.getUTCMonth() + 1)}-${pad(shifted.getUTCDate())}`;
+	const utcWeekday = shifted.getUTCDay();
+	return {
+		date,
+		weekday: utcWeekday === 0 ? 7 : utcWeekday,
+		minuteOfDay: shifted.getUTCHours() * 60 + shifted.getUTCMinutes(),
+		secondOfMinute: shifted.getUTCSeconds(),
+	};
+}
+
+/**
+* Wall-clock reading of an instant in one time zone.
+* @param epochMs - epoch milliseconds.
+* @param timeZone - IANA zone name.
+* @returns `{ date: 'YYYY-MM-DD', weekday: 1..7, minuteOfDay, secondOfMinute, timeZone }`.
+*/
+export function wallClock(epochMs, timeZone = DEFAULT_PEAK_TIME_ZONE) {
+	const at = Number.isFinite(epochMs) ? epochMs : Date.now();
+	const zone = resolveTimeZone(timeZone);
+	let parts;
+	try {
+		const bag = {};
+		for (const part of formatterFor(zone).formatToParts(new Date(at))) bag[part.type] = part.value;
+		const year = Number(bag.year);
+		const month = Number(bag.month);
+		const day = Number(bag.day);
+		const hour = Number(bag.hour) % 24;
+		const minute = Number(bag.minute);
+		const second = Number(bag.second);
+		if ([year, month, day, hour, minute].every((value) => Number.isFinite(value))) {
+			parts = {
+				date: `${year}-${pad(month)}-${pad(day)}`,
+				// A zone offset is always a whole number of minutes, so this is exact.
+				weekday: WEEKDAY_BY_SHORT[bag.weekday] ?? 1,
+				minuteOfDay: hour * 60 + minute,
+				secondOfMinute: Number.isFinite(second) ? second : 0,
+			};
+		}
+	} catch {
+		parts = undefined;
+	}
+	const clock = parts ?? offsetParts(at, 480);
+	return { ...clock, timeZone: zone };
+}
+
+/**
+* Parse one `HH:MM-HH:MM` window.
+* `24:00` is accepted as an end, so a window may run to midnight.
+* @param text - one configured window.
+* @returns `{ start, end, label }` in minutes, or undefined when unusable.
+*/
+export function parsePeakWindow(text) {
+	if (typeof text !== "string") return undefined;
+	const match = /^\s*(\d{1,2}):(\d{2})\s*[-–—~至]\s*(\d{1,2}):(\d{2})\s*$/.exec(text);
+	if (match === null) return undefined;
+	const start = Number(match[1]) * 60 + Number(match[2]);
+	const end = Number(match[3]) * 60 + Number(match[4]);
+	if (!Number.isFinite(start) || !Number.isFinite(end)) return undefined;
+	if (start < 0 || start >= MINUTES_PER_DAY) return undefined;
+	if (end <= start || end > MINUTES_PER_DAY) return undefined;
+	return { start, end, label: formatWindow(start, end) };
+}
+
+/**
+* Render a minute range as `HH:MM-HH:MM`.
+* @param start - first minute of the window.
+* @param end - first minute after the window.
+* @returns the label.
+*/
+export function formatWindow(start, end) {
+	return `${pad(Math.floor(start / 60))}:${pad(start % 60)}-${pad(Math.floor(end / 60))}:${pad(end % 60)}`;
+}
+
+/**
+* Parse a list of window strings.
+* An absent list means the defaults; an explicit empty list means "never peak".
+* Unusable entries are dropped rather than throwing.
+* @param raw - configured windows.
+* @returns the parsed windows, sorted and merged.
+*/
+export function parsePeakWindows(raw) {
+	const source = raw === undefined || raw === null ? DEFAULT_PEAK_WINDOWS : raw;
+	const parsed = (Array.isArray(source) ? source : [])
+		.map(parsePeakWindow)
+		.filter((window) => window !== undefined)
+		.sort((left, right) => left.start - right.start);
+	const merged = [];
+	for (const window of parsed) {
+		const last = merged.at(-1);
+		if (last !== undefined && window.start <= last.end) {
+			if (window.end > last.end) {
+				last.end = window.end;
+				last.label = formatWindow(last.start, last.end);
+			}
+			continue;
+		}
+		merged.push({ ...window });
+	}
+	return merged;
+}
+
+/**
+* Normalize the weekday list.
+* An absent list means Monday to Friday; an explicit empty list means "never peak".
+* @param raw - configured weekdays.
+* @returns ISO weekdays 1..7, in ascending order.
+*/
+export function parsePeakWeekdays(raw) {
+	const source = raw === undefined || raw === null ? DEFAULT_PEAK_WEEKDAYS : raw;
+	const days = new Set();
+	for (const entry of Array.isArray(source) ? source : []) {
+		const day = Number(entry);
+		if (Number.isInteger(day) && day >= 1 && day <= 7) days.add(day);
+	}
+	return [...days].sort((left, right) => left - right);
+}
+
+/**
+* Whether a string is a real calendar date in `YYYY-MM-DD` form.
+* @param value - candidate date.
+* @returns true for a date such as `2026-02-17`.
+*/
+export function isDateString(value) {
+	if (typeof value !== "string") return false;
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+	if (match === null) return false;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	if (month < 1 || month > 12 || day < 1 || day > 31) return false;
+	const probe = new Date(Date.UTC(year, month - 1, day));
+	return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+}
+
+/**
+* Parse a list of `YYYY-MM-DD` dates into a set.
+* Unusable entries are dropped; a present list replaces the default entirely.
+* @param raw - configured dates, or undefined to use the caller's default.
+* @param fallback - dates used when the field is absent.
+* @returns the date set.
+*/
+export function parseDateSet(raw, fallback = []) {
+	const source = raw === undefined || raw === null ? fallback : raw;
+	const set = new Set();
+	for (const entry of Array.isArray(source) ? source : []) {
+		if (typeof entry !== "string") continue;
+		const date = entry.trim();
+		if (isDateString(date)) set.add(date);
+	}
+	return set;
+}
+
+/**
+* Normalize the whole peak configuration into the shape the pure functions read.
+*
+* `holidays` and `makeupWorkdays` arrive already resolved: the Host reads them from the
+* fetched calendar (`lib/holiday-calendar.js`) and layers `holidayOverride` on top before
+* calling here. This module therefore has no built-in holiday list, and an absent list
+* means "no known holidays" — the conservative reading that treats every day by the
+* weekday rule when the calendar has never loaded.
+*
+* @param config - plain pool configuration (`peak*` fields plus resolved date sets).
+* @returns the normalized peak configuration.
+*/
+export function normalizePeakConfig(config = {}) {
+	const source = config === null || config === undefined ? {} : config;
+	return {
+		enabled: source.peakEnabled !== false,
+		timeZone: resolveTimeZone(source.peakTimeZone),
+		windows: parsePeakWindows(source.peakWindows),
+		weekdays: parsePeakWeekdays(source.peakWeekdays),
+		holidays: parseDateSet(source.holidays, []),
+		makeupWorkdays: parseDateSet(source.makeupWorkdays, []),
+	};
+}
+
+/**
+* Whether one calendar day counts as a peak day, ignoring the time of day.
+*
+* Precedence, highest first: statutory holiday (always idle) → make-up workday
+* (peak even on a weekend) → the weekday rule. A holiday therefore wins even when
+* an operator lists the same date as a make-up workday: the two lists answer
+* different questions ("the State Council closed" vs "the State Council opened a
+* Saturday"), and a date cannot be both, so the closed reading is the safe one.
+*
+* @param cfg - normalized peak configuration.
+* @param weekday - ISO weekday of the date.
+* @param date - `YYYY-MM-DD`.
+* @returns true when the day is a working day under the peak policy.
+*/
+function isPeakDay(cfg, weekday, date) {
+	if (cfg.enabled !== true) return false;
+	if (cfg.holidays.has(date)) return false;
+	if (cfg.makeupWorkdays.has(date)) return true;
+	return cfg.weekdays.includes(weekday);
+}
+
+/**
+* The period of one wall-clock reading.
+* @param cfg - normalized peak configuration.
+* @param clock - wall-clock parts.
+* @returns `peak` or `offPeak`.
+*/
+function periodOfClock(cfg, clock) {
+	if (!isPeakDay(cfg, clock.weekday, clock.date)) return OFF_PEAK;
+	return cfg.windows.some((window) => clock.minuteOfDay >= window.start && clock.minuteOfDay < window.end)
+		? PEAK
+		: OFF_PEAK;
+}
+
+/**
+* The period one instant falls in.
+* @param epochMs - epoch milliseconds.
+* @param config - plain pool configuration.
+* @returns `peak` or `offPeak`.
+*/
+export function periodAt(epochMs, config = {}) {
+	const cfg = normalizePeakConfig(config);
+	const at = Number.isFinite(epochMs) ? epochMs : Date.now();
+	return periodOfClock(cfg, wallClock(at, cfg.timeZone));
+}
+
+/**
+* Split one day into alternating segments.
+* @param cfg - normalized peak configuration.
+* @param weekday - ISO weekday of the date.
+* @param date - `YYYY-MM-DD`.
+* @returns segments `{ start, end, period }` covering the whole day, in order.
+*/
+function daySegments(cfg, weekday, date) {
+	const segments = [];
+	let cursor = 0;
+	if (isPeakDay(cfg, weekday, date)) {
+		for (const window of cfg.windows) {
+			if (window.start > cursor) segments.push({ start: cursor, end: window.start, period: OFF_PEAK });
+			if (window.end > window.start) segments.push({ start: window.start, end: window.end, period: PEAK });
+			cursor = window.end;
+		}
+	}
+	if (cursor < MINUTES_PER_DAY) segments.push({ start: cursor, end: MINUTES_PER_DAY, period: OFF_PEAK });
+	return segments;
+}
+
+/**
+* The next moment the period actually changes, looking ahead a bounded number of
+* days. Boundaries that leave the period unchanged are stepped over: sitting at
+* 19:00 on a Friday, the answer is Monday 09:00, not the next midnight.
+* @param at - the instant to search from.
+* @param cfg - normalized peak configuration.
+* @param clock - wall-clock parts of `at`.
+* @param current - the period at `at`.
+* @returns `{ at, period }` of the next transition, or null when none is found.
+*/
+function nextTransition(at, cfg, clock, current) {
+	if (cfg.enabled !== true) return null;
+	const millisecondOfSecond = ((at % 1000) + 1000) % 1000;
+	const dayStart = at - (clock.minuteOfDay * 60_000 + clock.secondOfMinute * 1000 + millisecondOfSecond);
+	for (let offset = 0; offset <= LOOKAHEAD_DAYS; offset += 1) {
+		const probe = dayStart + offset * DAY_MS;
+		const parts = wallClock(probe, cfg.timeZone);
+		// Re-derive the day start from the probe rather than assuming 24h days, so a
+		// zone with a DST jump still yields exact minute boundaries.
+		const base = probe - (parts.minuteOfDay * 60_000 + parts.secondOfMinute * 1000);
+		for (const segment of daySegments(cfg, parts.weekday, parts.date)) {
+			const boundary = base + segment.start * 60_000;
+			// The boundary at the start of a segment carries the period that *begins*
+			// there, so only a boundary that changes the period is a transition.
+			if (segment.period === current) continue;
+			if (boundary > at) return { at: boundary, period: segment.period };
+		}
+	}
+	return null;
+}
+
+/**
+* Describe the period of one instant, including why and when it changes.
+* @param epochMs - epoch milliseconds.
+* @param config - plain pool configuration.
+* @returns a JSON-friendly description of the period.
+*/
+export function describePeriod(epochMs, config = {}) {
+	const cfg = normalizePeakConfig(config);
+	const at = Number.isFinite(epochMs) ? epochMs : Date.now();
+	const clock = wallClock(at, cfg.timeZone);
+	const period = periodOfClock(cfg, clock);
+	const next = nextTransition(at, cfg, clock, period);
+	return {
+		period,
+		at,
+		timeZone: cfg.timeZone,
+		date: clock.date,
+		weekday: clock.weekday,
+		minuteOfDay: clock.minuteOfDay,
+		enabled: cfg.enabled,
+		peakDay: isPeakDay(cfg, clock.weekday, clock.date),
+		holiday: cfg.holidays.has(clock.date),
+		makeupWorkday: cfg.makeupWorkdays.has(clock.date),
+		windows: cfg.windows.map((window) => ({ start: window.start, end: window.end, label: window.label })),
+		weekdays: [...cfg.weekdays],
+		nextChangeAt: next === null ? null : next.at,
+		nextPeriod: next === null ? null : next.period,
+	};
+}
+
+/**
+* De-duplicate a list of provider ids, dropping blanks and non-strings.
+* @param raw - configured ids.
+* @returns the ids in first-seen order.
+*/
+function uniqueProviderIds(raw) {
+	const ids = [];
+	for (const entry of Array.isArray(raw) ? raw : []) {
+		if (typeof entry !== "string") continue;
+		const id = entry.trim();
+		if (id === "" || ids.includes(id)) continue;
+		ids.push(id);
+	}
+	return ids;
+}
+
+/**
+* The effective provider ranking for one period.
+*
+* The period's own list wins; providers it omits follow `providerOrder`, and any
+* provider missing from both keeps registration order through `route.priority`
+* (see `order` in `lib/strategies.js`, which places unlisted providers behind the
+* ranking). Returns undefined when the period has no list of its own, which is
+* what keeps the feature inert until it is configured.
+*
+* @param period - `peak` or `offPeak`.
+* @param config - plain pool configuration.
+* @returns an ordered provider id list, or undefined when the ranking is inert.
+*/
+export function priorityRanking(period, config = {}) {
+	const source = config === null || config === undefined ? {} : config;
+	if (source.peakEnabled === false) return undefined;
+	const listed = uniqueProviderIds(period === PEAK ? source.peakProviderOrder : source.offPeakProviderOrder);
+	if (listed.length === 0) return undefined;
+	const ranking = [...listed];
+	for (const id of uniqueProviderIds(source.providerOrder)) {
+		if (!ranking.includes(id)) ranking.push(id);
+	}
+	return ranking;
+}
+
+/**
+* The priority key of one provider under a ranking.
+* Unlisted providers sort behind every listed one, keeping their own
+* `route.priority` order among themselves.
+* @param ranking - effective provider ranking.
+* @param provider - provider id.
+* @param priority - the route's configured priority.
+* @returns the sort key.
+*/
+export function rankOf(ranking, provider, priority) {
+	const listed = Array.isArray(ranking) ? ranking.indexOf(provider) : -1;
+	if (listed >= 0) return listed;
+	return UNRANKED_PRIORITY + (Number.isFinite(priority) ? priority : 0);
+}