@interactive-inc/flume 0.10.0 → 0.10.1

package/dist/time.js

@@ -1,2 +1,621 @@
-import { i as parseCron, r as flumeCronNext, t as FlumeTimeSource } from "./time-source.js";
-export { FlumeTimeSource, flumeCronNext, parseCron };
+import { a as safeNow, c as attempt, i as FlumeLogger, l as safeNormalizeError, o as FlumeStartError, r as safeInvokeCallback, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
+import { t as isRecord } from "./is-record.js";
+//#region lib/time/parse-cron-field.ts
+/**
+* 単一 cron フィールド (minute など) の spec を許可値の Set に展開する。
+* 対応: `*` / `* /n` / `a` / `a-b` / `a-b/n` とそれらのカンマ区切り。名前 (JAN, MON) は非対応。
+* 空トークン (`"5,"` / `"-5"` / `"/5"` など) は `Number("") === 0` の暗黙変換で
+* 0 に化けるため、数値が期待される位置の空文字列は明示的に拒否する
+*/
+function parseCronField(spec, min, max) {
+	const values = /* @__PURE__ */ new Set();
+	for (const part of spec.split(",")) {
+		if (part === "") return new FlumeParseError(`empty cron list segment: "${spec}"`);
+		const expanded = expandCronPart(part, min, max);
+		if (expanded instanceof FlumeParseError) return expanded;
+		for (const value of expanded) values.add(value);
+	}
+	if (values.size === 0) return new FlumeParseError(`cron field empty: "${spec}"`);
+	return values;
+}
+function expandCronPart(part, min, max) {
+	const slash = part.indexOf("/");
+	const range = slash === -1 ? part : part.slice(0, slash);
+	const stepToken = slash === -1 ? null : part.slice(slash + 1);
+	if (stepToken === "") return new FlumeParseError(`invalid cron step: "${part}"`);
+	const step = stepToken === null ? 1 : Number(stepToken);
+	if (!Number.isInteger(step) || step <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
+	const bounds = resolveBounds(range, min, max);
+	if (bounds instanceof FlumeParseError) return bounds;
+	const numbers = [];
+	for (let value = bounds.lo; value <= bounds.hi; value += step) numbers.push(value);
+	return numbers;
+}
+function resolveBounds(range, min, max) {
+	if (range === "*") return {
+		lo: min,
+		hi: max
+	};
+	const dash = range.indexOf("-");
+	const loToken = dash === -1 ? range : range.slice(0, dash);
+	const hiToken = dash === -1 ? loToken : range.slice(dash + 1);
+	if (loToken === "" || hiToken === "") return new FlumeParseError(`invalid cron range: "${range}"`);
+	const lo = Number(loToken);
+	const hi = Number(hiToken);
+	if (!Number.isInteger(lo) || !Number.isInteger(hi)) return new FlumeParseError(`invalid cron range: "${range}"`);
+	if (lo < min || hi > max || lo > hi) return new FlumeParseError(`cron value out of range [${min}-${max}]: "${range}"`);
+	return {
+		lo,
+		hi
+	};
+}
+//#endregion
+//#region lib/time/parse-cron.ts
+/**
+* 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
+*/
+function parseCron(expression) {
+	const trimmed = expression.trim();
+	const fields = trimmed.split(/\s+/);
+	if (fields.length !== 5) return new FlumeParseError(`cron must have 5 fields, got ${fields.length}: "${expression}"`);
+	const minutes = parseCronField(fields[0] ?? "", 0, 59);
+	if (minutes instanceof FlumeParseError) return minutes;
+	const hours = parseCronField(fields[1] ?? "", 0, 23);
+	if (hours instanceof FlumeParseError) return hours;
+	const daysOfMonth = parseCronField(fields[2] ?? "", 1, 31);
+	if (daysOfMonth instanceof FlumeParseError) return daysOfMonth;
+	const months = parseCronField(fields[3] ?? "", 1, 12);
+	if (months instanceof FlumeParseError) return months;
+	const rawDaysOfWeek = parseCronField(fields[4] ?? "", 0, 7);
+	if (rawDaysOfWeek instanceof FlumeParseError) return rawDaysOfWeek;
+	const daysOfWeek = /* @__PURE__ */ new Set();
+	for (const value of rawDaysOfWeek) daysOfWeek.add(value === 7 ? 0 : value);
+	return {
+		source: trimmed,
+		minutes,
+		hours,
+		daysOfMonth,
+		months,
+		daysOfWeek,
+		domRestricted: !fields[2]?.includes("*"),
+		dowRestricted: !fields[4]?.includes("*")
+	};
+}
+//#endregion
+//#region lib/time/cron-next.ts
+const MINUTE_MS$1 = 6e4;
+const MAX_ITERATIONS = 5e5;
+/**
+* `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
+* 到達不能なら FlumeParseError を返す
+*/
+function flumeCronNext(cron, afterMs) {
+	let candidate = Math.floor(afterMs / MINUTE_MS$1) * MINUTE_MS$1 + MINUTE_MS$1;
+	for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+		const date = new Date(candidate);
+		if (!cron.months.has(date.getMonth() + 1)) {
+			candidate = new Date(date.getFullYear(), date.getMonth() + 1, 1, 0, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!matchesDay(cron, date)) {
+			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1, 0, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!cron.hours.has(date.getHours())) {
+			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours() + 1, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!cron.minutes.has(date.getMinutes())) {
+			candidate += MINUTE_MS$1;
+			continue;
+		}
+		return candidate;
+	}
+	return new FlumeParseError(`cron "${cron.source}" has no next time within bound`);
+}
+function matchesDay(cron, date) {
+	const domMatch = cron.daysOfMonth.has(date.getDate());
+	const dowMatch = cron.daysOfWeek.has(date.getDay());
+	if (cron.domRestricted && cron.dowRestricted) return domMatch || dowMatch;
+	return domMatch && dowMatch;
+}
+//#endregion
+//#region lib/time/is-dst-duplicate-fire.ts
+const DEDUP_WINDOW_MS = 7200 * 1e3;
+/**
+* DST fall-back では同一壁時計分 (y/m/d/h/min) が 2 つの epoch に存在し、
+* 分単位の epoch ウォークが両方にマッチして二重発火する。fire 直後に計算した
+* 次ターゲットが直近 2 時間の fire のいずれかと同じ壁時計分なら重複と判定する。
+* 複数分にマッチする cron では巻き戻し後の最初の時刻と直前 fire の分が異なるため、
+* 直前 1 件でなく履歴を受け取る
+*/
+function isDstDuplicateFire(firedTimes, nextTarget) {
+	for (let index = firedTimes.length - 1; index >= 0; index--) {
+		const firedAt = firedTimes[index];
+		if (firedAt === void 0) continue;
+		if (nextTarget <= firedAt) continue;
+		if (nextTarget - firedAt > DEDUP_WINDOW_MS) return false;
+		if (hasSameLocalMinute(firedAt, nextTarget)) return true;
+	}
+	return false;
+}
+function hasSameLocalMinute(firedAt, nextTarget) {
+	const fired = new Date(firedAt);
+	const next = new Date(nextTarget);
+	if (fired.getFullYear() !== next.getFullYear()) return false;
+	if (fired.getMonth() !== next.getMonth()) return false;
+	if (fired.getDate() !== next.getDate()) return false;
+	if (fired.getHours() !== next.getHours()) return false;
+	return fired.getMinutes() === next.getMinutes();
+}
+//#endregion
+//#region lib/time/time-scheduler.ts
+const MAX_TIMEOUT_MS = 2e9;
+const FIRE_TOLERANCE_MS = 1e3;
+const DST_HISTORY_WINDOW_MS = 7200 * 1e3;
+const MAX_DST_SKIPS = 180;
+/**
+* cron に従って `onTick` を駆動するタイマーループ。外部接続を持たないため reconnect 不要。
+* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない。
+* sleep-wake で複数回分を取り逃した場合は 1 回だけ発火して now まで早送りする
+* (取り逃しは `scheduler.skipped` info で観測可能)
+*/
+var FlumeTimeScheduler = class {
+	props;
+	log;
+	isStoppedFlag = false;
+	timer = null;
+	target = 0;
+	recentFires = [];
+	constructor(props) {
+		this.props = props;
+		this.log = new FlumeLogger({
+			source: "time.scheduler",
+			handler: props.onLog,
+			deps: props.deps
+		});
+	}
+	get isStopped() {
+		return this.isStoppedFlag;
+	}
+	/**
+	* `fromMs` より後の最初のマッチを狙う。catchup と同じ基準時刻を共有できるよう
+	* 呼び出し側から 1 つのタイムスタンプを渡す (未指定なら now)
+	*/
+	start(fromMs) {
+		const basis = fromMs ?? safeNow({ deps: this.props.deps });
+		const next = flumeCronNext(this.props.cron, basis);
+		if (next instanceof FlumeParseError) {
+			this.log.error({
+				action: "cron.no-next",
+				message: next.message,
+				error: next
+			});
+			return next;
+		}
+		this.target = next;
+		this.log.info({
+			action: "scheduler.start",
+			message: `next fire at ${new Date(next).toISOString()}`,
+			detail: { target: next }
+		});
+		return this.arm();
+	}
+	stop() {
+		this.isStoppedFlag = true;
+		this.clearTimer();
+	}
+	arm() {
+		if (this.isStoppedFlag) return null;
+		this.clearTimer();
+		const delay = Math.max(0, this.target - safeNow({ deps: this.props.deps }));
+		const capped = Math.min(delay, MAX_TIMEOUT_MS);
+		const result = attempt(() => this.props.deps.setTimeout(() => this.onWake(), capped));
+		if (result instanceof Error) {
+			this.log.error({
+				action: "scheduler.arm.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			this.timer = null;
+			this.isStoppedFlag = true;
+			return result;
+		}
+		this.timer = result;
+		return null;
+	}
+	onWake() {
+		this.timer = null;
+		if (this.isStoppedFlag) return;
+		if (this.target - safeNow({ deps: this.props.deps }) > FIRE_TOLERANCE_MS) {
+			const error = this.arm();
+			if (error instanceof Error) this.halt(error);
+			return;
+		}
+		const firedAt = this.target;
+		this.rememberFire(firedAt);
+		safeInvokeCallback({
+			fn: () => this.props.onTick(firedAt),
+			onError: (error) => {
+				this.log.error({
+					action: "scheduler.tick.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+		if (this.isStoppedFlag) return;
+		this.advanceAfterFire(firedAt);
+	}
+	/**
+	* fire 後の次ターゲット計算。sleep 明けで firedAt が過去に沈んでいる場合は
+	* now まで早送りして取り逃し分の replay burst を防ぐ (catchup は opt-in の別機構)
+	*/
+	advanceAfterFire(firedAt) {
+		const nowMs = safeNow({ deps: this.props.deps });
+		const firstAfterFired = flumeCronNext(this.props.cron, firedAt);
+		if (firstAfterFired instanceof FlumeParseError) {
+			this.halt(firstAfterFired);
+			return;
+		}
+		if (firstAfterFired <= nowMs) this.log.info({
+			action: "scheduler.skipped",
+			message: `late wake: skipped occurrence(s) between ${new Date(firedAt).toISOString()} and now`,
+			detail: {
+				latenessMs: nowMs - firedAt,
+				firedAt
+			}
+		});
+		const next = firstAfterFired > nowMs ? firstAfterFired : flumeCronNext(this.props.cron, nowMs);
+		if (next instanceof FlumeParseError) {
+			this.halt(next);
+			return;
+		}
+		const deduped = this.skipDstDuplicates(next);
+		if (deduped instanceof FlumeParseError) {
+			this.halt(deduped);
+			return;
+		}
+		this.target = deduped;
+		const armError = this.arm();
+		if (armError instanceof Error) this.halt(armError);
+	}
+	/** cron エラーによる恒久停止。source が接続済みのまま沈黙しないよう onHalt で通知する */
+	halt(error) {
+		this.isStoppedFlag = true;
+		this.clearTimer();
+		this.log.error({
+			action: "scheduler.halted",
+			message: error.message,
+			error
+		});
+		const onHalt = this.props.onHalt;
+		if (!onHalt) return;
+		safeInvokeCallback({
+			fn: () => onHalt(),
+			onError: (haltError) => {
+				this.log.error({
+					action: "scheduler.halt.error",
+					message: safeErrorMessage({ error: haltError }),
+					error: haltError
+				});
+			}
+		});
+	}
+	rememberFire(firedAt) {
+		this.recentFires.push(firedAt);
+		const cutoff = firedAt - DST_HISTORY_WINDOW_MS;
+		while (this.recentFires[0] !== void 0 && this.recentFires[0] < cutoff) this.recentFires.shift();
+	}
+	skipDstDuplicates(initialTarget) {
+		let target = initialTarget;
+		for (let iteration = 0; iteration < MAX_DST_SKIPS; iteration++) {
+			if (!isDstDuplicateFire(this.recentFires, target)) return target;
+			const next = flumeCronNext(this.props.cron, target);
+			if (next instanceof FlumeParseError) return next;
+			target = next;
+		}
+		return new FlumeParseError(`cron "${this.props.cron.source}" exceeded DST duplicate bound`);
+	}
+	clearTimer() {
+		if (this.timer === null) return;
+		const handle = this.timer;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "scheduler.timer.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+		this.timer = null;
+	}
+};
+//#endregion
+//#region lib/time/time-catchup.ts
+const DEFAULT_MISSED_WINDOW_MS = 1440 * 60 * 1e3;
+const MAX_CATCHUP_MATCHES = 1e4;
+const MINUTE_MS = 6e4;
+/**
+* `lastFiredAt` から `now` までに過ぎ去った cron マッチを policy に従って列挙する。
+*
+* - policy.mode === "off"      : 常に空
+* - policy.mode === "lastOnly" : 過ぎ去ったマッチの中で最も新しいもの 1 件 (件数上限なし・O(1) メモリ)
+* - policy.mode === "missed"   : maxWindowMs (既定 24h) 以内に過ぎ去ったすべてのマッチ。
+*                                window の起点は `max(lastFiredAt, now - maxWindowMs)`。
+*                                10,000 件を超えた場合は古い方を捨てて新しい 10,000 件を返し
+*                                truncated: true で通知する
+*
+* 到達不能 cron や catastrophic な policy ミス指定の場合は FlumeParseError を返す
+* (catchup 列挙だけで失敗させる。source 本体の起動は別判断)
+*/
+function flumeCollectCatchupMatches(props) {
+	const policy = props.policy;
+	if (policy.mode === "off") return {
+		matches: [],
+		truncated: false
+	};
+	if (props.lastFiredAt >= props.now) return {
+		matches: [],
+		truncated: false
+	};
+	if (policy.mode === "lastOnly") return collectLastOnly({
+		cron: props.cron,
+		windowStart: props.lastFiredAt,
+		now: props.now
+	});
+	const windowStart = Math.max(props.lastFiredAt, props.now - (policy.maxWindowMs ?? DEFAULT_MISSED_WINDOW_MS));
+	return collectMissed({
+		cron: props.cron,
+		windowStart,
+		now: props.now
+	});
+}
+function collectLastOnly(props) {
+	let lookbackMs = MINUTE_MS;
+	while (true) {
+		const recentStart = Math.max(props.windowStart, props.now - lookbackMs);
+		const walked = walkMatches({
+			...props,
+			windowStart: recentStart
+		});
+		if (walked instanceof FlumeParseError) return walked;
+		const latest = walked[walked.length - 1];
+		if (latest !== void 0) return {
+			matches: [latest],
+			truncated: false
+		};
+		if (recentStart === props.windowStart) return {
+			matches: [],
+			truncated: false
+		};
+		lookbackMs *= 2;
+	}
+}
+function collectMissed(props) {
+	let lookbackMs = MAX_CATCHUP_MATCHES * MINUTE_MS;
+	while (true) {
+		const recentStart = Math.max(props.windowStart, props.now - lookbackMs);
+		const walked = walkMatches({
+			...props,
+			windowStart: recentStart
+		});
+		if (walked instanceof FlumeParseError) return walked;
+		if (walked.length >= MAX_CATCHUP_MATCHES || recentStart === props.windowStart) {
+			const matches = walked.slice(Math.max(0, walked.length - MAX_CATCHUP_MATCHES));
+			const older = hasMatchBefore(props.cron, props.windowStart, recentStart);
+			if (older instanceof FlumeParseError) return older;
+			return {
+				matches,
+				truncated: walked.length > MAX_CATCHUP_MATCHES || older
+			};
+		}
+		lookbackMs *= 2;
+	}
+}
+function walkMatches(props) {
+	const matches = [];
+	let cursor = props.windowStart;
+	while (true) {
+		const next = flumeCronNext(props.cron, cursor);
+		if (next instanceof FlumeParseError) return next;
+		if (next > props.now) return matches;
+		if (!isDstDuplicateFire(matches, next)) matches.push(next);
+		cursor = next;
+	}
+}
+function hasMatchBefore(cron, windowStart, recentStart) {
+	if (recentStart === windowStart) return false;
+	const first = flumeCronNext(cron, windowStart);
+	if (first instanceof FlumeParseError) return first;
+	return first <= recentStart;
+}
+//#endregion
+//#region lib/time/time-source.ts
+/**
+* cron スケジュールで tick を emit する Source。外部接続を持たないため
+* 起動成功と同時に `connected` になり reconnect の対象外。
+*
+* options.statePersister + options.catchupPolicy を渡すと:
+*  1. 起動時に lastFiredAt を読み出す
+*  2. lastFiredAt から now までの過ぎ去った cron マッチを policy に従って再発火する
+*  3. 各 tick 後に lastFiredAt を保存する (best-effort, ブロックしない)
+*
+* 保存先や形式は flume の関知ではなく statePersister の実装が決める (純粋 DI)。
+*
+* DST 制限: fall-back (時計の巻き戻し) の二重発火は dedup で防ぐが、spring-forward
+* (時計の飛び越し) でスキップされた壁時計時刻 (例: 02:30 が存在しない日) にスケジュール
+* された job はその日は実行されない。cron は壁時計 (local time) 基準のため仕様とする
+*/
+var FlumeTimeSource = class extends FlumeSource {
+	options;
+	name = "time";
+	scheduler = null;
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	async connect(ctx) {
+		this.setStatus("connecting");
+		const cron = parseCron(this.options.cron);
+		if (cron instanceof FlumeParseError) {
+			const error = new FlumeStartError(`Time source: invalid cron "${this.options.cron}": ${cron.message}`);
+			ctx.log.error({
+				action: "source.start.failed",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			this.setStatus("disconnected", error.message);
+			return error;
+		}
+		const persister = this.options.statePersister ?? null;
+		const lastFiredAt = persister === null ? null : await this.loadLastFiredAt(ctx, persister);
+		this.scheduler = new FlumeTimeScheduler({
+			cron,
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onTick: (firedAt) => this.handleTick(ctx, firedAt, persister),
+			onHalt: () => this.handleSchedulerHalt(ctx)
+		});
+		const startedAt = safeNow({ deps: ctx.deps });
+		const result = this.scheduler.start(startedAt);
+		if (result instanceof Error) {
+			const error = new FlumeStartError(`Time source: ${safeErrorMessage({ error: result })}`);
+			this.setStatus("disconnected", error.message);
+			return error;
+		}
+		this.setStatus("connected");
+		if (lastFiredAt !== null && persister !== null) this.runCatchup({
+			ctx,
+			cron,
+			lastFiredAt,
+			persister,
+			now: startedAt
+		});
+		return null;
+	}
+	disconnect() {
+		this.scheduler?.stop();
+		this.scheduler = null;
+	}
+	handleTick(ctx, firedAt, persister) {
+		this.emitTick(ctx, firedAt);
+		if (persister !== null) this.saveLastFiredAt(ctx, persister, firedAt);
+	}
+	emitTick(ctx, firedAt) {
+		const tick = {
+			firedAt,
+			cron: this.options.cron
+		};
+		const custom = this.safeMessage(ctx, tick);
+		this.emit({
+			source: "time",
+			type: typeof custom.type === "string" ? custom.type : "tick",
+			data: isRecord(custom.data) ? custom.data : {
+				firedAt,
+				cron: this.options.cron
+			},
+			meta: this.normalizeMeta(custom.meta, this.options.cron),
+			receivedAt: safeNow({ deps: ctx.deps })
+		});
+	}
+	runCatchup(props) {
+		const policy = this.options.catchupPolicy ?? { mode: "off" };
+		if (policy.mode === "off") return;
+		const collected = flumeCollectCatchupMatches({
+			cron: props.cron,
+			lastFiredAt: props.lastFiredAt,
+			now: props.now,
+			policy
+		});
+		if (collected instanceof FlumeParseError) {
+			props.ctx.log.warn({
+				action: "time.catchup.failed",
+				message: collected.message,
+				error: collected
+			});
+			return;
+		}
+		if (collected.truncated) props.ctx.log.warn({
+			action: "time.catchup.truncated",
+			message: "catchup exceeded the match cap; oldest missed tick(s) were dropped",
+			detail: {
+				kept: collected.matches.length,
+				policy: policy.mode
+			}
+		});
+		const matches = collected.matches;
+		if (matches.length === 0) return;
+		props.ctx.log.info({
+			action: "time.catchup.fired",
+			message: `catchup ${matches.length} missed tick(s) since ${new Date(props.lastFiredAt).toISOString()}`,
+			detail: {
+				count: matches.length,
+				policy: policy.mode
+			}
+		});
+		for (const firedAt of matches) this.emitTick(props.ctx, firedAt);
+		const last = matches[matches.length - 1];
+		if (last !== void 0) this.saveLastFiredAt(props.ctx, props.persister, last);
+	}
+	/** スケジューラが cron エラーで恒久停止した (dead-but-green を防ぐため接続状態を落とす) */
+	handleSchedulerHalt(ctx) {
+		ctx.log.error({
+			action: "time.scheduler.halted",
+			message: "scheduler halted due to cron error; time source will not tick again"
+		});
+		this.setStatus("disconnected", "scheduler halted");
+	}
+	async loadLastFiredAt(ctx, persister) {
+		const result = await attempt(() => persister.load());
+		if (result instanceof Error) {
+			ctx.log.warn({
+				action: "time.state.load.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			return null;
+		}
+		if (result === null) return null;
+		if (typeof result.lastFiredAt !== "number" || !Number.isFinite(result.lastFiredAt)) return null;
+		return result.lastFiredAt;
+	}
+	saveLastFiredAt(ctx, persister, lastFiredAt) {
+		safeInvokeCallback({
+			fn: () => persister.save({ lastFiredAt }),
+			onError: (error) => {
+				ctx.log.warn({
+					action: "time.state.save.error",
+					message: safeErrorMessage({ error: safeNormalizeError({ value: error }) }),
+					error
+				});
+			}
+		});
+	}
+	safeMessage(ctx, tick) {
+		const message = this.options.message;
+		if (!message) return {};
+		const result = attempt(() => message(tick));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
+			ctx.log.warn({
+				action: "message.error",
+				message: safeErrorMessage({ error }),
+				error,
+				detail: { firedAt: tick.firedAt }
+			});
+			return {};
+		}
+		return isRecord(result) ? result : {};
+	}
+	normalizeMeta(meta, cron) {
+		if (!isRecord(meta)) return { cron };
+		const normalized = {};
+		for (const key of Object.keys(meta)) {
+			const value = meta[key];
+			if (typeof value === "string") normalized[key] = value;
+		}
+		if (Object.keys(normalized).length === 0) return { cron };
+		return normalized;
+	}
+};
+//#endregion
+export { FlumeTimeSource, flumeCollectCatchupMatches, flumeCronNext, parseCron };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/flume",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + fetch + Zod. No SDK dependencies.",
   "keywords": [
     "discord",

package/dist/parse-cron.d.ts

@@ -1,55 +0,0 @@
-import { D as FlumeSourceStartContext, L as FlumeTimeSourceOptions, t as FlumeSource } from "./flume-source.js";
-
-//#region lib/errors/parse-error.d.ts
-type Options = {
-  cause?: unknown;
-};
-declare class FlumeParseError extends Error {
-  constructor(message: string, options?: Options);
-}
-//#endregion
-//#region lib/time/time-source.d.ts
-/**
- * cron スケジュールで tick を emit する Source。外部接続を持たないため
- * 起動成功と同時に `connected` になり reconnect の対象外。
- *
- * options.statePersister + options.catchupPolicy を渡すと:
- *  1. 起動時に lastFiredAt を読み出す
- *  2. lastFiredAt から now までの過ぎ去った cron マッチを policy に従って再発火する
- *  3. 各 tick 後に lastFiredAt を保存する (best-effort, ブロックしない)
- *
- * 保存先や形式は flume の関知ではなく statePersister の実装が決める (純粋 DI)
- */
-declare class FlumeTimeSource extends FlumeSource {
-  private readonly options;
-  readonly name: "time";
-  private scheduler;
-  constructor(options: FlumeTimeSourceOptions);
-  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
-  protected disconnect(): void;
-  private handleTick;
-  private emitTick;
-  private runCatchup;
-  private loadLastFiredAt;
-  private saveLastFiredAt;
-  private safeMessage;
-  private normalizeMeta;
-}
-//#endregion
-//#region lib/time/parse-cron.d.ts
-type FlumeCron = {
-  source: string;
-  minutes: ReadonlySet<number>;
-  hours: ReadonlySet<number>;
-  daysOfMonth: ReadonlySet<number>;
-  months: ReadonlySet<number>;
-  daysOfWeek: ReadonlySet<number>; /** day-of-month フィールドが `*` 以外か。dow と両方制限時は OR マッチ (標準 cron 準拠) */
-  domRestricted: boolean;
-  dowRestricted: boolean;
-};
-/**
- * 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
- */
-declare function parseCron(expression: string): FlumeCron | FlumeParseError;
-//#endregion
-export { FlumeParseError as i, parseCron as n, FlumeTimeSource as r, FlumeCron as t };