@iebh/tera-fy 2.3.8 → 2.3.10

package/dist/lib/syncro/syncro (Rhino's conflicted copy 2026-05-10).js

@@ -0,0 +1,765 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+/* eslint-disable no-unused-vars */
+import { isEmpty, cloneDeep, random, sample, throttle, isEqual } from 'lodash-es';
+import { doc as FirestoreDocRef, getDoc as FirestoreGetDoc, onSnapshot as FirestoreOnSnapshot, setDoc as FirestoreSetDoc, updateDoc as FirestoreUpdateDoc, } from 'firebase/firestore';
+// @ts-expect-error No declaration file for marshal
+import marshal from '@momsfriendlydevco/marshal';
+import { nanoid } from 'nanoid';
+import PromiseThrottle from 'p-throttle';
+import PromiseRetry from 'p-retry';
+import { FirebaseError } from 'firebase/app';
+/**
+* @class Syncro
+* TERA Isomorphic Syncro class
+* Slurp an entity from Supabase and hold it in Firebase/Firestore as a "floating" entity which periodically gets flushed back to Supabase and eventually completely cleaned up
+* This class tries to be as independent as possible to help with adapting it to various front-end TERA-fy plugin frameworks
+*/
+export default class Syncro {
+    /**
+    * Firebase instance in use
+    *
+    * @type {FirebaseApp}
+    */
+    static firebase;
+    /**
+    * Firestore instance in use
+    *
+    * @type {Firestore}
+    */
+    static firestore;
+    /**
+    * Supabasey instance in use
+    *
+    * @type {Supabasey}
+    */
+    static supabasey;
+    /**
+    * The current user session, should be unique for the user + browser tab
+    * Used by the heartbeat system
+    *
+    * @type {String}
+    */
+    static session;
+    /**
+    * OPTIONAL SyncroEntries from './entities.ts' if its required
+    * This only gets populated if `config.forceLocalInit` is truthy and we've mounted at least one Syncro
+    *
+    * @type {Record<string, any>}
+    */
+    static SyncroEntities;
+    /**
+    * This instances fully formed string path
+    *
+    * @type {String}
+    */
+    path;
+    /**
+    * The Firestore docHandle when calling various Firestore functions
+    *
+    * @type {DocumentReference | undefined}
+    */
+    docRef;
+    /**
+    * The reactive object managed by this Syncro instance
+    * The nature of this varies by framework and what `getReactive()` provides
+    *
+    * @type {any}
+    */
+    value;
+    /**
+    * Default throttle to apply for writes
+    *
+    * @type {Number} Throttle time in milliseconds
+    */
+    throttle = 250;
+    /**
+    * Various Misc config for the Syncro instance
+    *
+    * @type {Object}
+    * @property {Number} heartbeatInterval Time in milliseconds between heartbeat beacons
+    * @property {String} syncroRegistryUrl The prefix Sync worker URL, used to populate Syncros and determine their active status
+    * @property {Object} context Additional named parameters to pass to callbacks like initState
+    */
+    config = {
+        heartbeatInterval: 120_000, //~= 120s / 2m
+        syncroRegistryUrl: 'https://tera-tools.com/api/sync',
+        context: {},
+    };
+    /**
+    * Whether the next heartbeat should be marked as 'dirty'
+    * This indicates that at least one change has occurred since the last heartbeat and the server should perform a flush (but not a clean)
+    * This flag is only transmitted once in the next heartbeat before being reset
+    *
+    * @see markDirty()
+    * @type {Boolean}
+    */
+    isDirty = false;
+    /**
+    * @interface
+    * Debugging printer for this instance
+    * Defaults to doing nothing
+    *
+    * @param {*...} [msg] The message to output
+    */
+    debug(...msg) { }
+    /**
+    * @interface
+    * Debugging printer specifically for error messages
+    * Defaults to using console.log()
+    *
+    * @param {*...} [msg] The message to output
+    */
+    debugError(...msg) {
+        console.warn(`[Syncro ${this.path}]`, ...msg);
+    }
+    /**
+    * Instance constructor
+    *
+    * @param {String} path Mount path for the Syncro. Should be in the form `${ENTITY}::${ID}(::${RELATION})?`
+    * @param {Object} [options] Additional instance setters (mutates instance directly), note that the `config` subkey is merged with the existing config rather than assigned
+    */
+    constructor(path, options) {
+        this.path = path;
+        Object.assign(this, {
+            ...options,
+            config: {
+                ...this.config,
+                ...options?.config,
+            },
+        });
+        if (!Syncro.session) // Assign a random session ID if we don't already have one
+            Syncro.session = `syncro_${nanoid()}`;
+    }
+    /**
+    * Instance destruction trigger
+    * This will unsubscribe from various facilities and release the object for cleanup
+    *
+    * @returns {Promise} A promise which resolves when the operation has completed
+    */
+    destroy() {
+        this.debug('Destroy!');
+        return Promise.resolve()
+            .then(() => Promise.all(this._destroyActions // eslint-disable @typescript-eslint/await-thenable
+            .map(fn => fn())))
+            .then(() => this._destroyActions = []); // Reset list of actions to perform when terminating
+    }
+    /**
+    * Actions to preform when we are destroying this instance
+    * This is an array of function callbacks to execute in parallel when `destroy()` is called
+    *
+    * @type {Array<Function<Promise>>}
+    */
+    _destroyActions = [];
+    /**
+    * Function to return whatever the local framework uses as a reactive object
+    * This should respond with an object of mandatory functions to watch for changes and re-merge them
+    *
+    * @param {Object} value Initial value of the reactive
+    *
+    * @returns {ReactiveWrapper} A reactive object prototype
+    * @property {Object} doc The reactive object
+    * @property {Function} setState Function used to overwrite the default state, called as `(newState:Object)`
+    * @property {Function} getState Function used to fetch the current snapshot state, called as `()`
+    * @property {Function} watch Function used to set up state watchers, should call its callback when a change is detected, called as `(cb:Function)`
+    */
+    getReactive(value) {
+        console.warn('Syncro.getReactive has not been subclassed, assuming a POJO response');
+        const doc = { ...value };
+        return {
+            doc,
+            setState(state) {
+                // Shallow copy all sub keys into existing object (keeping the object pointer)
+                Object.entries(state || {})
+                    .forEach(([k, v]) => doc[k] = v);
+            },
+            getState() {
+                return cloneDeep(doc);
+            },
+            watch(cb) {
+                // Stub
+            },
+        };
+    }
+    ;
+    /**
+    * Returns the split entity + ID relationship from a given session path
+    * This function checks for valid UUID format strings + that the entity is a known/supported entity (see `knownEntities`)
+    * NOTE: When used by itself (i.e. ignoring response) this function can also act as a guard that a path is valid
+    *
+    * INPUT: `widgets::UUID` -> `{entity:'widgets', id:UUID}`
+    * INPUT: `widgets::UUID::thing` -> `{entity:'widgets', id:UUID, relation:'thing'}`
+    *
+    * @param {String} path The input session path of the form `${ENTITY}::${ID}`
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {Boolean} [options.allowAsterisk=false] Whether to allow the meta asterisk character when recognising paths, this is used by the SyncroKeyed class
+    *
+    * @returns {PathSplitResult} An object composed of the session path components
+    */
+    static pathSplit(path, options) {
+        const settings = {
+            allowAsterisk: false,
+            ...options,
+        };
+        const pathMatcher = new RegExp(
+        // Compose the patch matching expression - note double escapes for backslashes to avoid encoding as raw string values
+        '^'
+            + '(?<entity>\\w+?)' // Any alpha-numeric sequence as the entity name (non-greedy capture)
+            + '::' // Followed by '::'
+            + '(?<id>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})' // Followed by a valid lower-case UUID
+            + '(?:::(?<relation>[' // Followed by an optional ansi relation
+            + '\\w' // Which is any alpha-numeric sequence...
+            + '\\-' // ... Including UUID characters
+            + (settings.allowAsterisk ? '\\*' : '') // ... and (optionally) an asterisk
+            + ']+?))?'
+            + '$');
+        const extracted = { ...pathMatcher.exec(path)?.groups };
+        if (!extracted || !extracted.entity || !extracted.id)
+            throw new Error(`Invalid session path syntax "${path}"`);
+        if (Syncro.SyncroEntities && !(extracted.entity in Syncro.SyncroEntities))
+            throw new Error(`Unsupported entity "${path}" -> Entity="${extracted.entity}"`);
+        return {
+            entity: extracted.entity,
+            id: extracted.id,
+            relation: extracted.relation,
+            fsCollection: extracted.entity,
+            fsId: extracted.relation
+                ? `${extracted.id}::${extracted.relation}`
+                : extracted.id,
+        };
+    }
+    /**
+    * Convert local POJO -> Firestore compatible object
+    * This applies the following mutations to the incoming object:
+    *
+    * 1. Arrays are converted to Objects (Firestore cannot store nested arrays)
+    * 2. All non-POJO objects (e.g. Dates) to a symmetric object
+    *
+    * @param {Object} snapshot The current state to convert
+    * @returns {Object} A Firebase compatible object
+    */
+    static toFirestore(snapshot = {}) {
+        return marshal.serialize(snapshot, {
+            ...marshalBaseConfig,
+            stringify: false,
+        });
+    }
+    /**
+    * Convert local Firestore compatible object -> local POJO
+    * This reverses the mutations listed in `toFirestore()`
+    *
+    * @param {Object} snapshot The raw Firebase state to convert
+    * @returns {Object} A JavaScript POJO representing the converted state
+    */
+    static fromFirestore(snapshot = {}) {
+        return marshal.deserialize(snapshot, {
+            ...marshalBaseConfig,
+            destringify: false,
+        });
+    }
+    /**
+    * Convert a raw POJO into Firestore field layout
+    * Field structures are usually consumed by the Firestore ReST API and need converting before being used
+    * NOTE: This does not serialize the incoming data so you likely want to use this as `toFirestoreFields(toFirestore(data))`
+    *
+    * @see https://stackoverflow.com/a/62304377
+    * @param {Object} data The raw value to convert
+    * @returns {Object} A Firestore compatible, typed data structure
+    */
+    static toFirestoreFields(data) {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            const type = typeof value;
+            if (type === 'string') { // eslint-disable-line unicorn/prefer-switch
+                result[key] = { stringValue: value };
+            }
+            else if (type === 'number') {
+                result[key] = { doubleValue: value };
+            }
+            else if (type === 'boolean') {
+                result[key] = { booleanValue: value };
+            }
+            else if (value === null) {
+                result[key] = { nullValue: null };
+            }
+            else if (Array.isArray(value)) {
+                // Need to handle the inner item structure correctly
+                result[key] = { arrayValue: { values: value.map(item => {
+                            const field = Syncro.toFirestoreFields({ item });
+                            return field.item; // Extract the typed value from the temporary {item: ...} structure
+                        }) } };
+            }
+            else if (type === 'object') {
+                result[key] = { mapValue: { fields: Syncro.toFirestoreFields(value) } };
+            }
+        }
+        return result;
+    }
+    /**
+    * Convert a Firestore field dump into a native POJO
+    * Field structures are usually provided by the Firestore ReST API and need de-typing back into a native document
+    * NOTE: This does not deserialize the result so you likely want to use this as `fromFirestore(fromFirestoreFields(response.fields))`
+    *
+    * @see https://stackoverflow.com/a/62304377
+    * @param {Object} fields The raw Snapshot to convert
+    * @returns {Object} A JavaScript POJO representing the converted state
+    */
+    static fromFirestoreFields(fields = {}) {
+        const result = {};
+        for (const key in fields) {
+            const value = fields[key];
+            const isDocumentType = [
+                'stringValue', 'booleanValue', 'doubleValue',
+                'integerValue', 'timestampValue', 'mapValue', 'arrayValue', 'nullValue', // Added nullValue
+            ].find(t => t === Object.keys(value)[0]); // Check the first key of the value object
+            if (isDocumentType) {
+                switch (isDocumentType) {
+                    case 'mapValue':
+                        result[key] = Syncro.fromFirestoreFields(value.mapValue.fields || {});
+                        break;
+                    case 'arrayValue': {
+                        const list = value.arrayValue.values;
+                        result[key] = !!list ? list.map((l) => Syncro.fromFirestoreFields(l)) : [];
+                        break;
+                    }
+                    case 'nullValue':
+                        result[key] = null;
+                        break;
+                    default:
+                        result[key] = value[isDocumentType];
+                }
+            }
+            else {
+                // This case might not be standard Firestore field structure, but handle recursively
+                result[key] = Syncro.fromFirestoreFields(value);
+            }
+        }
+        return result;
+    }
+    /**
+    * Perform a one-off fetch of a given Syncro path
+    *
+    * @param {String} path The Syncro entity + ID path. Takes the form `ENTITY::ID`
+    *
+    * @returns {Promise<Object|Null>} An eventual snapshot of the given path, if the entity doesn't exist null is returned
+    */
+    static getSnapshot(path) {
+        const { fsCollection, fsId } = Syncro.pathSplit(path);
+        return Promise.resolve()
+            .then(async () => FirestoreGetDoc(// Set up binding and wait for it to come ready
+        FirestoreDocRef(Syncro.firestore, fsCollection, fsId)))
+            .then(doc => doc.exists() // Use exists() method
+            ? Syncro.fromFirestore(doc.data())
+            : null);
+    }
+    /**
+    * Perform a one-off set/merge operation against
+    *
+    * @param {String} path The Syncro entity + ID path. Takes the form `ENTITY::ID`
+    * @param {Object} state The new state to set/merge
+    *
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {'merge'|'set'} [options.method='merge'] How to apply the new state. 'merge' (merge in partial data to an existing Syncro), 'set' (overwrite the entire Syncro state)
+    *
+    * @returns {Promise<*>} The state object after it has been applied
+    */
+    static setSnapshot(path, state, options) {
+        const settings = {
+            method: 'merge',
+            ...options,
+        };
+        const { fsCollection, fsId } = Syncro.pathSplit(path);
+        const docRef = FirestoreDocRef(Syncro.firestore, fsCollection, fsId);
+        const firestoreData = Syncro.toFirestore(state);
+        return Promise.resolve()
+            .then(() => {
+            if (settings.method === 'merge') {
+                return FirestoreUpdateDoc(docRef, firestoreData);
+            }
+            else { // method === 'set'
+                return FirestoreSetDoc(docRef, firestoreData); // Default set overwrites
+            }
+        })
+            .then(() => state);
+    }
+    /**
+    * Mount the remote Firestore document against this Syncro instance
+    *
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {Object} [options.initialState] State to use if no state is already loaded, overrides the entities own `initState` function fetcher
+    * @param {Number} [options.retries=3] Number of times to retry if a mounted Syncro fails its sanity checks
+    * @returns {Promise<Syncro>} A promise which resolves as this syncro instance when completed
+    */
+    mount(options) {
+        const settings = {
+            initialState: null,
+            retries: 5,
+            retryMinTime: 250,
+            ...options,
+        };
+        const { fsCollection, fsId, entity } = Syncro.pathSplit(this.path);
+        let reactive; // Eventual response from reactive() with the initial value
+        let doc; // Eventual Firebase document
+        return PromiseRetry(async () => {
+            await this.setHeartbeat(false); // Disable any existing heartbeat
+            // Set up binding and wait for it to come ready
+            this.docRef = FirestoreDocRef(Syncro.firestore, fsCollection, fsId);
+            // Initialize state
+            let initialState = await this.getFirestoreState();
+            // If we have a project that has `users` (written by the invite system)
+            // but lacks core data like `name` 9implying a full sync hasn't happened),
+            // we assume the document is corrupted/partial.
+            if (this.path.startsWith('projects::') &&
+                initialState &&
+                !isEmpty(initialState) &&
+                initialState.users &&
+                (!initialState.type && !initialState.name && !initialState.created)) {
+                this.debugError('Zombie state detected (Partial document). Forcing repair...');
+                // Force the backend to wipe and re-sync this entity
+                const repairRes = await fetch(`${this.config.syncroRegistryUrl}/${this.path}?drop=1&force=1`);
+                if (repairRes.ok) {
+                    this.debug('Repair signal sent successfully. Reloading local state...');
+                    // Fetch the newly corrected state from Firestore
+                    initialState = await this.getFirestoreState();
+                }
+                else {
+                    console.error('[Syncro] Self-healing failed', repairRes.statusText);
+                }
+            }
+            // Construct a reactive component
+            reactive = this.getReactive(initialState);
+            if (!reactive.doc || !reactive.setState || !reactive.getState || !reactive.watch)
+                throw new Error('Syncro.getReactive() requires a returned `doc`, `setState()`, `getState()` + `watch()`');
+            // Accept throttling for reactiveWrapper if present
+            if (reactive.throttle) { // Wanting to throttle - handed either truthy or an object of throttle settings
+                let throttleSettings = {
+                    limit: 2,
+                    interval: 100, // i.e. 2 calls within 100ms, otherwise throttle
+                    strict: false,
+                    ...(typeof reactive.throttle == 'object' && reactive.throttle), // Import throttle settings if any
+                };
+                // Wrap original reactive.setState() in a throttle function
+                let originalSetState = reactive.setState;
+                reactive.setState = PromiseThrottle({
+                    limit: throttleSettings.limit,
+                    interval: throttleSettings.interval,
+                    onDelay: () => this.debug('Throttling excessive Syncro.setState() writes'),
+                })(originalSetState);
+            }
+            this.value = doc = reactive.doc;
+            this.debug('Initial state', { doc });
+            // Subscribe to remote updates
+            const unsubscribe = FirestoreOnSnapshot(this.docRef, snapshot => {
+                const snapshotData = Syncro.fromFirestore(snapshot.data());
+                this.debug('Incoming snapshot', { snapshotData });
+                reactive.setState(snapshotData);
+            });
+            this._destroyActions.push(unsubscribe);
+            // Optionally create the doc if it has no content
+            if (!isEmpty(doc)) { // Doc already has content - skip
+                // Do nothing
+            }
+            else if (settings.initialState) { // Provided an initialState
+                this.debug('Populate initial Syncro state (from provided initialState)');
+                await this.setFirestoreState(settings.initialState, { method: 'set' });
+            }
+            else {
+                // Doc is empty (or was missing).
+                this.debug(`Populate initial Syncro state (from "${entity}" Syncro worker)`);
+                const response = await fetch(`${this.config.syncroRegistryUrl}/${this.path}`);
+                if (!response.ok) {
+                    throw new Error(`Failed to check Syncro "${fsCollection}::${fsId}" status - ${response.statusText}`);
+                }
+            }
+            // Setup local state watcher
+            reactive.watch(throttle((newState) => {
+                this.debug('Local change', { newState });
+                this.markDirty();
+                this.setFirestoreState(newState, { method: 'merge' }); // eslint-disable-line @typescript-eslint/no-floating-promises
+            }, this.throttle));
+            await this.setHeartbeat(true, {
+                immediate: true,
+            });
+            return this;
+        }, {
+            retries: settings.retries,
+            minTimeout: settings.retryMinTime,
+            randomize: true,
+            factor: 3,
+            onFailedAttempt: async (e) => {
+                this.debugError(`[Attempt ${e.attemptNumber}/${e.attemptNumber + e.retriesLeft - 1}] to mount syncro`, e);
+                await this.destroy();
+            },
+        });
+    }
+    /**
+    * Merge a single or multiple values into a Syncro data object
+    * NOTE: Default behaviour is to flush (if any changes apply), use direct object mutation or disable with `flush:false` to disable
+    *
+    * @param {String|Object} key Either the single named key to set OR the object to merge
+    * @param {*} [value] The value to set if `key` is a string
+    *
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {Boolean} [options.delta=true] Only merge keys that differ, skipping flush if no changes are made
+    * @param {Boolean} [options.flush=true] Send a flush signal that Firebase should sync to Supabase on changes
+    * @param {Boolean} [options.forceFlush=false] Flush even if no changes were made
+    * @param {Boolean} [options.flushDestroy=false] Destroy the Syncro after flushing
+    *
+    * @returns {Promise<Syncro>} A promise which resolves with this Syncro instance on completion
+    */
+    async set(key, value, options) {
+        // Argument mangling - [key, value, settings] -> changes{}, settings {{{
+        let changes;
+        if (typeof key == 'string') { // Called as (key:String, value:*, options?:Object)
+            changes[key] = value;
+        }
+        else if (typeof key == 'object') { // Called as (changes:Object, options?:Object)
+            [changes, options] = [key, value];
+        }
+        else {
+            throw new Error('Unknown call signature for set() - call with string+value or object');
+        }
+        // }}}
+        const settings = {
+            delta: true,
+            flush: true,
+            forceFlush: false,
+            flushDestroy: false,
+            ...options,
+        };
+        // Perform merge
+        let hasChanges = false;
+        if (settings.delta) { // Merge changes lazily
+            Object.entries(changes)
+                .filter(([k, v]) => !isEqual(this.value[k], v))
+                .forEach(([k, v]) => {
+                hasChanges = true;
+                this.value[k] = v;
+            });
+        }
+        else {
+            hasChanges = true;
+            Object.assign(this.value, changes);
+        }
+        // Optionally perform flush
+        if ((settings.forceFlush || hasChanges)
+            && settings.flush) {
+            await this.flush({ destroy: settings.flushDestroy });
+        }
+        return this;
+    }
+    /**
+    * Schedule Syncro heartbeats
+    * This populates the `sync` presence meta-information
+    *
+    * @param {Boolean} [enable=true] Whether to enable heartbeats
+    *
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {Boolean} [options.immediate=false] Fire a heartbeat as soon as this function is called, this is only really useful on mount
+    * @returns {Promise|Void} A promise that resolves when completed (if `{immediate:true}`) or void
+    */
+    setHeartbeat(enable = true, options) {
+        const settings = {
+            immediate: true,
+            ...options,
+        };
+        // Clear existing heartbeat timer, if there is one
+        clearTimeout(this._heartbeatTimer);
+        if (enable) {
+            const heartbeatAction = async () => {
+                // Perform the heartbeat
+                await this.heartbeat();
+                // If we're enabled - schedule the next heartbeat timer
+                if (enable)
+                    this.setHeartbeat(true); // eslint-disable-line @typescript-eslint/no-floating-promises
+            };
+            this._heartbeatTimer = setTimeout(heartbeatAction, this.config.heartbeatInterval);
+            if (settings.immediate)
+                return this.heartbeat(); // Return the promise from immediate heartbeat
+        }
+    }
+    /**
+    * Perform one heartbeat pulse to the server to indicate presence within this Syncro
+    * This function is automatically called by a timer if `setHeartbeat(true)` (the default behaviour)
+    *
+    * @returns {Promise} A promise which resolves when the operation has completed
+    */
+    async heartbeat() {
+        this.debug('heartbeat!');
+        try {
+            const response = await fetch(`${this.config.syncroRegistryUrl}/${this.path}/heartbeat`, {
+                method: 'post',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    session: Syncro.session,
+                    ...(this.isDirty && { dirty: true }),
+                }),
+            });
+            if (!response.ok) {
+                console.warn(this.path, `Heartbeat failed - ${response.statusText}`, { response });
+            }
+            this.isDirty = false; // Reset the dirty flag if it is set
+        }
+        catch (error) {
+            console.warn(this.path, 'Heartbeat fetch error', error);
+            // Decide if isDirty should be reset on network error
+        }
+    }
+    /**
+    * Utility function to directly set this documents firestore state
+    *
+    * @param {Object} state The state to set / merge
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {'merge'|'set'} [options.method='merge'] How to apply the new state. 'merge' (merge in partial data to an existing Syncro), 'set' (overwrite the entire Syncro state)
+    *
+    * @param {number} retries How many tries to take before erroring
+    * @returns {Promise} A promise which resolves when the operation has completed
+    */
+    async setFirestoreState(state, options, retries = 0) {
+        const settings = {
+            method: 'merge',
+            ...options,
+        };
+        if (!this.docRef)
+            throw new Error('mount() must be called before setting Firestore state');
+        const firestoreData = Syncro.toFirestore(state);
+        try {
+            if (settings.method === 'merge') {
+                return await FirestoreUpdateDoc(this.docRef, firestoreData);
+            }
+            else { // method === 'set'
+                return await FirestoreSetDoc(this.docRef, firestoreData);
+            }
+        }
+        catch (e) {
+            if (e instanceof FirebaseError && e.code === 'not-found') {
+                if (retries < 3) {
+                    console.warn('Firebase syncro document does not exist during document update, reinitializing...');
+                    // Reinitialize the firestore syncro document
+                    const response = await fetch(`${this.config.syncroRegistryUrl}/${this.path}?force=1`);
+                    if (!response.ok) {
+                        console.error('Failed to reinitialize Syncro');
+                    }
+                    // Retry the request
+                    return await this.setFirestoreState(state, options, retries + 1);
+                }
+                else {
+                    console.warn('Max retries exceeded while trying to recover firestore syncro document, throwing error');
+                }
+            }
+            console.error(`Error during Firestore operation (${settings.method}) on doc: ${this.docRef.path}`, e);
+            throw e;
+        }
+    }
+    /**
+    * Utility method to fetch the Firestore state for this Syncro
+    * NOTE: This directly extracts the state of the Firestore, not its wrapping doc object returned by `FirestoreGetDoc`
+    *
+    * @returns {Promise<Object>} A promise which resolves to the Firestore state
+    */
+    getFirestoreState() {
+        if (!this.docRef)
+            throw new Error('mount() must be called before getting Firestore state');
+        return FirestoreGetDoc(this.docRef)
+            .then(doc => Syncro.fromFirestore(doc.data() ?? {})); // Handle undefined data with default {}
+    }
+    /**
+    * Set the Syncro dirty flag which gets passed to the server on the next heartbeat
+    *
+    * @see isDirty
+    * @returns {Syncro} This chainable Syncro instance
+    */
+    markDirty() {
+        this.isDirty = true;
+        return this;
+    }
+    /**
+    * Force the server to flush state
+    * This is only really useful for debugging as this happens automatically anyway
+    *
+    * @param {Object} [options] Additional options to mutate behaviour
+    * @param {Boolean} [options.destroy=false] Instruct the server to also dispose of the Syncro state
+    *
+    * @returns {Promise} A promise which resolves when the operation has completed
+    */
+    flush(options) {
+        const settings = {
+            destroy: false,
+            ...options,
+        };
+        return fetch(`${this.config.syncroRegistryUrl}/${this.path}/flush` + (settings.destroy ? '?destroy=1' : ''))
+            .then(response => response.ok
+            ? null
+            : Promise.reject(response.statusText || 'An error occurred'));
+    }
+    /**
+    * Timer handle for heartbeats
+    *
+    * @type {any}
+    */
+    _heartbeatTimer; // Using any for simplicity with NodeJS.Timeout / number
+}
+/**
+* Build a chaotic random tree structure based on dice rolls
+* This function is mainly used for sync testing
+*
+* @param {Number} [depth=0] The current depth we are starting at, changes the nature of branches based on probability
+*
+* @returns {*} The current branch contents
+*/
+export function randomBranch(depth = 0) {
+    const dice = // Roll a dice to pick the content
+     depth == 0 ? 10 // first roll is always '10'
+        : random(0, 11 - depth, false); // Subsequent rolls bias downwards based on depth (to avoid recursion)
+    return (dice == 0 ? false
+        : dice == 1 ? true
+            : dice == 2 ? random(1, 10_000)
+                : dice == 3 ? (new Date(random(1_000_000_000_000, 1_777_777_777_777))).toISOString()
+                    : dice == 5 ? Array.from({ length: random(1, 10) }, () => random(1, 10)) // Added return type hint
+                        : dice == 6 ? null
+                            : dice < 8 ? Array.from({ length: random(1, 10) }, () => randomBranch(depth + 1)) // Added return type hint
+                                : Object.fromEntries(Array.from({ length: random(1, 5) })
+                                    .map((v, k) => [
+                                    sample(['foo', 'bar', 'baz', 'quz', 'flarp', 'corge', 'grault', 'garply', 'waldo', 'fred', 'plugh', 'thud'])
+                                        + `_${k}`,
+                                    randomBranch(depth + 1),
+                                ])));
+}
+/**
+* Syncro specific version of the base NPM:@momsfriendlydevco/marshal config
+* Designed to be used when calling marshal.serialize() + marshal.deserialize()
+*/
+const marshalBaseConfig = {
+    circular: false,
+    clone: true, // Clone away from original so we don't trigger a loop within Firebase
+    modules: [
+        {
+            id: `~array`,
+            recursive: true,
+            test: (v) => Array.isArray(v),
+            serialize: (v) => ({ _: '~array', ...v }),
+            deserialize: (v) => {
+                const arr = Array.from({ length: Object.keys(v).length - 1 });
+                Object.entries(v)
+                    .filter(([k]) => k !== '_')
+                    .forEach(([k, val]) => arr[+k] = val); // Changed v to val to avoid shadowing
+                return arr;
+            },
+        },
+        {
+            id: '~function',
+            test: (v) => typeof v == 'function',
+            serialize: (v, path) => {
+                console.warn('Marshal Warning: Stripping function from path', path.join('.'));
+                throw new Error('Function serializing is forbidden');
+            },
+            deserialize: (v, path) => {
+                console.warn('Marshal Warning: Stripping function from path', path.join('.'));
+            },
+        },
+        ...marshal.settings.modules // Use default Marshal modules excepting...
+            .filter((mod) => mod.id != '~function') // Remove the Marshal function module as this upsets Cloudflare workers by using the `eval` built-in
+    ],
+};
+//# sourceMappingURL=syncro.js.map