@verdant-web/common 1.11.0

package/src/timestamp.ts

@@ -0,0 +1,284 @@
+import cuid from 'cuid';
+import { v4 } from 'uuid';
+
+export interface TimestampProvider {
+	now(version: number): string;
+	update(remoteTimestamp: string): void;
+	zero(version: number): string;
+	getWallClockTime(timestamp: string): number;
+}
+
+const VERSION_BLOCK_LENGTH = 4;
+const ENCODING_NUMBER_RADIX = 36;
+
+export function encodeVersion(version: number | string): string {
+	return version
+		.toString(ENCODING_NUMBER_RADIX)
+		.padStart(VERSION_BLOCK_LENGTH, '0');
+}
+
+export function OLD_encodeVersion(version: number | string): string {
+	return version.toString().padStart(6, '0');
+}
+
+export class NaiveTimestampProvider implements TimestampProvider {
+	counter = 0;
+	now = (version: number | string) => {
+		return (
+			encodeVersion(version) + Date.now().toString() + '-' + this.counter++
+		);
+	};
+	update = () => {
+		this.counter = 0;
+	};
+	zero = (version: number | string) => {
+		return encodeVersion(version) + '0' + '-' + this.counter++;
+	};
+	getWallClockTime = (timestamp: string) => {
+		return parseInt(timestamp.slice(VERSION_BLOCK_LENGTH).split('-')[0], 10);
+	};
+}
+
+export class HybridLogicalClockTimestampProvider implements TimestampProvider {
+	private latest: HLCTimestamp = {
+		time: Date.now(),
+		counter: 0,
+		node: generateNodeId(),
+	};
+	private zeroCounter = 0;
+
+	now = (version: string | number) => {
+		this.latest = getHlcNow(this.latest);
+		return this.get(version, this.latest);
+	};
+	/**
+	 * @deprecated - use now() instead and update to latest format
+	 */
+	OLD_now = (version: string | number) => {
+		this.latest = getHlcNow(this.latest);
+		return OLD_encodeVersion(version) + OLD_serializeHlcTimestamp(this.latest);
+	};
+	/** Get the current timer state. Does not increment counter. */
+	timerState = () => {
+		return this.latest;
+	};
+	update = (remoteTimestamp: string) => {
+		// strip version from remote timestamp
+		const hlcString = remoteTimestamp.slice(VERSION_BLOCK_LENGTH);
+		this.latest = updateFromRemote(
+			this.latest,
+			deserializeHlcTimestamp(hlcString),
+		);
+	};
+	get = (version: string | number, raw: HLCTimestamp) => {
+		return encodeVersion(version) + serializeHlcTimestamp(raw);
+	};
+	zero = (version: string | number) => {
+		return (
+			encodeVersion(version) +
+			serializeHlcTimestamp({
+				time: 0,
+				// to keep zero timestamps unique, we use a counter here as well
+				counter: this.zeroCounter++,
+				node: this.latest.node,
+			})
+		);
+	};
+	getWallClockTime = (timestamp: string): number => {
+		return deserializeHlcTimestamp(timestamp.slice(VERSION_BLOCK_LENGTH)).time;
+	};
+}
+
+class ClockDriftError extends Error {
+	type: string;
+	constructor(...args: any[]) {
+		super();
+		this.type = 'ClockDriftError';
+		this.message = ['maximum clock drift exceeded'].concat(args).join(' ');
+	}
+}
+
+class OverflowError extends Error {
+	type: string;
+	constructor() {
+		super();
+		this.type = 'OverflowError';
+		this.message = 'timestamp counter overflow';
+	}
+}
+
+interface HLCTimestamp {
+	time: number;
+	counter: number;
+	node: string;
+}
+
+const COUNTER_BLOCK_LENGTH = 4;
+const NODE_BLOCK_LENGTH = 7;
+const MAX_CLOCK_DRIFT = 60 * 1000;
+// 9 base36 characters should last until the year 5000
+// when encoding a unix MS timestamp
+const TIME_BLOCK_LENGTH = 9;
+
+function generateNodeId() {
+	return cuid
+		.slug()
+		.padStart(NODE_BLOCK_LENGTH, '0')
+		.slice(0, NODE_BLOCK_LENGTH);
+}
+
+export function serializeHlcTimestamp(ts: HLCTimestamp): string {
+	// string representation of the time
+	const dateString = new Date(ts.time)
+		.getTime()
+		.toString(ENCODING_NUMBER_RADIX)
+		.padStart(TIME_BLOCK_LENGTH, '0');
+	// counter, 336, padded to 4 characters
+	const counter = ts.counter
+		.toString(ENCODING_NUMBER_RADIX)
+		.padStart(COUNTER_BLOCK_LENGTH, '0');
+	// node id padded to 16 characters
+	const node = ts.node.padStart(NODE_BLOCK_LENGTH, '0');
+	return `${dateString}${counter}${node}`;
+}
+
+function getHlcNow(prev: HLCTimestamp): HLCTimestamp {
+	const wallTime = Date.now();
+
+	// pick prev's time if it's later than our local device
+	const newWallTime = Math.max(prev.time, wallTime);
+	// reset counter if wall time changed
+	const newCounter = prev.time === newWallTime ? prev.counter + 1 : 0;
+
+	// check for drift
+	if (newWallTime - wallTime > MAX_CLOCK_DRIFT) {
+		throw new ClockDriftError(newWallTime, wallTime, MAX_CLOCK_DRIFT);
+	}
+	// check for counter overflow (max is 4 bytes)
+	if (newCounter > 65535) {
+		throw new OverflowError();
+	}
+
+	return {
+		time: newWallTime,
+		counter: newCounter,
+		node: prev.node,
+	};
+}
+
+function updateFromRemote(
+	local: HLCTimestamp,
+	remote: HLCTimestamp,
+): HLCTimestamp {
+	const wallTime = Date.now();
+	// pick remote's time if it's later than our local device
+	const newTime = Math.max(wallTime, Math.max(local.time, remote.time));
+
+	const maxCounter = Math.max(local.counter, remote.counter);
+	let newCounter;
+	// if all clocks are the same, increment the counter
+	if (local.time === newTime && remote.time === newTime) {
+		newCounter = maxCounter + 1;
+	}
+	// if local time is the same as new time, increment our local counter
+	else if (local.time === newTime) {
+		newCounter = local.counter + 1;
+	}
+	// if remote time is the same as new time, increment remote counter
+	else if (remote.time === newTime) {
+		newCounter = remote.counter + 1;
+	}
+	// otherwise, reset the counter
+	else {
+		newCounter = 0;
+	}
+
+	// check for drift
+	if (newTime - wallTime > MAX_CLOCK_DRIFT) {
+		throw new ClockDriftError(newTime, wallTime, MAX_CLOCK_DRIFT);
+	}
+	if (newCounter > 65535) {
+		throw new OverflowError();
+	}
+
+	return {
+		time: newTime,
+		counter: newCounter,
+		node: local.node,
+	};
+}
+
+export function deserializeHlcTimestamp(clock: string): HLCTimestamp {
+	const dateString = clock.slice(0, TIME_BLOCK_LENGTH);
+	const counter = clock.slice(
+		TIME_BLOCK_LENGTH,
+		TIME_BLOCK_LENGTH + COUNTER_BLOCK_LENGTH,
+	);
+	const node = clock.slice(TIME_BLOCK_LENGTH + COUNTER_BLOCK_LENGTH);
+	const time = parseInt(dateString, ENCODING_NUMBER_RADIX);
+	const counterNum = parseInt(counter, ENCODING_NUMBER_RADIX);
+
+	if (isNaN(time) || isNaN(counterNum)) {
+		throw new Error('invalid clock format');
+	}
+
+	return {
+		time,
+		counter: counterNum,
+		node,
+	};
+}
+
+function removeLeadingZeroes(str: string): string {
+	return str.replace(/^0+/, '');
+}
+
+/**
+ * Below, converters for old-style timestamps are defined.
+ * These are for migrating older clients to the new format.
+ */
+
+/**
+ * Converts a timestamp from the old format to the new format.
+ */
+export function convertOldHlcTimestamp(ts: string): string {
+	const versionBlock = ts.slice(0, 6);
+	// no jokes please
+	const clockBlock = ts.slice(6);
+	const deserialized = OLD_deserializeHlcTimestamp(clockBlock);
+
+	// version was base 10 and now is base 36
+	const versionNumber = parseInt(versionBlock, 10);
+	const encodedVersion = encodeVersion(versionNumber);
+	return encodedVersion + serializeHlcTimestamp(deserialized);
+}
+
+export function OLD_serializeHlcTimestamp(ts: HLCTimestamp): string {
+	// ISO string representation of the time
+	const dateString = new Date(ts.time).toISOString();
+	// counter, base16, padded to 4 characters
+	const counter = ts.counter.toString(16).toUpperCase().padStart(4, '0');
+	// node id padded to 16 characters
+	const node = ts.node.padStart(16, '0');
+	return `${dateString}-${counter}-${node}`;
+}
+
+export function OLD_deserializeHlcTimestamp(clock: string): HLCTimestamp {
+	// ISO string representation of the time
+	const dateString = clock.slice(0, 24);
+	const counter = clock.slice(25, 25 + 4);
+	const node = clock.slice(25 + 4 + 1);
+
+	const time = new Date(dateString).getTime();
+	const counterNum = parseInt(counter, 16);
+
+	if (isNaN(time) || isNaN(counterNum)) {
+		throw new Error('invalid clock format');
+	}
+
+	return {
+		time,
+		counter: counterNum,
+		node: node.slice(node.length - 7),
+	};
+}

package/src/undo.ts

@@ -0,0 +1,205 @@
+import { ObjectIdentifier } from './oids.js';
+import { applyPatch, Operation } from './operation.js';
+import { cloneDeep } from './utils.js';
+
+export function getUndoOperations(
+	oid: ObjectIdentifier,
+	initial: any,
+	operations: Operation[],
+	getNow: () => string,
+): Operation[] {
+	if (initial === undefined) {
+		// if the initial state is nothing, then the undo is to delete everything.
+		// there's nothing else to worry about!
+		return [
+			{
+				oid,
+				timestamp: getNow(),
+				data: {
+					op: 'delete',
+				},
+			},
+		];
+	}
+	// otherwise, traverse the operations one by one,
+	// applying them, and using the prior state to determine
+	// what the undo operation is.
+	let state = cloneDeep(initial);
+	const undoOperations: Operation[] = [];
+	for (const operation of operations) {
+		const undo = getUndoOperation(oid, state, operation, getNow);
+		undoOperations.unshift(...undo);
+		applyPatch(state, operation.data);
+	}
+	return undoOperations;
+}
+
+function getUndoOperation(
+	oid: ObjectIdentifier,
+	initial: any,
+	operation: Operation,
+	getNow: () => string,
+): Operation[] {
+	const data = operation.data;
+	switch (data.op) {
+		case 'set':
+		case 'remove':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'set',
+						name: data.name,
+						value: initial[data.name],
+					},
+				},
+			];
+		case 'list-insert':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-delete',
+						index: data.index,
+						count: 1,
+					},
+				},
+			];
+		case 'list-delete':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-insert',
+						index: data.index,
+						values: initial.slice(data.index, data.count),
+					},
+				},
+			];
+		case 'list-move-by-ref':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-move-by-ref',
+						value: data.value,
+						index: initial.indexOf(data.value),
+					},
+				},
+			];
+		case 'list-move-by-index':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-move-by-index',
+						from: data.to,
+						to: data.from,
+					},
+				},
+			];
+		case 'delete':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'initialize',
+						value: initial,
+					},
+				},
+			];
+		case 'list-push':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-remove',
+						value: data.value,
+						// best heuristic here - remove the last instance of the item.
+						only: 'last',
+					},
+				},
+			];
+		case 'list-remove':
+			if (data.only === 'last') {
+				const index = initial.lastIndexOf(data.value);
+				return [
+					{
+						oid,
+						timestamp: getNow(),
+						data: {
+							op: 'list-insert',
+							index,
+							values: [data.value],
+						},
+					},
+				];
+			} else if (data.only === 'first') {
+				const index = initial.indexOf(data.value);
+				return [
+					{
+						oid,
+						timestamp: getNow(),
+						data: {
+							op: 'list-insert',
+							index,
+							values: [data.value],
+						},
+					},
+				];
+			} else {
+				// find all instances of value and restore them at their
+				// original index
+				const indexesOfValue = [];
+				let index = initial.indexOf(data.value);
+				while (index !== -1) {
+					indexesOfValue.push(index);
+					index = initial.indexOf(data.value, index + 1);
+				}
+				return indexesOfValue.map((index) => ({
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-insert',
+						index,
+						value: data.value,
+					},
+				}));
+			}
+		case 'list-add':
+			// this one is kind of ambiguous. in theory the set may have
+			// already included the value and so no change happened. but
+			// basically we infer the intent is to remove what was meant
+			// to be added by this change.
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'list-remove',
+						value: data.value,
+						only: 'last',
+					},
+				},
+			];
+		case 'initialize':
+			return [
+				{
+					oid,
+					timestamp: getNow(),
+					data: {
+						op: 'delete',
+					},
+				},
+			];
+		default:
+			throw new Error(`Cannot undo operation type: ${(data as any).op}`);
+	}
+}

package/src/utils.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { assignOid, assignOidsToAllSubObjects, getOid } from './oids.js';
+import { cloneDeep, getSortedIndex } from './utils.js';
+
+describe('utils', () => {
+	describe('get sorted index', () => {
+		it('finds the right insertion index', () => {
+			function compare(a: number, b: number) {
+				return a - b;
+			}
+			expect(getSortedIndex([1, 2, 3, 4, 5], 6, compare)).toBe(5);
+			expect(getSortedIndex([1, 2, 3, 4, 5], 0, compare)).toBe(0);
+			expect(getSortedIndex([1, 2, 3, 4, 5], -1, compare)).toBe(0);
+			expect(getSortedIndex([1, 2, 3, 4, 5], 20, compare)).toBe(5);
+		});
+	});
+
+	describe('clone deep', () => {
+		it('preserves OIDs', () => {
+			const obj = {
+				foo: 'bar',
+				qux: [
+					{
+						corge: true,
+					},
+				],
+			};
+			assignOid(obj, 'test/a');
+			assignOidsToAllSubObjects(obj);
+
+			const cloned = cloneDeep(obj);
+
+			expect(getOid(cloned)).toEqual(getOid(obj));
+			expect(getOid(cloned.qux)).toEqual(getOid(obj.qux));
+			expect(getOid(cloned.qux[0])).toEqual(getOid(obj.qux[0]));
+		});
+	});
+});

package/src/utils.ts

@@ -0,0 +1,137 @@
+import { v4 } from 'uuid';
+import { assignOid, maybeGetOid } from './oids.js';
+
+export function take<T extends object, Keys extends keyof T>(
+	obj: T,
+	keys: Keys[],
+): Pick<T, Keys> {
+	const result: any = {};
+	for (const key of keys) {
+		result[key] = obj[key];
+	}
+	return result;
+}
+
+export function omit<T extends object, Keys extends keyof T>(
+	obj: T,
+	keys: Keys[],
+): Omit<T, Keys> {
+	const result: any = {};
+	for (const key of Object.keys(obj)) {
+		if (!keys.includes(key as Keys)) {
+			result[key] = (obj as any)[key];
+		}
+	}
+	return result;
+}
+
+export function getSortedIndex<T>(
+	array: T[],
+	insert: T,
+	compare: (a: T, b: T) => number,
+) {
+	let low = 0;
+	let high = array.length;
+	while (low < high) {
+		const mid = (low + high) >>> 1;
+		const cmp = compare(array[mid], insert);
+		if (cmp < 0) {
+			low = mid + 1;
+		} else {
+			high = mid;
+		}
+	}
+	return low;
+}
+
+function orderedReplacer(_: any, v: any) {
+	if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+		return v;
+	}
+	return Object.fromEntries(
+		Object.entries(v).sort(([ka], [kb]) => (ka < kb ? -1 : ka > kb ? 1 : 0)),
+	);
+}
+/**
+ * Consistently stringifies an object regardless
+ * of key insertion order
+ */
+export function stableStringify(obj: any) {
+	return JSON.stringify(obj, orderedReplacer);
+}
+
+export function cloneDeep<T>(obj: T): T {
+	if (isObject(obj)) {
+		const oid = maybeGetOid(obj);
+		let clone: any;
+		if (Array.isArray(obj)) {
+			clone = obj.map(cloneDeep) as T;
+		} else {
+			clone = {};
+			for (const [key, value] of Object.entries(obj as any)) {
+				clone[key] = cloneDeep(value);
+			}
+		}
+		if (oid) {
+			assignOid(clone, oid);
+		}
+		return clone;
+	}
+	return obj;
+}
+
+// TODO: better hash
+export function hashObject(obj: any) {
+	return stableStringify(obj);
+}
+
+export function isObject(obj: any) {
+	return obj && typeof obj === 'object';
+}
+
+export function roughSizeOfObject(object: any) {
+	var objectList = [];
+	var stack = [object];
+	var bytes = 0;
+
+	while (stack.length) {
+		var value = stack.pop();
+
+		if (typeof value === 'boolean') {
+			bytes += 4;
+		} else if (typeof value === 'string') {
+			bytes += value.length * 2;
+		} else if (typeof value === 'number') {
+			bytes += 8;
+		} else if (typeof value === 'object' && objectList.indexOf(value) === -1) {
+			objectList.push(value);
+
+			for (var i in value) {
+				stack.push(value[i]);
+			}
+		}
+	}
+	return bytes;
+}
+
+export function assert(
+	condition: any,
+	message: string = 'assertion failed',
+): asserts condition {
+	if (!condition) {
+		throw new Error(message);
+	}
+}
+
+export function generateId(length = 16) {
+	return v4().replace('-', '').slice(0, length);
+}
+
+export function findLastIndex<T>(array: T[], predicate: (item: T) => boolean) {
+	for (let i = array.length - 1; i >= 0; i--) {
+		if (predicate(array[i])) {
+			return i;
+		}
+	}
+	return -1;
+}