@onehat/data 1.22.38 → 1.22.39

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@onehat/data",
-	"version": "1.22.38",
+	"version": "1.22.39",
 	"description": "JS data modeling package with adapters for many storage mediums.",
 	"main": "src/index.js",
 	"type": "module",

package/src/Integration/Browser/Repository/LocalStorage.js

@@ -3,6 +3,7 @@
 import OfflineRepository from '@onehat/data/src/Repository/Offline.js';
 import store from 'store2'; // see: https://github.com/nbubna/store#readme
 import _ from 'lodash';
+import { CROSS_TAB_CHANNEL_NAME, CROSS_TAB_MESSAGE_TYPE, CROSS_TAB_EVENT_NAME } from './crossTabConstants.js';
 
 /**
  * Repository representing a browser's LocalStorage implementation
@@ -17,9 +18,183 @@ class LocalStorageRepository extends OfflineRepository {
 
 		this._store = store.namespace(this.schema.name);
 
+		// crossTabSync defaults
+		this._crossTabSyncEnabled = config.crossTabSync === true;
+		this._crossTabChannelName = config.crossTabChannelName || CROSS_TAB_CHANNEL_NAME;
+		this._crossTabChannel = null;
+		this._onCrossTabStorageEvent = null;
+		this._onCrossTabMessageEvent = null;
+
+		this.registerEvent(CROSS_TAB_EVENT_NAME);
+
 		if (this._store.isFake()) {
 			throw new Error('store2 error: persistent storage not established.');
 		}
+
+		this._setupCrossTabSync();
+	}
+
+	/**
+	 * _setupCrossTabSync
+	 * 
+	 * Initialises cross-tab change notification.
+	 * Prefers BroadcastChannel (direct messaging, all modern browsers) and falls back to
+	 * the native window 'storage' event, which browsers fire in every *other* tab whenever
+	 * localStorage is mutated.
+	 */
+	_setupCrossTabSync() {
+		if (!this._crossTabSyncEnabled || typeof window === 'undefined') {
+			return;
+		}
+
+		if (typeof BroadcastChannel !== 'undefined') {
+			this._crossTabChannel = new BroadcastChannel(this._crossTabChannelName);
+			this._onCrossTabMessageEvent = this._handleBroadcastMessage.bind(this);
+			this._crossTabChannel.addEventListener('message', this._onCrossTabMessageEvent);
+			return;
+		}
+
+		if (_.isFunction(window.addEventListener)) {
+			this._onCrossTabStorageEvent = this._handleStorageEvent.bind(this);
+			window.addEventListener('storage', this._onCrossTabStorageEvent);
+		}
+	}
+
+	/**
+	 * _teardownCrossTabSync
+	 * 
+	 * Removes all cross-tab listeners and closes the BroadcastChannel.
+	 * Called from destroy() to prevent memory leaks and stale event handlers after
+	 * the repository is no longer in use.
+	 */
+	_teardownCrossTabSync() {
+		if (typeof window !== 'undefined' && _.isFunction(window.removeEventListener) && this._onCrossTabStorageEvent) {
+			window.removeEventListener('storage', this._onCrossTabStorageEvent);
+			this._onCrossTabStorageEvent = null;
+		}
+
+		if (this._crossTabChannel) {
+			if (this._onCrossTabMessageEvent) {
+				this._crossTabChannel.removeEventListener('message', this._onCrossTabMessageEvent);
+				this._onCrossTabMessageEvent = null;
+			}
+			this._crossTabChannel.close();
+			this._crossTabChannel = null;
+		}
+	}
+
+	/**
+	 * _getNamespacedKey
+	 * 
+	 * 
+	 * Returns the fully-qualified storage key that store2 uses for a given entry name.
+	 * store2 namespaces keys with a prefix derived from the schema name, so the raw
+	 * key and the actual localStorage key differ. Broadcasting the namespaced key lets
+	 * recipients correlate messages with what they see in raw storage APIs.
+	 */
+	_getNamespacedKey(name) {
+		if (!this._store || !_.isFunction(this._store._in)) {
+			return name;
+		}
+		return this._store._in(name);
+	}
+
+	/**
+	 * _emitCrossTabStorageChange
+	 * 
+	 * Emits the crossTabStorageChange event on this repository instance.
+	 * Attaches standard repository identity fields so listeners always know which
+	 * repository triggered the change, regardless of how many are registered.
+	 */
+	_emitCrossTabStorageChange(data = {}) {
+		this.emit(CROSS_TAB_EVENT_NAME, {
+			repositoryId: this.id,
+			repositoryName: this.name,
+			repositoryType: this.type,
+			...data,
+		});
+	}
+
+	/**
+	 * _handleBroadcastMessage
+	 * 
+	 * Handles an incoming BroadcastChannel message from another tab.
+	 * Filters out messages that are not storage-change notifications, messages
+	 * originating from this same repository instance (echo prevention), and messages
+	 * intended for a different repository, then re-emits the change locally.
+	 */
+	_handleBroadcastMessage(event) {
+		const data = event?.data;
+		if (!data || data.type !== CROSS_TAB_MESSAGE_TYPE) {
+			return;
+		}
+		if (data.repositoryId === this.id) {
+			return;
+		}
+		if (data.repositoryName !== this.name) {
+			return;
+		}
+
+		this._emitCrossTabStorageChange({
+			source: 'broadcast',
+			operation: data.operation,
+			key: data.key,
+			namespacedKey: data.namespacedKey,
+			timestamp: data.timestamp,
+		});
+	}
+
+	/**
+	 * _handleStorageEvent
+	 * 
+	 * Handles the native window 'storage' event, which fires in every tab *except*
+	 * the one that made the change. Used as a fallback when BroadcastChannel is
+	 * unavailable. Filters to keys belonging to this repository's store2 namespace,
+	 * then derives the operation from whether the new value is null (delete) or not.
+	 */
+	_handleStorageEvent(event) {
+		if (!event || !event.key) {
+			return;
+		}
+		const namespace = this._store?._ns;
+		if (!namespace || !event.key.startsWith(namespace)) {
+			return;
+		}
+
+		const key = event.key.replace(namespace, '');
+		if (!key) {
+			return;
+		}
+
+		this._emitCrossTabStorageChange({
+			source: 'storage',
+			operation: _.isNil(event.newValue) ? 'delete' : 'set',
+			key,
+			namespacedKey: event.key,
+			timestamp: Date.now(),
+		});
+	}
+
+	/**
+	 * Posts a structured message to the BroadcastChannel so other tabs can react
+	 * to a storage mutation made in this tab. Only called when BroadcastChannel is
+	 * available; the storage-event fallback path does not require an explicit broadcast
+	 * because the browser fires the 'storage' event automatically.
+	 */
+	_broadcastStorageChange(name, operation) {
+		if (!this._crossTabSyncEnabled || !this._crossTabChannel) {
+			return;
+		}
+
+		this._crossTabChannel.postMessage({
+			type: CROSS_TAB_MESSAGE_TYPE,
+			repositoryId: this.id,
+			repositoryName: this.name,
+			operation,
+			key: name || null,
+			namespacedKey: _.isNil(name) ? null : this._getNamespacedKey(name),
+			timestamp: Date.now(),
+		});
 	}
 
 	_storageGetValue(name){
@@ -62,7 +237,9 @@ class LocalStorageRepository extends OfflineRepository {
 				value = JSON.stringify(value);
 			}
 
-			return this._store(name, value);
+			const result = this._store(name, value);
+			this._broadcastStorageChange(name, 'set');
+			return result;
 
 		} catch (error) {
 			if (this.debugMode) {
@@ -82,7 +259,9 @@ class LocalStorageRepository extends OfflineRepository {
 				console.log(this.name, 'LocalStorage.delete', name);
 			}
 
-			return this._store.remove(name);
+			const result = this._store.remove(name);
+			this._broadcastStorageChange(name, 'delete');
+			return result;
 
 		} catch (error) {
 			if (this.debugMode) {
@@ -93,7 +272,19 @@ class LocalStorageRepository extends OfflineRepository {
 	}
 
 	clearAll() {
-		return this._store.clearAll();
+		const result = this._store.clearAll();
+		this._broadcastStorageChange(null, 'clearAll');
+		return result;
+	}
+
+	/**
+	 * Cleans up cross-tab sync resources before delegating to the parent destroy.
+	 * Ensures the BroadcastChannel is closed and event listeners are removed so the
+	 * repository does not continue to react to storage events after disposal.
+	 */
+	destroy() {
+		this._teardownCrossTabSync();
+		super.destroy();
 	}
 
 };

package/src/Integration/Browser/Repository/SecureLocalStorage.js

@@ -69,7 +69,9 @@ class SecureLocalStorageRepository extends LocalStorageRepository {
 
 			value = AES.encrypt(value, this.passphrase).toString(); // MOD
 
-			return this._store(name, value);
+			const result = this._store(name, value);
+			this._broadcastStorageChange(name, 'set');
+			return result;
 
 		} catch (error) {
 			if (this.debugMode) {

package/src/Integration/Browser/Repository/SecureSessionStorage.js

@@ -47,8 +47,10 @@ class SecureSessionStorageRepository extends SessionStorageRepository {
 		}
 
 		value = AES.encrypt(value, this.passphrase).toString(); // MOD
-		
-		return this._store.session(name, value);
+
+		const result = this._store.session(name, value);
+		this._broadcastStorageChange(name, 'set');
+		return result;
 	}
 
 };

package/src/Integration/Browser/Repository/SessionStorage.js

@@ -3,6 +3,7 @@
 import OfflineRepository from '@onehat/data/src/Repository/Offline.js';
 import store from 'store2'; // see: https://github.com/nbubna/store#readme
 import _ from 'lodash';
+import { CROSS_TAB_CHANNEL_NAME, CROSS_TAB_MESSAGE_TYPE, CROSS_TAB_EVENT_NAME } from './crossTabConstants.js';
 
 /**
  * Repository representing a browser's SessionStorage implementation
@@ -18,10 +19,136 @@ class SessionStorageRepository extends OfflineRepository {
 		_.merge(this, config);
 
 		this._store = store.namespace(this.schema.name);
-		
+
+		// crossTabSync defaults
+		this._crossTabSyncEnabled = config.crossTabSync === true;
+		this._crossTabChannelName = config.crossTabChannelName || CROSS_TAB_CHANNEL_NAME;
+		this._crossTabChannel = null;
+		this._onCrossTabMessageEvent = null;
+
+		this.registerEvent(CROSS_TAB_EVENT_NAME);
+
 		if (this._store.isFake()) {
 			throw new Error('store2 error: persistent storage not established.');
 		}
+
+		this._setupCrossTabSync();
+	}
+
+	/**
+	 * _setupCrossTabSync
+	 * 
+	 * Initialises cross-tab change notification via BroadcastChannel.
+	 * Unlike LocalStorage, there is no window 'storage' event fallback here because
+	 * browsers never fire that event for sessionStorage mutations. If BroadcastChannel
+	 * is unavailable, cross-tab sync simply does nothing.
+	 */
+	_setupCrossTabSync() {
+		if (!this._crossTabSyncEnabled || typeof window === 'undefined') {
+			return;
+		}
+		if (typeof BroadcastChannel === 'undefined') {
+			return;
+		}
+		this._crossTabChannel = new BroadcastChannel(this._crossTabChannelName);
+		this._onCrossTabMessageEvent = this._handleBroadcastMessage.bind(this);
+		this._crossTabChannel.addEventListener('message', this._onCrossTabMessageEvent);
+	}
+
+	/**
+	 * _teardownCrossTabSync
+	 * 
+	 * Removes the BroadcastChannel message listener and closes the channel.
+	 * Called from destroy() to prevent memory leaks and stale handlers.
+	 */
+	_teardownCrossTabSync() {
+		if (this._crossTabChannel) {
+			if (this._onCrossTabMessageEvent) {
+				this._crossTabChannel.removeEventListener('message', this._onCrossTabMessageEvent);
+				this._onCrossTabMessageEvent = null;
+			}
+			this._crossTabChannel.close();
+			this._crossTabChannel = null;
+		}
+	}
+
+	/**
+	 * _getNamespacedKey
+	 * 
+	 * Returns the fully-qualified storage key that store2 uses for a given entry name.
+	 * store2 namespaces keys with a prefix derived from the schema name, so the raw
+	 * key and the actual sessionStorage key differ. Broadcasting the namespaced key lets
+	 * recipients correlate messages with what they see in raw storage APIs.
+	 */
+	_getNamespacedKey(name) {
+		if (!this._store || !_.isFunction(this._store._in)) {
+			return name;
+		}
+		return this._store._in(name);
+	}
+
+	/**
+	 * _emitCrossTabStorageChange
+	 * 
+	 * Emits the crossTabStorageChange event on this repository instance.
+	 * Attaches standard repository identity fields so listeners always know which
+	 * repository triggered the change, regardless of how many are registered.
+	 */
+	_emitCrossTabStorageChange(data = {}) {
+		this.emit(CROSS_TAB_EVENT_NAME, {
+			repositoryId: this.id,
+			repositoryName: this.name,
+			repositoryType: this.type,
+			...data,
+		});
+	}
+
+	/**
+	 * _handleBroadcastMessage
+	 * 
+	 * Handles an incoming BroadcastChannel message from another tab.
+	 * Filters out non-storage-change messages, echoes from this same instance,
+	 * and messages for unrelated repositories, then re-emits the change locally.
+	 */
+	_handleBroadcastMessage(event) {
+		const data = event?.data;
+		if (!data || data.type !== CROSS_TAB_MESSAGE_TYPE) {
+			return;
+		}
+		if (data.repositoryId === this.id) {
+			return;
+		}
+		if (data.repositoryName !== this.name) {
+			return;
+		}
+		this._emitCrossTabStorageChange({
+			source: 'broadcast',
+			operation: data.operation,
+			key: data.key,
+			namespacedKey: data.namespacedKey,
+			timestamp: data.timestamp,
+		});
+	}
+
+	/**
+	 * _broadcastStorageChange
+	 * 
+	 * Posts a structured message to the BroadcastChannel so other tabs can react
+	 * to a sessionStorage mutation made in this tab.
+	 */
+	_broadcastStorageChange(name, operation) {
+		if (!this._crossTabSyncEnabled || !this._crossTabChannel) {
+			return;
+		}
+		this._crossTabChannel.postMessage({
+			type: CROSS_TAB_MESSAGE_TYPE,
+			repositoryId: this.id,
+			repositoryName: this.name,
+			operation,
+			key: name || null,
+			namespacedKey: _.isNil(name) ? null : this._getNamespacedKey(name),
+			timestamp: Date.now(),
+		});
 	}
 
 	_storageGetValue(name) {
@@ -40,15 +167,31 @@ class SessionStorageRepository extends OfflineRepository {
 		if (!_.isString(value)) {
 			value = JSON.stringify(value);
 		}
-		return this._store.session(name, value);
+		const result = this._store.session(name, value);
+		this._broadcastStorageChange(name, 'set');
+		return result;
 	}
 
 	_storageDeleteValue(name) {
-		return this._store.session.remove(name);
+		const result = this._store.session.remove(name);
+		this._broadcastStorageChange(name, 'delete');
+		return result;
 	}
 
 	clearAll() {
-		return this._store.session.clearAll();
+		const result = this._store.session.clearAll();
+		this._broadcastStorageChange(null, 'clearAll');
+		return result;
+	}
+
+	/**
+	 * Cleans up cross-tab sync resources before delegating to the parent destroy.
+	 * Ensures the BroadcastChannel is closed and event listeners are removed so the
+	 * repository does not continue to react to storage events after disposal.
+	 */
+	destroy() {
+		this._teardownCrossTabSync();
+		super.destroy();
 	}
 
 };

package/src/Integration/Browser/Repository/crossTabConstants.js

@@ -0,0 +1,5 @@
+/** @module Repository */
+
+export const CROSS_TAB_CHANNEL_NAME = '__onehat_data_cross_tab__';
+export const CROSS_TAB_MESSAGE_TYPE = 'repositoryStorageChanged';
+export const CROSS_TAB_EVENT_NAME = 'crossTabStorageChange';

package/src/OneHatData.js

@@ -16,6 +16,7 @@ import {
 	v4 as uuid,
 } from 'uuid';
 import _ from 'lodash';
+import { CROSS_TAB_EVENT_NAME } from './Integration/Browser/Repository/crossTabConstants.js';
 
 /**
  * OneHatData represents a collection of Repositories.
@@ -258,6 +259,9 @@ export class OneHatData extends EventEmitter {
 		if (repository.isRegisteredEvent('logout')) { // OneBuild repository emits this
 			this.relayEventsFrom(repository, ['logout']);
 		}
+		if (repository.isRegisteredEvent(CROSS_TAB_EVENT_NAME)) {
+			this.relayEventsFrom(repository, [CROSS_TAB_EVENT_NAME]);
+		}
 
 		this.emit('createRepository', repository);
 		return repository;