refactor progress

packages/time/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "@fluxer/time",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsgo --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "catalog:",
+		"@typescript/native-preview": "catalog:",
+		"vite-tsconfig-paths": "catalog:",
+		"vitest": "catalog:"
+	}
+}

packages/time/src/Clock.tsx

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export interface IClock {
+	nowMs(): number;
+}
+
+export const SystemClock: IClock = {
+	nowMs(): number {
+		return Date.now();
+	},
+};
+
+export function nowMs(clock: IClock = SystemClock): number {
+	return clock.nowMs();
+}

packages/time/src/DelayMath.tsx

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export interface DelayRange {
+	fromMs: number;
+	toMs: number;
+}
+
+export function computeRemainingDelayMs(range: DelayRange): number {
+	const delayMs = range.toMs - range.fromMs;
+
+	if (!Number.isFinite(delayMs)) {
+		throw new Error(`Invalid delay range: fromMs=${range.fromMs}, toMs=${range.toMs}`);
+	}
+
+	return Math.max(0, delayMs);
+}

packages/time/src/ExponentialBackoff.tsx

@@ -0,0 +1,81 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export interface ExponentialBackoffPolicy {
+	baseSeconds: number;
+	minimumSeconds: number;
+	maximumSeconds: number;
+	maxExponent: number;
+}
+
+export interface ExponentialBackoffInput {
+	attemptCount: number;
+	policy?: ExponentialBackoffPolicy;
+}
+
+export const DefaultExponentialBackoffPolicy: ExponentialBackoffPolicy = {
+	baseSeconds: 1,
+	minimumSeconds: 1,
+	maximumSeconds: 600,
+	maxExponent: 30,
+};
+
+function normalizeAttemptCount(attemptCount: number): number {
+	if (!Number.isFinite(attemptCount)) {
+		return 0;
+	}
+
+	return Math.max(0, Math.floor(attemptCount));
+}
+
+function validateExponentialBackoffPolicy(policy: ExponentialBackoffPolicy): void {
+	if (!Number.isFinite(policy.baseSeconds) || policy.baseSeconds <= 0) {
+		throw new Error(`Invalid exponential backoff baseSeconds: ${policy.baseSeconds}`);
+	}
+
+	if (!Number.isFinite(policy.minimumSeconds) || policy.minimumSeconds <= 0) {
+		throw new Error(`Invalid exponential backoff minimumSeconds: ${policy.minimumSeconds}`);
+	}
+
+	if (!Number.isFinite(policy.maximumSeconds) || policy.maximumSeconds <= 0) {
+		throw new Error(`Invalid exponential backoff maximumSeconds: ${policy.maximumSeconds}`);
+	}
+
+	if (policy.maximumSeconds < policy.minimumSeconds) {
+		throw new Error(
+			`Invalid exponential backoff policy: maximumSeconds(${policy.maximumSeconds}) is smaller than minimumSeconds(${policy.minimumSeconds})`,
+		);
+	}
+
+	if (!Number.isFinite(policy.maxExponent) || policy.maxExponent < 0) {
+		throw new Error(`Invalid exponential backoff maxExponent: ${policy.maxExponent}`);
+	}
+}
+
+export function computeExponentialBackoffSeconds(input: ExponentialBackoffInput): number {
+	const policy = input.policy ?? DefaultExponentialBackoffPolicy;
+	validateExponentialBackoffPolicy(policy);
+
+	const normalizedAttemptCount = normalizeAttemptCount(input.attemptCount);
+	const exponent = Math.min(normalizedAttemptCount, Math.floor(policy.maxExponent));
+	const backoffSeconds = policy.baseSeconds * 2 ** exponent;
+	const cappedBackoffSeconds = Math.min(backoffSeconds, policy.maximumSeconds);
+
+	return Math.max(cappedBackoffSeconds, policy.minimumSeconds);
+}

packages/time/src/Rfc3339Timestamp.tsx

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+function createInvalidRfc3339TimestampError(timestamp: string): Error {
+	return new Error(`Invalid RFC3339 timestamp: ${timestamp}`);
+}
+
+export function parseRfc3339TimestampToMs(timestamp: string): number {
+	const date = new Date(timestamp);
+	const parsedTimestampMs = date.getTime();
+
+	if (!Number.isFinite(parsedTimestampMs)) {
+		throw createInvalidRfc3339TimestampError(timestamp);
+	}
+
+	return parsedTimestampMs;
+}
+
+export function formatRfc3339Timestamp(timestampMs: number): string {
+	if (!Number.isFinite(timestampMs)) {
+		throw new Error(`Invalid timestamp milliseconds: ${timestampMs}`);
+	}
+
+	return new Date(timestampMs).toISOString();
+}

packages/time/src/Sleep.tsx

@@ -0,0 +1,28 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+export function sleepMs(durationMs: number): Promise<void> {
+	if (!Number.isFinite(durationMs)) {
+		throw new Error(`Invalid sleep duration milliseconds: ${durationMs}`);
+	}
+
+	return new Promise((resolve) => {
+		setTimeout(resolve, Math.max(0, durationMs));
+	});
+}

packages/time/src/tests/Clock.test.tsx

@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type {IClock} from '@fluxer/time/src/Clock';
+import {nowMs} from '@fluxer/time/src/Clock';
+import {describe, expect, it} from 'vitest';
+
+describe('nowMs', () => {
+	it('returns the current time in milliseconds by default', () => {
+		const before = Date.now();
+		const value = nowMs();
+		const after = Date.now();
+
+		expect(value).toBeGreaterThanOrEqual(before);
+		expect(value).toBeLessThanOrEqual(after);
+	});
+
+	it('reads time from the provided clock', () => {
+		const fixedClock: IClock = {
+			nowMs(): number {
+				return 1735732800000;
+			},
+		};
+
+		expect(nowMs(fixedClock)).toBe(1735732800000);
+	});
+});

packages/time/src/tests/DelayMath.test.tsx

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {computeRemainingDelayMs} from '@fluxer/time/src/DelayMath';
+import {describe, expect, it} from 'vitest';
+
+describe('computeRemainingDelayMs', () => {
+	it('returns a positive delay when the deadline is in the future', () => {
+		expect(
+			computeRemainingDelayMs({
+				fromMs: 1000,
+				toMs: 5000,
+			}),
+		).toBe(4000);
+	});
+
+	it('returns zero when the deadline has passed', () => {
+		expect(
+			computeRemainingDelayMs({
+				fromMs: 5000,
+				toMs: 1000,
+			}),
+		).toBe(0);
+	});
+
+	it('throws when the range computes to a non-finite number', () => {
+		expect(() =>
+			computeRemainingDelayMs({
+				fromMs: Number.POSITIVE_INFINITY,
+				toMs: 1000,
+			}),
+		).toThrow('Invalid delay range: fromMs=Infinity, toMs=1000');
+	});
+});

packages/time/src/tests/ExponentialBackoff.test.tsx

@@ -0,0 +1,67 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {computeExponentialBackoffSeconds, DefaultExponentialBackoffPolicy} from '@fluxer/time/src/ExponentialBackoff';
+import {describe, expect, it} from 'vitest';
+
+describe('computeExponentialBackoffSeconds', () => {
+	it('computes exponential backoff with the default policy', () => {
+		expect(computeExponentialBackoffSeconds({attemptCount: 0})).toBe(1);
+		expect(computeExponentialBackoffSeconds({attemptCount: 1})).toBe(2);
+		expect(computeExponentialBackoffSeconds({attemptCount: 2})).toBe(4);
+		expect(computeExponentialBackoffSeconds({attemptCount: 9})).toBe(512);
+	});
+
+	it('caps the backoff with the default maximum', () => {
+		expect(computeExponentialBackoffSeconds({attemptCount: 10})).toBe(600);
+		expect(computeExponentialBackoffSeconds({attemptCount: 100})).toBe(600);
+	});
+
+	it('normalizes invalid attempt values', () => {
+		expect(computeExponentialBackoffSeconds({attemptCount: -3})).toBe(1);
+		expect(computeExponentialBackoffSeconds({attemptCount: Number.NaN})).toBe(1);
+	});
+
+	it('accepts custom policies', () => {
+		expect(
+			computeExponentialBackoffSeconds({
+				attemptCount: 4,
+				policy: {
+					...DefaultExponentialBackoffPolicy,
+					baseSeconds: 3,
+					maximumSeconds: 25,
+				},
+			}),
+		).toBe(25);
+	});
+
+	it('throws when policy values are invalid', () => {
+		expect(() =>
+			computeExponentialBackoffSeconds({
+				attemptCount: 1,
+				policy: {
+					baseSeconds: 1,
+					minimumSeconds: 10,
+					maximumSeconds: 5,
+					maxExponent: 30,
+				},
+			}),
+		).toThrow('Invalid exponential backoff policy: maximumSeconds(5) is smaller than minimumSeconds(10)');
+	});
+});

packages/time/src/tests/Rfc3339Timestamp.test.tsx

@@ -0,0 +1,61 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {formatRfc3339Timestamp, parseRfc3339TimestampToMs} from '@fluxer/time/src/Rfc3339Timestamp';
+import {describe, expect, it} from 'vitest';
+
+describe('parseRfc3339TimestampToMs', () => {
+	it('parses a valid timestamp', () => {
+		const timestamp = '2024-06-15T12:30:45.000Z';
+		const result = parseRfc3339TimestampToMs(timestamp);
+		expect(result).toBe(new Date(timestamp).getTime());
+	});
+
+	it('parses timestamps with timezone offsets', () => {
+		const timestamp = '2024-06-15T12:30:45+05:30';
+		const result = parseRfc3339TimestampToMs(timestamp);
+		expect(result).toBe(new Date(timestamp).getTime());
+	});
+
+	it('throws for invalid timestamps', () => {
+		expect(() => parseRfc3339TimestampToMs('not-a-date')).toThrow('Invalid RFC3339 timestamp: not-a-date');
+	});
+});
+
+describe('formatRfc3339Timestamp', () => {
+	it('formats milliseconds as RFC3339', () => {
+		expect(formatRfc3339Timestamp(1718454645000)).toBe('2024-06-15T12:30:45.000Z');
+	});
+
+	it('preserves millisecond precision', () => {
+		expect(formatRfc3339Timestamp(1718454645123)).toBe('2024-06-15T12:30:45.123Z');
+	});
+
+	it('throws for non-finite inputs', () => {
+		expect(() => formatRfc3339Timestamp(Number.NaN)).toThrow('Invalid timestamp milliseconds: NaN');
+	});
+
+	it('roundtrips with parser', () => {
+		const originalTimestampMs = 1718451045500;
+		const timestamp = formatRfc3339Timestamp(originalTimestampMs);
+		const parsedTimestampMs = parseRfc3339TimestampToMs(timestamp);
+
+		expect(parsedTimestampMs).toBe(originalTimestampMs);
+	});
+});

packages/time/src/tests/Sleep.test.tsx

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {sleepMs} from '@fluxer/time/src/Sleep';
+import {describe, expect, it} from 'vitest';
+
+describe('sleepMs', () => {
+	it('resolves after approximately the provided duration', async () => {
+		const startMs = Date.now();
+		await sleepMs(50);
+		const elapsedMs = Date.now() - startMs;
+
+		expect(elapsedMs).toBeGreaterThanOrEqual(45);
+		expect(elapsedMs).toBeLessThan(150);
+	});
+
+	it('clamps negative durations to zero', async () => {
+		const startMs = Date.now();
+		await sleepMs(-10);
+		const elapsedMs = Date.now() - startMs;
+
+		expect(elapsedMs).toBeLessThan(50);
+	});
+
+	it('throws for non-finite inputs', () => {
+		expect(() => sleepMs(Number.POSITIVE_INFINITY)).toThrow('Invalid sleep duration milliseconds: Infinity');
+	});
+});

packages/time/tsconfig.json

@@ -0,0 +1,7 @@
+{
+	"extends": "../../tsconfigs/package.json",
+	"compilerOptions": {
+		"types": ["node"]
+	},
+	"include": ["src/**/*"]
+}

packages/time/vitest.config.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright (C) 2026 Fluxer Contributors
+ *
+ * This file is part of Fluxer.
+ *
+ * Fluxer is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Fluxer is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with Fluxer. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import tsconfigPaths from 'vite-tsconfig-paths';
+import {defineConfig} from 'vitest/config';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+	plugins: [
+		tsconfigPaths({
+			root: path.resolve(__dirname, '../..'),
+		}),
+	],
+	test: {
+		globals: true,
+		environment: 'node',
+		include: ['**/*.{test,spec}.{ts,tsx}'],
+		exclude: ['node_modules', 'dist'],
+		coverage: {
+			provider: 'v8',
+			reporter: ['text', 'json', 'html'],
+			exclude: ['**/*.test.tsx', '**/*.spec.tsx', 'node_modules/'],
+		},
+	},
+});