@open-mercato/shared 0.6.6-develop.6184.1.b7e55f8d61 → 0.6.6-develop.6198.1.0822f97cc6

package/.turbo/turbo-build.log

@@ -1,2 +1,2 @@
-[build:shared] found 224 entry points
+[build:shared] found 225 entry points
 [build:shared] built successfully

package/AGENTS.md

@@ -35,6 +35,7 @@ yarn workspace @open-mercato/shared build
 | `api/` | When building scoped API payloads | `@open-mercato/shared/lib/api/scoped` |
 | `auth/` | When you need wildcard-aware feature matching or shared auth helpers | `@open-mercato/shared/lib/auth/featureMatch` |
 | `boolean/` | When parsing boolean strings from env/query params | `@open-mercato/shared/lib/boolean` |
+| `browser/` | When persisting client UI state to `localStorage` — use the safe wrappers and the versioned-envelope helper instead of raw `localStorage` reads/writes | `@open-mercato/shared/lib/browser/safeLocalStorage`, `@open-mercato/shared/lib/browser/versionedPreference` |
 | `commands/` | When implementing undo/redo command pattern | `@open-mercato/shared/lib/commands` |
 | `commands/flush` | When a command mutates entities across multiple phases (scalar + relation syncs) — wraps phases in a single atomic flush | `@open-mercato/shared/lib/commands/flush` — `withAtomicFlush(em, phases, { transaction? })` |
 | `commands/runCrudCommandWrite` | When a command writes an entity + custom fields + CRUD/index side effects in one logical operation — composes fork → atomic flush → custom-field write → side-effect queue in the only correct order. **Prefer this over composing the primitives by hand for new commands.** | `@open-mercato/shared/lib/commands/runCrudCommandWrite` — `runCrudCommandWrite({ ctx, entityId, action, scope, phases, customFields?, events?, indexer?, sideEffect })` |
@@ -91,6 +92,24 @@ const results = await findWithDecryption(em, 'Entity', filter, { tenantId, organ
 import { parseBooleanToken, parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 ```
 
+### Browser Storage — use the shared helpers instead of raw `localStorage`
+
+Persisted client UI state MUST go through the shared `browser/` helpers, never raw `window.localStorage` reads/writes scattered per component:
+
+```typescript
+import { readJsonFromLocalStorage, writeJsonToLocalStorage } from '@open-mercato/shared/lib/browser/safeLocalStorage'
+import { readVersionedPreference, writeVersionedPreference, clearVersionedPreference } from '@open-mercato/shared/lib/browser/versionedPreference'
+```
+
+- `safeLocalStorage` — SSR-safe, error-swallowing JSON get/set/remove. Use for raw values.
+- `versionedPreference` — wraps a value in a `{ v, data }` envelope so schema changes can migrate or safely discard stale data. `readVersionedPreference(key, version, isValid, fallback, { legacyIsValid })` validates the envelope, discards version-mismatched or malformed data, and (when `legacyIsValid` is supplied) migrates a pre-envelope bare value forward on the next write. `readVersionedIdSet`/`writeVersionedIdSet` are convenience wrappers for the common "set of ids" shape.
+
+**Versioning threshold** — when to reach for `versionedPreference` vs. a raw scalar:
+
+- **Trivial scalar flags** (a single boolean/number/string with no schema to evolve, e.g. `om:sidebarCollapsed`, `om:progress:expanded`) MAY stay raw via `safeLocalStorage` (or a plain `'1'`/`'0'`). Add a one-line comment noting the deliberate choice.
+- **Structured values** (objects, records, arrays of objects — anything whose shape can change incompatibly, e.g. a perspective snapshot, a model-picker selection, a sessions cache) MUST use a versioned envelope so a future shape change can migrate or discard old data instead of crashing or silently corrupting state.
+- A slot that already carries its own inline version discriminator (e.g. `{ v, ... }` checked on read) is already migratable and need not be re-wrapped — re-wrapping changes the on-disk format and discards existing user data.
+
 ### i18n — MUST use for all user-facing strings
 
 ```typescript

package/dist/lib/browser/versionedPreference.js

@@ -0,0 +1,33 @@
+import { readJsonFromLocalStorage, writeJsonToLocalStorage, removeLocalStorageKey } from "./safeLocalStorage.js";
+function readVersionedPreference(key, version, isValid, fallback, options) {
+  const raw = readJsonFromLocalStorage(key, null);
+  if (raw && typeof raw === "object" && !Array.isArray(raw) && "v" in raw && "data" in raw) {
+    const envelope = raw;
+    return envelope.v === version && isValid(envelope.data) ? envelope.data : fallback;
+  }
+  if (options?.legacyIsValid && options.legacyIsValid(raw)) return raw;
+  return fallback;
+}
+function writeVersionedPreference(key, version, data) {
+  writeJsonToLocalStorage(key, { v: version, data });
+}
+function clearVersionedPreference(key) {
+  removeLocalStorageKey(key);
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function readVersionedIdSet(key, version) {
+  return new Set(readVersionedPreference(key, version, isStringArray, [], { legacyIsValid: isStringArray }));
+}
+function writeVersionedIdSet(key, version, ids) {
+  writeVersionedPreference(key, version, Array.from(ids));
+}
+export {
+  clearVersionedPreference,
+  readVersionedIdSet,
+  readVersionedPreference,
+  writeVersionedIdSet,
+  writeVersionedPreference
+};
+//# sourceMappingURL=versionedPreference.js.map

package/dist/lib/browser/versionedPreference.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/browser/versionedPreference.ts"],
+  "sourcesContent": ["import { readJsonFromLocalStorage, writeJsonToLocalStorage, removeLocalStorageKey, type JsonSerializable } from './safeLocalStorage'\n\ntype VersionedEnvelope<T> = { v: number; data: T }\n\nexport function readVersionedPreference<T>(\n  key: string,\n  version: number,\n  isValid: (value: unknown) => value is T,\n  fallback: T,\n  options?: { legacyIsValid?: (value: unknown) => value is T },\n): T {\n  const raw = readJsonFromLocalStorage<JsonSerializable>(key, null)\n  if (raw && typeof raw === 'object' && !Array.isArray(raw) && 'v' in raw && 'data' in raw) {\n    const envelope = raw as { v?: unknown; data?: unknown }\n    return envelope.v === version && isValid(envelope.data) ? envelope.data : fallback\n  }\n  if (options?.legacyIsValid && options.legacyIsValid(raw)) return raw\n  return fallback\n}\n\nexport function writeVersionedPreference<T>(key: string, version: number, data: T): void {\n  writeJsonToLocalStorage(key, { v: version, data } satisfies VersionedEnvelope<T>)\n}\n\nexport function clearVersionedPreference(key: string): void {\n  removeLocalStorageKey(key)\n}\n\nfunction isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === 'string')\n}\n\n/** Convenience pair for the common \"set of ids\" preference shape, with legacy bare-array migration. */\nexport function readVersionedIdSet(key: string, version: number): Set<string> {\n  return new Set(readVersionedPreference<string[]>(key, version, isStringArray, [], { legacyIsValid: isStringArray }))\n}\n\nexport function writeVersionedIdSet(key: string, version: number, ids: Set<string>): void {\n  writeVersionedPreference(key, version, Array.from(ids))\n}\n"],
+  "mappings": "AAAA,SAAS,0BAA0B,yBAAyB,6BAAoD;AAIzG,SAAS,wBACd,KACA,SACA,SACA,UACA,SACG;AACH,QAAM,MAAM,yBAA2C,KAAK,IAAI;AAChE,MAAI,OAAO,OAAO,QAAQ,YAAY,CAAC,MAAM,QAAQ,GAAG,KAAK,OAAO,OAAO,UAAU,KAAK;AACxF,UAAM,WAAW;AACjB,WAAO,SAAS,MAAM,WAAW,QAAQ,SAAS,IAAI,IAAI,SAAS,OAAO;AAAA,EAC5E;AACA,MAAI,SAAS,iBAAiB,QAAQ,cAAc,GAAG,EAAG,QAAO;AACjE,SAAO;AACT;AAEO,SAAS,yBAA4B,KAAa,SAAiB,MAAe;AACvF,0BAAwB,KAAK,EAAE,GAAG,SAAS,KAAK,CAAgC;AAClF;AAEO,SAAS,yBAAyB,KAAmB;AAC1D,wBAAsB,GAAG;AAC3B;AAEA,SAAS,cAAc,OAAmC;AACxD,SAAO,MAAM,QAAQ,KAAK,KAAK,MAAM,MAAM,CAAC,SAAS,OAAO,SAAS,QAAQ;AAC/E;AAGO,SAAS,mBAAmB,KAAa,SAA8B;AAC5E,SAAO,IAAI,IAAI,wBAAkC,KAAK,SAAS,eAAe,CAAC,GAAG,EAAE,eAAe,cAAc,CAAC,CAAC;AACrH;AAEO,SAAS,oBAAoB,KAAa,SAAiB,KAAwB;AACxF,2BAAyB,KAAK,SAAS,MAAM,KAAK,GAAG,CAAC;AACxD;",
+  "names": []
+}

package/dist/lib/version.js

@@ -1,4 +1,4 @@
-const APP_VERSION = "0.6.6-develop.6184.1.b7e55f8d61";
+const APP_VERSION = "0.6.6-develop.6198.1.0822f97cc6";
 const appVersion = APP_VERSION;
 export {
   APP_VERSION,

package/dist/lib/version.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/lib/version.ts"],
-  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.6-develop.6184.1.b7e55f8d61'\nexport const appVersion = APP_VERSION\n"],
+  "sourcesContent": ["// Build-time generated version\nexport const APP_VERSION = '0.6.6-develop.6198.1.0822f97cc6'\nexport const appVersion = APP_VERSION\n"],
   "mappings": "AACO,MAAM,cAAc;AACpB,MAAM,aAAa;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/shared",
-  "version": "0.6.6-develop.6184.1.b7e55f8d61",
+  "version": "0.6.6-develop.6198.1.0822f97cc6",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -93,7 +93,7 @@
     "@mikro-orm/core": "^7.1.4",
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/cache": "0.6.6-develop.6184.1.b7e55f8d61",
+    "@open-mercato/cache": "0.6.6-develop.6198.1.0822f97cc6",
     "dotenv": "^17.4.2",
     "rate-limiter-flexible": "^11.2.0",
     "re2js": "2.8.3",

package/src/lib/browser/__tests__/versionedPreference.test.ts

@@ -0,0 +1,81 @@
+/** @jest-environment jsdom */
+import {
+  readVersionedPreference,
+  writeVersionedPreference,
+  clearVersionedPreference,
+  readVersionedIdSet,
+  writeVersionedIdSet,
+} from '../versionedPreference'
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value as Record<string, unknown>).every((v) => typeof v === 'string')
+}
+
+describe('versionedPreference', () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it('round-trips a value through write then read', () => {
+    writeVersionedPreference('test:a', 1, { foo: 'bar' })
+    expect(readVersionedPreference('test:a', 1, isStringRecord, {})).toEqual({ foo: 'bar' })
+  })
+
+  it('discards data on version mismatch', () => {
+    writeVersionedPreference('test:b', 1, { foo: 'bar' })
+    expect(readVersionedPreference('test:b', 2, isStringRecord, {})).toEqual({})
+  })
+
+  it('discards malformed/invalid envelope data', () => {
+    localStorage.setItem('test:c', JSON.stringify({ v: 1, data: { foo: 42 } }))
+    expect(readVersionedPreference('test:c', 1, isStringRecord, {})).toEqual({})
+  })
+
+  it('migrates a legacy bare (unversioned) value and upgrades it on next write', () => {
+    localStorage.setItem('test:d', JSON.stringify({ foo: 'legacy' }))
+    const value = readVersionedPreference('test:d', 1, isStringRecord, {}, { legacyIsValid: isStringRecord })
+    expect(value).toEqual({ foo: 'legacy' })
+
+    writeVersionedPreference('test:d', 1, value)
+    expect(JSON.parse(localStorage.getItem('test:d')!)).toEqual({ v: 1, data: { foo: 'legacy' } })
+  })
+
+  it('treats a legacy record with a literal "v" key as legacy data, not a malformed envelope', () => {
+    localStorage.setItem('test:legacy-v-key', JSON.stringify({ v: 250, other: 300 }))
+    function isNumberRecord(value: unknown): value is Record<string, number> {
+      return !!value && typeof value === 'object' && !Array.isArray(value)
+        && Object.values(value as Record<string, unknown>).every((v) => typeof v === 'number')
+    }
+    expect(readVersionedPreference('test:legacy-v-key', 1, isNumberRecord, {}, { legacyIsValid: isNumberRecord }))
+      .toEqual({ v: 250, other: 300 })
+  })
+
+  it('does not migrate a legacy value when legacyIsValid is not provided', () => {
+    localStorage.setItem('test:e', JSON.stringify({ foo: 'legacy' }))
+    expect(readVersionedPreference('test:e', 1, isStringRecord, {})).toEqual({})
+  })
+
+  it('clearVersionedPreference removes the key', () => {
+    writeVersionedPreference('test:f', 1, { foo: 'bar' })
+    clearVersionedPreference('test:f')
+    expect(localStorage.getItem('test:f')).toBeNull()
+  })
+
+  describe('readVersionedIdSet / writeVersionedIdSet', () => {
+    it('round-trips a set of ids', () => {
+      writeVersionedIdSet('test:ids', 1, new Set(['a', 'b']))
+      expect(readVersionedIdSet('test:ids', 1)).toEqual(new Set(['a', 'b']))
+    })
+
+    it('migrates a legacy bare string[] array', () => {
+      localStorage.setItem('test:ids-legacy', JSON.stringify(['x', 'y']))
+      expect(readVersionedIdSet('test:ids-legacy', 1)).toEqual(new Set(['x', 'y']))
+    })
+
+    it('falls back to an empty set for malformed entries', () => {
+      localStorage.setItem('test:ids-bad', JSON.stringify({ v: 1, data: [1, 2, 3] }))
+      expect(readVersionedIdSet('test:ids-bad', 1)).toEqual(new Set())
+    })
+  })
+})

package/src/lib/browser/versionedPreference.ts

@@ -0,0 +1,40 @@
+import { readJsonFromLocalStorage, writeJsonToLocalStorage, removeLocalStorageKey, type JsonSerializable } from './safeLocalStorage'
+
+type VersionedEnvelope<T> = { v: number; data: T }
+
+export function readVersionedPreference<T>(
+  key: string,
+  version: number,
+  isValid: (value: unknown) => value is T,
+  fallback: T,
+  options?: { legacyIsValid?: (value: unknown) => value is T },
+): T {
+  const raw = readJsonFromLocalStorage<JsonSerializable>(key, null)
+  if (raw && typeof raw === 'object' && !Array.isArray(raw) && 'v' in raw && 'data' in raw) {
+    const envelope = raw as { v?: unknown; data?: unknown }
+    return envelope.v === version && isValid(envelope.data) ? envelope.data : fallback
+  }
+  if (options?.legacyIsValid && options.legacyIsValid(raw)) return raw
+  return fallback
+}
+
+export function writeVersionedPreference<T>(key: string, version: number, data: T): void {
+  writeJsonToLocalStorage(key, { v: version, data } satisfies VersionedEnvelope<T>)
+}
+
+export function clearVersionedPreference(key: string): void {
+  removeLocalStorageKey(key)
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string')
+}
+
+/** Convenience pair for the common "set of ids" preference shape, with legacy bare-array migration. */
+export function readVersionedIdSet(key: string, version: number): Set<string> {
+  return new Set(readVersionedPreference<string[]>(key, version, isStringArray, [], { legacyIsValid: isStringArray }))
+}
+
+export function writeVersionedIdSet(key: string, version: number, ids: Set<string>): void {
+  writeVersionedPreference(key, version, Array.from(ids))
+}