Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
12.7 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {FLUXER_EPOCH as FLUXER_EPOCH_NUMBER} from '@fluxer/constants/src/Core';
import {
	createSnowflake,
	createSnowflakeFromTimestamp,
	FLUXER_EPOCH,
	generateSnowflake,
	isValidSnowflake,
	parseSnowflake,
	SnowflakeGenerator,
	snowflakeToDate,
} from '@fluxer/snowflake/src/Snowflake';
import {describe, expect, it} from 'vitest';

const WORKER_ID_BITS = 10n;
const SEQUENCE_BITS = 12n;
const TIMESTAMP_SHIFT = SEQUENCE_BITS + WORKER_ID_BITS;
const WORKER_ID_SHIFT = SEQUENCE_BITS;

describe('FLUXER_EPOCH', () => {
	it('should match the epoch constant from @fluxer/constants', () => {
		expect(FLUXER_EPOCH).toBe(BigInt(FLUXER_EPOCH_NUMBER));
	});
	it('should equal January 1, 2015 00:00:00 UTC', () => {
		const expectedDate = new Date('2015-01-01T00:00:00.000Z');
		expect(Number(FLUXER_EPOCH)).toBe(expectedDate.getTime());
	});
});

describe('SnowflakeGenerator', () => {
	describe('generate', () => {
		it('should generate unique snowflakes', () => {
			const generator = new SnowflakeGenerator(1);
			const snowflakes = new Set<bigint>();
			for (let i = 0; i < 1000; i++) {
				snowflakes.add(generator.generate());
			}
			expect(snowflakes.size).toBe(1000);
		});
		it('should generate snowflakes with increasing values', () => {
			const generator = new SnowflakeGenerator(1);
			let previous = generator.generate();
			for (let i = 0; i < 100; i++) {
				const current = generator.generate();
				expect(current).toBeGreaterThan(previous);
				previous = current;
			}
		});
		it('should generate snowflakes with correct structure', () => {
			const generator = new SnowflakeGenerator(5);
			const snowflake = generator.generate();
			expect(typeof snowflake).toBe('bigint');
			expect(snowflake).toBeGreaterThan(0n);
		});
		it('should embed worker ID in generated snowflakes', () => {
			const workerId = 512;
			const generator = new SnowflakeGenerator(workerId);
			for (let i = 0; i < 10; i++) {
				const snowflake = generator.generate();
				const parsed = parseSnowflake(snowflake);
				expect(parsed.workerId).toBe(workerId);
			}
		});
		it('should increment sequence within same millisecond', () => {
			const generator = new SnowflakeGenerator(1);
			const snowflakes: Array<bigint> = [];
			for (let i = 0; i < 100; i++) {
				snowflakes.push(generator.generate());
			}
			const firstTimestamp = parseSnowflake(snowflakes[0]).timestamp.getTime();
			const sameMillisecond = snowflakes.filter((s) => parseSnowflake(s).timestamp.getTime() === firstTimestamp);
			if (sameMillisecond.length > 1) {
				const sameMillisecondSequences = sameMillisecond.map((s) => parseSnowflake(s).sequence);
				for (let i = 1; i < sameMillisecondSequences.length; i++) {
					expect(sameMillisecondSequences[i]).toBeGreaterThan(sameMillisecondSequences[i - 1]);
				}
			}
		});
		it('should reset sequence when timestamp changes', () => {
			const generator = new SnowflakeGenerator(1);
			const snowflake1 = generator.generate();
			const parsed1 = parseSnowflake(snowflake1);
			let snowflake2 = generator.generate();
			let parsed2 = parseSnowflake(snowflake2);
			let attempts = 0;
			while (parsed1.timestamp.getTime() === parsed2.timestamp.getTime() && attempts < 10000) {
				snowflake2 = generator.generate();
				parsed2 = parseSnowflake(snowflake2);
				attempts++;
			}
			if (parsed1.timestamp.getTime() !== parsed2.timestamp.getTime()) {
				expect(parsed2.sequence).toBe(0);
			}
		});
	});
	describe('sequence overflow handling', () => {
		it('should handle rapid generation without duplicates', () => {
			const generator = new SnowflakeGenerator(1);
			const snowflakes = new Set<bigint>();
			const count = 5000;
			for (let i = 0; i < count; i++) {
				snowflakes.add(generator.generate());
			}
			expect(snowflakes.size).toBe(count);
		});
		it('should remain monotonic when the clock moves backwards', () => {
			const baseTime = Number(FLUXER_EPOCH) + 1000;
			const times = [baseTime + 2, baseTime + 1, baseTime + 3];
			let index = 0;
			const generator = new SnowflakeGenerator({
				workerId: 1,
				now: () => {
					const nextIndex = Math.min(index, times.length - 1);
					index += 1;
					return times[nextIndex];
				},
			});
			const first = generator.generate();
			const second = generator.generate();
			expect(second).toBeGreaterThan(first);
		});
	});
});

describe('createSnowflake', () => {
	it('should create a snowflake with explicit worker and sequence', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflake({
			timestamp,
			workerId: 3,
			sequence: 77,
		});
		const parsed = parseSnowflake(snowflake);
		expect(parsed.timestamp.getTime()).toBe(timestamp);
		expect(parsed.workerId).toBe(3);
		expect(parsed.sequence).toBe(77);
	});
	it('should throw error for out-of-range sequence', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		expect(() =>
			createSnowflake({
				timestamp,
				sequence: 4096,
			}),
		).toThrow('Sequence must be between 0 and 4095');
	});
});

describe('createSnowflakeFromTimestamp', () => {
	it('should create a snowflake from a numeric timestamp', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(timestamp);
	});
	it('should create a snowflake from a bigint timestamp', () => {
		const timestamp = FLUXER_EPOCH + 1000000n;
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(Number(timestamp));
	});
	it('should create a snowflake with default worker ID of 0', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const parsed = parseSnowflake(snowflake);
		expect(parsed.workerId).toBe(0);
	});
	it('should create a snowflake with specified worker ID', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflakeFromTimestamp(timestamp, 100);
		const parsed = parseSnowflake(snowflake);
		expect(parsed.workerId).toBe(100);
	});
	it('should create a snowflake with sequence of 0', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const parsed = parseSnowflake(snowflake);
		expect(parsed.sequence).toBe(0);
	});
	it('should throw error for timestamp before epoch', () => {
		const timestamp = Number(FLUXER_EPOCH) - 1;
		expect(() => createSnowflakeFromTimestamp(timestamp)).toThrow('Timestamp must be on or after the Fluxer epoch');
	});
	it('should accept timestamp exactly at epoch', () => {
		const timestamp = Number(FLUXER_EPOCH);
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(timestamp);
	});
	it('should throw error for invalid worker ID', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		expect(() => createSnowflakeFromTimestamp(timestamp, -1)).toThrow('Worker ID must be between 0 and 1023');
		expect(() => createSnowflakeFromTimestamp(timestamp, 1024)).toThrow('Worker ID must be between 0 and 1023');
	});
	it('should create different snowflakes for different worker IDs at same timestamp', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake1 = createSnowflakeFromTimestamp(timestamp, 0);
		const snowflake2 = createSnowflakeFromTimestamp(timestamp, 1);
		expect(snowflake1).not.toBe(snowflake2);
	});
});

describe('snowflakeToDate', () => {
	it('should extract date from a generated snowflake', () => {
		const before = Date.now();
		const snowflake = generateSnowflake();
		const after = Date.now();
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBeGreaterThanOrEqual(before);
		expect(date.getTime()).toBeLessThanOrEqual(after);
	});
	it('should extract correct date from a snowflake created from timestamp', () => {
		const expectedTimestamp = Number(FLUXER_EPOCH) + 86400000;
		const snowflake = createSnowflakeFromTimestamp(expectedTimestamp);
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(expectedTimestamp);
	});
	it('should handle snowflake at epoch', () => {
		const snowflake = 0n;
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(Number(FLUXER_EPOCH));
	});
	it('should handle large snowflake values', () => {
		const futureTimestamp = Number(FLUXER_EPOCH) + 10 * 365 * 24 * 60 * 60 * 1000;
		const snowflake = createSnowflakeFromTimestamp(futureTimestamp);
		const date = snowflakeToDate(snowflake);
		expect(date.getTime()).toBe(futureTimestamp);
	});
});

describe('parseSnowflake', () => {
	it('should parse all components of a snowflake', () => {
		const workerId = 42;
		const generator = new SnowflakeGenerator(workerId);
		const snowflake = generator.generate();
		const parsed = parseSnowflake(snowflake);
		expect(parsed).toHaveProperty('timestamp');
		expect(parsed).toHaveProperty('workerId');
		expect(parsed).toHaveProperty('sequence');
		expect(parsed.timestamp).toBeInstanceOf(Date);
		expect(typeof parsed.workerId).toBe('number');
		expect(typeof parsed.sequence).toBe('number');
	});
	it('should extract correct worker ID', () => {
		const workerId = 777;
		const generator = new SnowflakeGenerator(workerId);
		const snowflake = generator.generate();
		const parsed = parseSnowflake(snowflake);
		expect(parsed.workerId).toBe(workerId);
	});
	it('should extract correct timestamp', () => {
		const before = Date.now();
		const generator = new SnowflakeGenerator(1);
		const snowflake = generator.generate();
		const after = Date.now();
		const parsed = parseSnowflake(snowflake);
		expect(parsed.timestamp.getTime()).toBeGreaterThanOrEqual(before);
		expect(parsed.timestamp.getTime()).toBeLessThanOrEqual(after);
	});
	it('should extract sequence starting from 0', () => {
		const timestamp = Number(FLUXER_EPOCH) + 1000000;
		const snowflake = createSnowflakeFromTimestamp(timestamp);
		const parsed = parseSnowflake(snowflake);
		expect(parsed.sequence).toBe(0);
	});
	it('should parse snowflake with maximum worker ID', () => {
		const generator = new SnowflakeGenerator(1023);
		const snowflake = generator.generate();
		const parsed = parseSnowflake(snowflake);
		expect(parsed.workerId).toBe(1023);
	});
	it('should correctly parse a manually constructed snowflake', () => {
		const relativeTimestamp = 1000000n;
		const workerId = 500n;
		const sequence = 100n;
		const snowflake = (relativeTimestamp << TIMESTAMP_SHIFT) | (workerId << WORKER_ID_SHIFT) | sequence;
		const parsed = parseSnowflake(snowflake);
		expect(parsed.timestamp.getTime()).toBe(Number(FLUXER_EPOCH) + Number(relativeTimestamp));
		expect(parsed.workerId).toBe(Number(workerId));
		expect(parsed.sequence).toBe(Number(sequence));
	});
});

describe('isValidSnowflake', () => {
	describe('valid snowflakes', () => {
		it('should return true for a generated snowflake', () => {
			const snowflake = generateSnowflake();
			expect(isValidSnowflake(snowflake)).toBe(true);
		});
		it('should return true for a snowflake created from timestamp', () => {
			const snowflake = createSnowflakeFromTimestamp(Date.now());
			expect(isValidSnowflake(snowflake)).toBe(true);
		});
		it('should return true for snowflake at epoch (0n)', () => {
			expect(isValidSnowflake(0n)).toBe(true);
		});
		it('should return true for snowflake with maximum worker ID', () => {
			const generator = new SnowflakeGenerator(1023);
			const snowflake = generator.generate();
			expect(isValidSnowflake(snowflake)).toBe(true);
		});
	});
	describe('invalid snowflakes', () => {
		it('should return false for non-bigint values', () => {
			expect(isValidSnowflake(123)).toBe(false);
			expect(isValidSnowflake('123456789')).toBe(false);
			expect(isValidSnowflake(null)).toBe(false);
			expect(isValidSnowflake(undefined)).toBe(false);
			expect(isValidSnowflake({})).toBe(false);
			expect(isValidSnowflake([])).toBe(false);
		});
		it('should return false for negative bigint', () => {
			expect(isValidSnowflake(-1n)).toBe(false);
			expect(isValidSnowflake(-1000000n)).toBe(false);
		});
		it('should return false for snowflake with timestamp before epoch', () => {
			const invalidSnowflake = -1n << TIMESTAMP_SHIFT;
			expect(isValidSnowflake(invalidSnowflake)).toBe(false);
		});
		it('should return false for snowflake with timestamp too far in the future', () => {
			const farFutureTimestamp = BigInt(Date.now() + 86400000 + 1000) - FLUXER_EPOCH;
			const invalidSnowflake = farFutureTimestamp << TIMESTAMP_SHIFT;
			expect(isValidSnowflake(invalidSnowflake)).toBe(false);
		});
		it('should return true for snowflake with timestamp within 24 hours in the future', () => {
			const nearFutureTimestamp = BigInt(Date.now() + 3600000) - FLUXER_EPOCH;
			const validSnowflake = nearFutureTimestamp << TIMESTAMP_SHIFT;
			expect(isValidSnowflake(validSnowflake)).toBe(true);
		});
	});
});