Move browser persistence utilities into engine persistence - PR_26140_047-move-browser-persistence-to-engine

Author: DavidQ

src/engine/persistence/BrowserStorageService.js

@@ -0,0 +1,112 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/20/2026
+BrowserStorageService.js
+*/
+export default class BrowserStorageService {
+  constructor(storage = null) {
+    this.storage = storage;
+  }
+
+  static resolveGlobalStorage(storageName) {
+    try {
+      return globalThis?.[storageName] ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  isSupported() {
+    return !!this.storage;
+  }
+
+  length() {
+    try {
+      return Number(this.storage?.length || 0);
+    } catch {
+      return 0;
+    }
+  }
+
+  key(index) {
+    try {
+      return this.storage?.key(index) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  getItem(key, defaultValue = null) {
+    if (!this.storage || typeof this.storage.getItem !== 'function') {
+      return defaultValue;
+    }
+
+    try {
+      const value = this.storage.getItem(key);
+      return value == null ? defaultValue : value;
+    } catch {
+      return defaultValue;
+    }
+  }
+
+  setItem(key, value) {
+    if (!this.storage || typeof this.storage.setItem !== 'function') {
+      return false;
+    }
+
+    try {
+      this.storage.setItem(key, value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  removeItem(key) {
+    if (!this.storage || typeof this.storage.removeItem !== 'function' || !key) {
+      return { ok: false, message: 'storage entry does not include a supported storage and key' };
+    }
+
+    try {
+      this.storage.removeItem(key);
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+  }
+
+  entries() {
+    const entries = [];
+    const length = this.length();
+    for (let index = 0; index < length; index += 1) {
+      const key = this.key(index);
+      if (!key) {
+        continue;
+      }
+      entries.push({
+        key,
+        rawValue: this.getItem(key, null)
+      });
+    }
+    return entries;
+  }
+
+  saveJson(key, value) {
+    const serialized = JSON.stringify(value);
+    return this.setItem(key, serialized);
+  }
+
+  loadJson(key, defaultValue = null) {
+    const raw = this.getItem(key, null);
+    if (!raw) {
+      return defaultValue;
+    }
+
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return defaultValue;
+    }
+  }
+}

src/engine/persistence/CookieStorageService.js

@@ -4,6 +4,30 @@ David Quesenberry
 03/22/2026
 CookieStorageService.js
 */
+function safeDecodeCookiePart(value) {
+  try {
+    return decodeURIComponent(String(value || ''));
+  } catch {
+    return String(value || '');
+  }
+}
+
+function parseCookieString(cookieText) {
+  const text = String(cookieText || '').trim();
+  if (!text) {
+    return [];
+  }
+  return text.split(';').map((part) => part.trim()).filter(Boolean).map((part) => {
+    const separatorIndex = part.indexOf('=');
+    const rawName = separatorIndex >= 0 ? part.slice(0, separatorIndex) : part;
+    const rawValue = separatorIndex >= 0 ? part.slice(separatorIndex + 1) : '';
+    return {
+      key: safeDecodeCookiePart(rawName),
+      rawValue: safeDecodeCookiePart(rawValue)
+    };
+  }).filter((entry) => entry.key);
+}
+
 export default class CookieStorageService {
   constructor({ documentRef = globalThis.document ?? null } = {}) {
     this.documentRef = documentRef;
@@ -47,4 +71,39 @@ export default class CookieStorageService {
     this.documentRef.cookie = `${encodeURIComponent(name)}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=${path}`;
     return true;
   }
+
+  readCookieString() {
+    try {
+      return String(this.documentRef?.cookie || '');
+    } catch {
+      return '';
+    }
+  }
+
+  entries() {
+    return parseCookieString(this.readCookieString());
+  }
+
+  removeEverywhere(name) {
+    if (!this.documentRef || !name) {
+      return { ok: false, message: 'cookie entry does not include a supported document and key' };
+    }
+
+    try {
+      const encodedKey = encodeURIComponent(name);
+      const expires = 'expires=Thu, 01 Jan 1970 00:00:00 GMT';
+      const maxAge = 'Max-Age=0';
+      this.documentRef.cookie = `${encodedKey}=; ${maxAge}; ${expires}; path=/`;
+      const pathname = String(this.documentRef.location?.pathname || '/');
+      const pathSegments = pathname.split('/').filter(Boolean);
+      let currentPath = '';
+      pathSegments.forEach((segment) => {
+        currentPath += `/${segment}`;
+        this.documentRef.cookie = `${encodedKey}=; ${maxAge}; ${expires}; path=${currentPath}`;
+      });
+      return { ok: true };
+    } catch (error) {
+      return { ok: false, message: error.message };
+    }
+  }
 }

src/engine/persistence/LocalStorageService.js

@@ -0,0 +1,15 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/20/2026
+LocalStorageService.js
+*/
+import BrowserStorageService from './BrowserStorageService.js';
+
+export default class LocalStorageService extends BrowserStorageService {
+  constructor(storage = undefined) {
+    super(storage === undefined
+      ? BrowserStorageService.resolveGlobalStorage('localStorage')
+      : storage);
+  }
+}

src/engine/persistence/SessionStorageService.js

@@ -0,0 +1,15 @@
+/*
+Toolbox Aid
+David Quesenberry
+05/20/2026
+SessionStorageService.js
+*/
+import BrowserStorageService from './BrowserStorageService.js';
+
+export default class SessionStorageService extends BrowserStorageService {
+  constructor(storage = undefined) {
+    super(storage === undefined
+      ? BrowserStorageService.resolveGlobalStorage('sessionStorage')
+      : storage);
+  }
+}

src/engine/persistence/StorageService.js

@@ -4,55 +4,14 @@ David Quesenberry
 03/21/2026
 StorageService.js
 */
-export default class StorageService {
+import BrowserStorageService from './BrowserStorageService.js';
+
+export default class StorageService extends BrowserStorageService {
   constructor(storage = undefined) {
-    this.storage = storage === undefined ? StorageService.resolveDefaultStorage() : storage;
+    super(storage === undefined ? StorageService.resolveDefaultStorage() : storage);
   }
 
   static resolveDefaultStorage() {
-    try {
-      return globalThis.localStorage ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  saveJson(key, value) {
-    if (!this.storage || typeof this.storage.setItem !== 'function') {
-      return false;
-    }
-
-    const serialized = JSON.stringify(value);
-
-    try {
-      this.storage.setItem(key, serialized);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  loadJson(key, fallback = null) {
-    if (!this.storage || typeof this.storage.getItem !== 'function') {
-      return fallback;
-    }
-
-    let raw;
-
-    try {
-      raw = this.storage.getItem(key);
-    } catch {
-      return fallback;
-    }
-
-    if (!raw) {
-      return fallback;
-    }
-
-    try {
-      return JSON.parse(raw);
-    } catch {
-      return fallback;
-    }
+    return BrowserStorageService.resolveGlobalStorage('localStorage');
   }
 }

src/engine/persistence/index.js

@@ -4,7 +4,10 @@ David Quesenberry
 03/21/2026
 index.js
 */
+export { default as BrowserStorageService } from './BrowserStorageService.js';
 export { default as StorageService } from './StorageService.js';
+export { default as LocalStorageService } from './LocalStorageService.js';
+export { default as SessionStorageService } from './SessionStorageService.js';
 export { default as CookieStorageService } from './CookieStorageService.js';
 export { default as SaveSlotManager } from './SaveSlotManager.js';
 export { compressText, decompressText, compressJson, decompressJson } from './CompressionService.js';

src/shared/utils/debugConfigUtils.js

@@ -1,3 +1,4 @@
+import { LocalStorageService } from '../../engine/persistence/index.js';
 import { safeTrim, toLowerSafe } from './stringUtils.js';
 const BUILD_DEBUG_MODE = 'prod';
 const BUILD_DEBUG_ENABLED = false;
@@ -25,35 +26,27 @@ export function normalizeDebugMode(value, fallback = 'prod') {
 }
 
 export function readStoredBoolean(key) {
-  if (!key || typeof globalThis.localStorage === 'undefined') {
+  if (!key) {
     return null;
   }
 
-  try {
-    const value = globalThis.localStorage.getItem(key);
-    if (value === '1') {
-      return true;
-    }
-    if (value === '0') {
-      return false;
-    }
-  } catch {
-    return null;
+  const value = new LocalStorageService().getItem(key, null);
+  if (value === '1') {
+    return true;
+  }
+  if (value === '0') {
+    return false;
   }
 
   return null;
 }
 
 export function writeStoredBoolean(key, value) {
-  if (!key || typeof globalThis.localStorage === 'undefined') {
+  if (!key) {
     return;
   }
 
-  try {
-    globalThis.localStorage.setItem(key, value ? '1' : '0');
-  } catch {
-    // Ignore storage failures to keep startup resilient.
-  }
+  new LocalStorageService().setItem(key, value ? '1' : '0');
 }
 
 export function isLocalDebugEnvironment(documentRef) {

src/tools/common/GameManifestLoader.js

@@ -1,4 +1,5 @@
 import { asPositiveInteger } from "../../shared/number/index.js";
+import { SessionStorageService } from "../../engine/persistence/index.js";
 import { isRecord } from "../../shared/types/typeGuards.js";
 
 export { isRecord };
@@ -36,7 +37,7 @@ export class GameManifestLoader {
   } = {}) {
     this.fetch = fetchRef || windowRef.fetch?.bind(windowRef) || null;
     this.pathParams = pathParams;
-    this.sessionStorage = sessionStorageRef || windowRef.sessionStorage || null;
+    this.sessionStorage = new SessionStorageService(sessionStorageRef || windowRef.sessionStorage || null);
     this.window = windowRef;
   }
 
@@ -62,7 +63,7 @@ export class GameManifestLoader {
     if (!hostContextId) {
       return { ok: false, message: "Workspace launch did not include hostContextId." };
     }
-    const rawValue = this.sessionStorage?.getItem(hostContextId) || "";
+    const rawValue = this.sessionStorage.getItem(hostContextId, "") || "";
     if (!rawValue) {
       return { ok: false, message: `Workspace manifest context was not found in sessionStorage: ${hostContextId}.` };
     }