[mergeable] Custom getNow function

Author: jamesgpearce

src/@types/mergeable-store/docs.js

@@ -20,6 +20,19 @@
  * @since v5.0.0
  */
 /// mergeable-store
+
+/**
+ * The GetNow type is used to represent a function that returns the current time
+ * in milliseconds.
+ *
+ * This is used internally within the mergeable-store module, but is used for
+ * the createMergeableStore function's second optional argument to allow
+ * applications to override the clock used to generate timestamps.
+ * @category Stamps
+ * @since v6.1.0
+ */
+/// GetNow
+
 /**
  * The Hash type is used within the mergeable-store module to quickly compare
  * the content of two objects.
@@ -953,12 +966,21 @@
  * The createMergeableStore function creates a MergeableStore, and is the main
  * entry point into the mergeable-store module.
  *
- * There is one optional parameter which is a uniqueId for the MergeableStore.
- * This is used to distinguish conflicting changes made in the same millisecond
- * by two different MergeableStore objects as its hash is added to the end of
- * the HLC timestamps. Generally this can be omitted unless you have a need for
- * deterministic HLCs, such as in a testing scenario. Otherwise, TinyBase will
- * assign a unique Id to the Store at the time of creation.
+ * There are two optional parameters which are only for testing and advanced
+ * usage.
+ *
+ * The first is a uniqueId for the MergeableStore, used to distinguish
+ * conflicting changes made in the same millisecond by two different
+ * MergeableStore objects as its hash is added to the end of the HLC timestamps.
+ * Generally this can be omitted unless you have a need for deterministic HLCs,
+ * such as in a testing scenario. Otherwise, TinyBase will assign a unique Id to
+ * the Store at the time of creation.
+ *
+ * Since v6.1.0, the second is a function that can be used to replace the way
+ * the timestamp is generated for HLCs (by default JavaScript's `Date.now()`
+ * method).
+ * @param uniqueId An optional unique Id for the MergeableStore.
+ * @param getNow An optional function that generates millisecond timestamps.
  * @returns A reference to the new MergeableStore.
  * @example
  * This example creates a MergeableStore.

src/@types/mergeable-store/index.d.ts

@@ -7,6 +7,9 @@ import type {
   ValueOrUndefined,
 } from '../store/index.d.ts';
 
+/// GetNow
+export type GetNow = () => number;
+
 /// Hash
 export type Hash = number;
 
@@ -141,4 +144,7 @@ export interface MergeableStore extends Store {
 }
 
 /// createMergeableStore
-export function createMergeableStore(uniqueId?: Id): MergeableStore;
+export function createMergeableStore(
+  uniqueId?: Id,
+  getNow?: GetNow,
+): MergeableStore;

src/@types/mergeable-store/with-schemas/index.d.ts

@@ -20,6 +20,9 @@ import type {
   ValuesSchema,
 } from '../../store/with-schemas/index.d.ts';
 
+/// GetNow
+export type GetNow = () => number;
+
 /// Hash
 export type Hash = number;
 
@@ -257,4 +260,7 @@ export interface MergeableStore<Schemas extends OptionalSchemas>
 }
 
 /// createMergeableStore
-export function createMergeableStore(uniqueId?: Id): MergeableStore<NoSchemas>;
+export function createMergeableStore(
+  uniqueId?: Id,
+  getNow?: GetNow,
+): MergeableStore<NoSchemas>;

src/common/hlc.ts

@@ -1,4 +1,5 @@
 import type {Id} from '../@types/common/index.d.ts';
+import type {GetNow} from '../@types/mergeable-store/index.d.ts';
 import {decode, encode} from './codec.ts';
 import {getHash} from './hash.ts';
 import {getUniqueId} from './index.ts';
@@ -48,6 +49,7 @@ const decodeTimeAndCounter = (
 
 export const getHlcFunctions = (
   uniqueId?: Id,
+  getNow: GetNow = Date.now,
 ): [getHlc: () => Hlc, seenHlc: (remoteHlc: Hlc) => void] => {
   let logicalTime = 0;
   let lastCounter = -1;
@@ -79,7 +81,7 @@ export const getHlcFunctions = (
     logicalTime = mathMax(
       previousLogicalTime,
       remoteLogicalTime,
-      (GLOBAL as any).HLC_TIME ?? Date.now(),
+      (GLOBAL as any).HLC_TIME ?? getNow(),
     );
     lastCounter =
       logicalTime == previousLogicalTime

src/mergeable-store/index.ts

@@ -2,6 +2,7 @@ import type {Id} from '../@types/common/index.d.ts';
 import type {
   CellHashes,
   ContentHashes,
+  GetNow,
   MergeableChanges,
   MergeableContent,
   MergeableStore,
@@ -147,13 +148,16 @@ const validateMergeableContent = (
     ),
   );
 
-export const createMergeableStore = ((uniqueId?: Id): MergeableStore => {
+export const createMergeableStore = ((
+  uniqueId?: Id,
+  getNow?: GetNow,
+): MergeableStore => {
   let listeningToRawStoreChanges = 1;
   let contentStampMap = newContentStampMap();
   let defaultingContent: 0 | 1 = 0;
   const touchedCells: IdSet3 = mapNew();
   const touchedValues: IdSet = setNew();
-  const [getHlc, seenHlc] = getHlcFunctions(uniqueId);
+  const [getHlc, seenHlc] = getHlcFunctions(uniqueId, getNow);
   const store = createStore();
 
   const disableListeningToRawStoreChanges = (