@interactive-inc/flume 0.6.0 → 0.9.0

package/dist/time.d.ts

@@ -0,0 +1,45 @@
+import { N as FlumeTimeSourceOptions, t as FlumeSource, w as FlumeSourceStartContext } from "./flume-source.js";
+import { t as FlumeParseError } from "./parse-error.js";
+
+//#region lib/time/time-source.d.ts
+/**
+ * cron スケジュールで tick を emit する Source。外部接続を持たないため
+ * 起動成功と同時に `connected` になり reconnect の対象外。
+ * `options.message` で tick ごとの type / data / meta を上書きできる
+ */
+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 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
+//#region lib/time/cron-next.d.ts
+/**
+ * `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
+ * 到達不能なら FlumeParseError を返す
+ */
+declare function flumeCronNext(cron: FlumeCron, afterMs: number): number | FlumeParseError;
+//#endregion
+export { type FlumeCron, FlumeTimeSource, flumeCronNext, parseCron };

package/dist/time.js

@@ -0,0 +1,319 @@
+import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } 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) は非対応
+*/
+function parseCronField(spec, min, max) {
+	const values = /* @__PURE__ */ new Set();
+	for (const part of spec.split(",")) {
+		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) {
+	let range = part;
+	let step = 1;
+	const slash = part.indexOf("/");
+	if (slash !== -1) {
+		range = part.slice(0, slash);
+		const parsed = Number(part.slice(slash + 1));
+		if (!Number.isInteger(parsed) || parsed <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
+		step = parsed;
+	}
+	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 lo = dash === -1 ? Number(range) : Number(range.slice(0, dash));
+	const hi = dash === -1 ? lo : Number(range.slice(dash + 1));
+	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] !== "*",
+		dowRestricted: fields[4] !== "*"
+	};
+}
+//#endregion
+//#region lib/time/cron-next.ts
+const MINUTE_MS = 6e4;
+const MAX_ITERATIONS = 5e5;
+/**
+* `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
+* 到達不能なら FlumeParseError を返す
+*/
+function flumeCronNext(cron, afterMs) {
+	let candidate = Math.floor(afterMs / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
+	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;
+			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;
+	if (cron.domRestricted) return domMatch;
+	if (cron.dowRestricted) return dowMatch;
+	return true;
+}
+//#endregion
+//#region lib/time/time-scheduler.ts
+const MAX_TIMEOUT_MS = 2e9;
+const FIRE_TOLERANCE_MS = 1e3;
+/**
+* cron に従って `onTick` を駆動するタイマーループ。外部接続を持たないため reconnect 不要。
+* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない
+*/
+var FlumeTimeScheduler = class {
+	props;
+	log;
+	isStoppedFlag = false;
+	timer = null;
+	target = 0;
+	constructor(props) {
+		this.props = props;
+		this.log = new FlumeLogger({
+			source: "time.scheduler",
+			handler: props.onLog,
+			deps: props.deps
+		});
+	}
+	get isStopped() {
+		return this.isStoppedFlag;
+	}
+	start() {
+		const next = flumeCronNext(this.props.cron, safeNow({ deps: this.props.deps }));
+		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 }
+		});
+		this.arm();
+		return null;
+	}
+	stop() {
+		this.isStoppedFlag = true;
+		this.clearTimer();
+	}
+	arm() {
+		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;
+			return;
+		}
+		this.timer = result;
+	}
+	onWake() {
+		this.timer = null;
+		if (this.isStoppedFlag) return;
+		if (this.target - safeNow({ deps: this.props.deps }) > FIRE_TOLERANCE_MS) {
+			this.arm();
+			return;
+		}
+		const firedAt = this.target;
+		safeInvokeCallback({
+			fn: () => this.props.onTick(firedAt),
+			onError: (error) => {
+				this.log.error({
+					action: "scheduler.tick.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+		const next = flumeCronNext(this.props.cron, firedAt);
+		if (next instanceof FlumeParseError) {
+			this.log.error({
+				action: "cron.no-next",
+				message: next.message,
+				error: next
+			});
+			return;
+		}
+		this.target = next;
+		this.arm();
+	}
+	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-source.ts
+/**
+* cron スケジュールで tick を emit する Source。外部接続を持たないため
+* 起動成功と同時に `connected` になり reconnect の対象外。
+* `options.message` で tick ごとの type / data / meta を上書きできる
+*/
+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;
+		}
+		this.scheduler = new FlumeTimeScheduler({
+			cron,
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onTick: (firedAt) => this.handleTick(ctx, firedAt)
+		});
+		const result = this.scheduler.start();
+		if (result instanceof Error) {
+			const error = new FlumeStartError(`Time source: ${safeErrorMessage({ error: result })}`);
+			this.setStatus("disconnected", error.message);
+			return error;
+		}
+		this.setStatus("connected");
+		return null;
+	}
+	disconnect() {
+		this.scheduler?.stop();
+		this.scheduler = null;
+	}
+	handleTick(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 })
+		});
+	}
+	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, flumeCronNext, parseCron };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/flume",
-  "version": "0.6.0",
+  "version": "0.9.0",
   "description": "Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + fetch + Zod. No SDK dependencies.",
   "keywords": [
     "discord",
@@ -54,6 +54,11 @@
       "import": "./dist/github.js",
       "default": "./dist/github.js"
     },
+    "./time": {
+      "types": "./dist/time.d.ts",
+      "import": "./dist/time.js",
+      "default": "./dist/time.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {