@quazardous/qdadm 2.19.0 → 2.20.0

package/src/routeState/CookiePersister.ts

@@ -0,0 +1,109 @@
+/**
+ * Route state in a cookie (#2146).
+ *
+ * Here because qdadm already does this — page size lives in a year-long
+ * `qdadm_pageSize` cookie — and a seam that could not express what the
+ * framework already does would be a seam with a hole in it.
+ *
+ * **Every cookie is sent on every request to your origin.** That is the whole
+ * difference from web storage, and the reason this persister is shaped
+ * differently: ONE cookie per scope holding a JSON blob, not one per key. A
+ * list with eight filters would otherwise put eight cookies on every image,
+ * script and API call the page makes.
+ *
+ * Which also means: keep it small, and do not reach for this when
+ * `local_storage` would do. The case for a cookie is state the SERVER needs
+ * to see — a rows-per-page the backend renders against, say. If the server
+ * never reads it, it is paying wire cost for nothing.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { underscoreScopeLocator, type RouteStateScopeLocator } from './keyLocator'
+
+/** The document surface this needs, so a test needs no browser. */
+export interface CookieJar {
+  cookie: string
+}
+
+export interface CookiePersisterOptions {
+  /** Defaults to `document`. */
+  jar?: CookieJar
+  /** How a scope becomes a cookie name. Defaults to `qdadm_offers`. */
+  scopeLocator?: RouteStateScopeLocator
+  /** Lifetime in days. Defaults to 365 — what `qdadm_pageSize` already used. */
+  maxAgeDays?: number
+  /** `SameSite` attribute. Defaults to `Lax`. */
+  sameSite?: 'Strict' | 'Lax' | 'None'
+  /** Path the cookie applies to. Defaults to `/`. */
+  path?: string
+}
+
+export class CookiePersister implements RouteStatePersister {
+  readonly name = 'cookie'
+
+  private readonly _jar: CookieJar
+  private readonly _scopes: RouteStateScopeLocator
+  private readonly _maxAgeDays: number
+  private readonly _sameSite: string
+  private readonly _path: string
+
+  constructor(options: CookiePersisterOptions = {}) {
+    this._jar = options.jar ?? (document as unknown as CookieJar)
+    this._scopes = options.scopeLocator ?? underscoreScopeLocator
+    this._maxAgeDays = options.maxAgeDays ?? 365
+    this._sameSite = options.sameSite ?? 'Lax'
+    this._path = options.path ?? '/'
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const raw = this._readCookie(this._scopes.encode(scope))
+    if (raw === null) return null
+    try {
+      const parsed = JSON.parse(decodeURIComponent(raw))
+      return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
+    } catch {
+      // Somebody else's cookie under our name, or a truncated one. Ignoring it
+      // is right here: unlike a single key, a corrupt blob tells us nothing
+      // partial worth keeping.
+      return null
+    }
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    // The blob is rewritten whole, so the empty-means-absent rule is applied
+    // by dropping keys rather than by removing entries.
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (value === null || value === undefined || value === '') continue
+      kept[key] = value
+    }
+
+    // Nothing left to remember: take the cookie off the wire rather than
+    // shipping `{}` on every request for the next year.
+    if (!Object.keys(kept).length) {
+      this.clear(scope)
+      return
+    }
+
+    this._writeCookie(this._scopes.encode(scope), encodeURIComponent(JSON.stringify(kept)))
+  }
+
+  clear(scope: string): void {
+    const name = this._scopes.encode(scope)
+    this._jar.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=${this._path}; SameSite=${this._sameSite}`
+  }
+
+  private _readCookie(name: string): string | null {
+    for (const part of this._jar.cookie.split(';')) {
+      const separator = part.indexOf('=')
+      if (separator === -1) continue
+      if (part.slice(0, separator).trim() !== name) continue
+      return part.slice(separator + 1)
+    }
+    return null
+  }
+
+  private _writeCookie(name: string, value: string): void {
+    const expires = new Date(Date.now() + this._maxAgeDays * 864e5).toUTCString()
+    this._jar.cookie = `${name}=${value}; expires=${expires}; path=${this._path}; SameSite=${this._sameSite}`
+  }
+}

package/src/routeState/MemoryPersister.ts

@@ -0,0 +1,60 @@
+/**
+ * Route state in memory (#2146).
+ *
+ * Survives navigating away and back within the running app; does not survive
+ * a reload, and is invisible to a link. That makes it the right answer for
+ * state that would be noise anywhere else — a wizard's step, a panel a user
+ * opened once — and the right answer in tests, where a shared `localStorage`
+ * leaks one case into the next.
+ *
+ * THE STORE OUTLIVES THE PERSISTER ON PURPOSE. A list builds its persister on
+ * mount; if the state lived on the instance it would die on unmount, which is
+ * exactly the navigation this is supposed to survive. So the default store is
+ * module-level and shared. Pass your own `store` to get an isolated one —
+ * which is what a test usually wants.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export type RouteStateMemoryStore = Map<string, Record<string, unknown>>
+
+/** The shared default. See the note above on why this is module-level. */
+const defaultStore: RouteStateMemoryStore = new Map()
+
+export interface MemoryPersisterOptions {
+  store?: RouteStateMemoryStore
+}
+
+export class MemoryPersister implements RouteStatePersister {
+  readonly name = 'memory'
+
+  private readonly _store: RouteStateMemoryStore
+
+  constructor(options: MemoryPersisterOptions = {}) {
+    this._store = options.store ?? defaultStore
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const stored = this._store.get(scope)
+    // Copied out, so a caller mutating what it read cannot rewrite history.
+    return stored ? { ...stored } : null
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    const kept: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(state)) {
+      if (value === null || value === undefined || value === '') continue
+      kept[key] = value
+    }
+    if (!Object.keys(kept).length) this._store.delete(scope)
+    else this._store.set(scope, kept)
+  }
+
+  clear(scope: string): void {
+    this._store.delete(scope)
+  }
+}
+
+/** Empty the shared store — for tests that use the default. */
+export function clearRouteStateMemory(): void {
+  defaultStore.clear()
+}

package/src/routeState/NullPersister.ts

@@ -0,0 +1,33 @@
+/**
+ * Route state remembered nowhere (#2146).
+ *
+ * The way to say "this screen forgets" and have it read as a decision. An
+ * embedded list inside a detail view, a picker in a dialog, a preview — none
+ * of them should put anything in the address bar, and none of them should
+ * leave anything behind.
+ *
+ * A no-op object looks like the thing
+ * [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) forbids, and the
+ * difference is the whole point: this one is NAMED. Nothing falls back to it,
+ * nothing resolves to it by accident, and an unknown slug throws rather than
+ * landing here. It does nothing because somebody wrote `routeState: 'none'`,
+ * and that sentence is in the app's source where the next reader will find
+ * it.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+
+export class NullPersister implements RouteStatePersister {
+  readonly name = 'none'
+
+  read(): null {
+    return null
+  }
+
+  write(): void {
+    /* deliberately nothing — see the note above */
+  }
+
+  clear(): void {
+    /* deliberately nothing */
+  }
+}

package/src/routeState/RouteStatePersister.ts

@@ -0,0 +1,86 @@
+/**
+ * Where a route's state is remembered (#2146).
+ *
+ * Not "list state": the list is one CONSUMER of routing state, not the
+ * subject. A detail page's active tab, a dashboard's date range and a child
+ * page's own state are the same problem, and each would invent its own answer
+ * if this seam did not exist — which is exactly how qdadm ended up with five
+ * unrelated persistence sites, one of them a year-long cookie.
+ *
+ * The state is opaque on purpose. Every consumer has its own shape, and a
+ * fixed one here would only fit whichever consumer was written first.
+ *
+ * NOT for chrome preferences. A collapsed sidebar belongs to the person, not
+ * to the route: sending someone a link must not fold their menu. The line is
+ * *what I am looking at* versus *how I like my interface*.
+ */
+export interface RouteStatePersister {
+  /** Everything remembered under this scope, or null when nothing is. */
+  read(scope: string): Record<string, unknown> | null
+  /**
+   * Remember this state under this scope.
+   *
+   * A key whose value is `null`, `undefined` or `''` is REMOVED rather than
+   * stored empty — so a pristine screen leaves no trace, and a shared link
+   * carries only what was actually chosen.
+   */
+  write(scope: string, state: Record<string, unknown>): void
+  clear(scope: string): void
+  /** For diagnostics: which persister answered. */
+  readonly name: string
+}
+
+/**
+ * How a consumer names itself.
+ *
+ * The scope is what makes two lists on one route stop fighting over `page` —
+ * the collision `page-compositions.md` currently tells people to avoid by
+ * switching persistence off entirely.
+ */
+export type RouteStateScope = string
+
+/** A handler as the bootstrap declares it: a slug, or an instance. */
+export type RouteStatePersisterSpec = string | RouteStatePersister
+
+/** Anything that can build a persister from a slug. */
+export type RouteStatePersisterFactory = (slug: string) => RouteStatePersister | null
+
+/** An instance, duck-typed — the same test the storage factory applies. */
+export function isRouteStatePersister(value: unknown): value is RouteStatePersister {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as RouteStatePersister
+  return (
+    typeof candidate.read === 'function' &&
+    typeof candidate.write === 'function' &&
+    typeof candidate.clear === 'function'
+  )
+}
+
+/**
+ * Turn a spec into a persister.
+ *
+ * An unknown slug THROWS. It does not fall back to the URL: a persistence
+ * choice that silently does something else is the exact failure
+ * [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) exists to forbid, and
+ * the one this seam is cleaning up after.
+ */
+export function resolveRouteStatePersister(
+  spec: RouteStatePersisterSpec,
+  factory: RouteStatePersisterFactory
+): RouteStatePersister {
+  if (isRouteStatePersister(spec)) return spec
+
+  if (typeof spec === 'string') {
+    const built = factory(spec)
+    if (built) return built
+    throw new Error(
+      `[qdadm] Unknown route-state persister "${spec}". ` +
+        `Pass a known slug, or an object with read/write/clear.`
+    )
+  }
+
+  throw new Error(
+    `[qdadm] Invalid route-state persister: ${typeof spec}. ` +
+      `Expected a slug or an object with read/write/clear.`
+  )
+}

package/src/routeState/UrlPersister.ts

@@ -0,0 +1,207 @@
+/**
+ * Route state in the query string — the default (#2146).
+ *
+ * The default because it is the only medium where "what I am looking at" is
+ * also "what I can send you". A list URL that does not carry its page is a
+ * link that shows the recipient something else.
+ *
+ * CLEAN AROUND THE EXISTING ROUTER: this goes through the `router` the app
+ * already has, with `replace`, and touches no route declaration. Paging is
+ * not a history step of its own — but the URL must carry the state at the
+ * moment the user leaves, so that coming back restores it.
+ *
+ * Keys are namespaced by scope (`offers.page=2`), which is what stops two
+ * lists on one route from fighting over `page` — the collision
+ * `page-compositions.md` currently tells people to avoid by switching
+ * persistence off.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { dottedKeyLocator, type RouteStateKeyLocator } from './keyLocator'
+
+/** The bits of vue-router this needs, so tests need no real router. */
+/** One query value, shaped as vue-router accepts them. */
+export type UrlPersisterQueryValue = string | number | null | undefined
+
+export interface UrlPersisterRouter {
+  // Values are narrowed to what vue-router's own query type accepts, so the
+  // real router satisfies this without a cast — and so does a two-line fake
+  // in a test.
+  replace(to: { query: Record<string, UrlPersisterQueryValue> }): unknown
+}
+export interface UrlPersisterRoute {
+  query: Record<string, unknown>
+}
+
+export interface UrlPersisterOptions {
+  router: UrlPersisterRouter
+  /** Live route — read at call time, never captured. */
+  route: UrlPersisterRoute
+  /**
+   * How a (scope, key) pair becomes a query parameter. Defaults to
+   * `offers.page`; override to impose your own scheme.
+   */
+  keyLocator?: RouteStateKeyLocator
+  /**
+   * Also read UNPREFIXED keys when the scope has none of its own.
+   *
+   * Transitional, and on by default: qdadm wrote `?page=2` flat before this
+   * seam existed, so links people bookmarked or pasted into tickets carry
+   * that shape. Without this they would silently resolve to page 1 — the
+   * reader would see a wrong screen and no error.
+   *
+   * Writes are always prefixed, so a link refreshes itself the first time
+   * anyone touches the list. Set false to drop the compatibility, and expect
+   * to remove it here in a later version.
+   */
+  readFlatFallback?: boolean
+}
+
+export class UrlPersister implements RouteStatePersister {
+  readonly name = 'url'
+
+  private readonly _router: UrlPersisterRouter
+  private readonly _route: UrlPersisterRoute
+  private readonly _keys: RouteStateKeyLocator
+  private readonly _readFlatFallback: boolean
+
+  constructor(options: UrlPersisterOptions) {
+    this._router = options.router
+    this._route = options.route
+    this._keys = options.keyLocator ?? dottedKeyLocator
+    this._readFlatFallback = options.readFlatFallback ?? true
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    const state: Record<string, unknown> = {}
+    let found = false
+
+    for (const [storedKey, raw] of Object.entries(this._route.query)) {
+      const key = this._keys.decode(scope, storedKey)
+      if (key === null) continue
+      found = true
+      state[key] = decodeValue(raw)
+    }
+
+    if (found || !this._readFlatFallback) return found ? state : null
+
+    // Nothing under this scope: possibly a link written before the seam
+    // existed. Read it flat rather than showing the wrong screen without a
+    // word — but ONLY keys nobody has scoped. `jobs.page` belongs to the jobs
+    // list, and handing it to this one would be worse than ignoring it.
+    const flat: Record<string, unknown> = {}
+    for (const [storedKey, raw] of Object.entries(this._route.query)) {
+      if (this._keys.looksScoped(storedKey)) continue
+      flat[storedKey] = decodeValue(raw)
+    }
+    return Object.keys(flat).length ? flat : null
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    const query: Record<string, UrlPersisterQueryValue> = { ...toQuery(this._route.query) }
+
+    for (const [key, value] of Object.entries(state)) {
+      const param = this._keys.encode(scope, key)
+      // A flat key left by an older link would shadow the prefixed one on the
+      // next read, so writing a scope also retires its legacy twin.
+      if (this._readFlatFallback && param !== key) delete query[key]
+      // Absent, not stored empty: a pristine screen leaves a clean link.
+      if (value === null || value === undefined || value === '') delete query[param]
+      else query[param] = encodeValue(value)
+    }
+
+    this._router.replace({ query })
+  }
+
+  clear(scope: string): void {
+    const query: Record<string, UrlPersisterQueryValue> = { ...toQuery(this._route.query) }
+    let scoped = false
+    for (const storedKey of Object.keys(query)) {
+      if (this._keys.decode(scope, storedKey) === null) continue
+      scoped = true
+      delete query[storedKey]
+    }
+
+    // Clear what read() would have READ, or the URL starts lying: arrive on a
+    // pre-scope `?page=4` link, clear the filters, and the list shows page 1
+    // under an address still claiming page 4 — and a refresh would restore
+    // the state that was just cleared.
+    if (!scoped && this._readFlatFallback) {
+      for (const storedKey of Object.keys(query)) {
+        if (!this._keys.looksScoped(storedKey)) delete query[storedKey]
+      }
+    }
+
+    this._router.replace({ query })
+  }
+}
+
+/**
+ * A value on its way into a URL.
+ *
+ * Primitives stay readable — `page=2`, not `page=%222%22` — because a query
+ * string people paste into tickets is worth more than perfect round-tripping.
+ * Objects and arrays are JSON, which `decodeValue` recognises by its opening
+ * brace.
+ */
+function encodeValue(value: unknown): string {
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+/**
+ * And on its way back out.
+ *
+ * The coercion is deliberately the one `restoreFilters` already applied to
+ * query params, so behaviour does not shift underneath anyone: `'true'`
+ * becomes a boolean, a numeric string becomes a number.
+ *
+ * It follows that a filter whose value is the STRING `'42'` comes back as the
+ * NUMBER 42. That was already true before this seam existed; it is written
+ * down here rather than left to be rediscovered.
+ *
+ * BUT ONLY WHEN NOTHING IS LOST (#2147). `'007'` is not the number 7 and
+ * `'9876667194123456789'` is not the float it would become — those are text
+ * that merely looks numeric, and coercing them hands the app a value the user
+ * never typed. So the coercion happens only when it round-trips exactly, and
+ * anything else stays the string it was. Reference numbers, invoice ids and
+ * phone numbers all live in that gap, and a search box is full of them.
+ */
+function decodeValue(raw: unknown): unknown {
+  if (Array.isArray(raw)) return raw.map(decodeValue)
+  if (typeof raw !== 'string') return raw
+
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  if (raw === 'null') return null
+  if (raw !== '' && !Number.isNaN(Number(raw))) {
+    const asNumber = Number(raw)
+    // The round-trip test IS the rule: if the number cannot be written back
+    // as the exact same text, the text was never a number.
+    if (String(asNumber) === raw) return asNumber
+    return raw
+  }
+
+  const first = raw[0]
+  if (first === '{' || first === '[') {
+    try {
+      return JSON.parse(raw)
+    } catch {
+      // Not JSON after all — a filter value that merely starts with a brace.
+      return raw
+    }
+  }
+
+  return raw
+}
+
+/** The live route's query, narrowed to what we may hand back to the router. */
+function toQuery(query: Record<string, unknown>): Record<string, UrlPersisterQueryValue> {
+  const out: Record<string, UrlPersisterQueryValue> = {}
+  for (const [key, value] of Object.entries(query)) {
+    if (value === null || value === undefined) continue
+    // An array param is one vue-router supports and we do not produce; keep
+    // its first value rather than dropping the key entirely.
+    out[key] = Array.isArray(value) ? (value[0] as UrlPersisterQueryValue) : (String(value) as string)
+  }
+  return out
+}

package/src/routeState/WebStoragePersister.ts

@@ -0,0 +1,149 @@
+/**
+ * Route state in `localStorage` or `sessionStorage` (#2146).
+ *
+ * The medium you pick when the state is worth keeping but not worth putting
+ * in a link: a back-office list somebody returns to twenty times a day, whose
+ * URL nobody ever sends anyone.
+ *
+ * ONE ENTRY PER KEY, namespaced — `qdadm:offers:page`. Not one JSON blob per
+ * scope, because web storage is shared with everything else the app keeps
+ * there, and per-key namespacing is what lets this persister pick out its own
+ * entries without owning the medium. It also means devtools shows you
+ * readable state instead of a blob to decode by hand.
+ *
+ * VALUES ARE JSON, so they come back exactly as they went in. That differs
+ * from `UrlPersister`, which coerces (`'42'` reads back as the number 42)
+ * because a query string is meant to be read by people. A list moved from one
+ * to the other can therefore see a filter value change TYPE — worth knowing
+ * before you switch a screen that compares with `===`.
+ */
+import type { RouteStatePersister } from './RouteStatePersister'
+import { namespacedKeyLocator, type RouteStateKeyLocator } from './keyLocator'
+
+/** The bit of the Storage API this needs, so a test needs no browser. */
+export interface RouteStateStorage {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+  readonly length: number
+  key(index: number): string | null
+}
+
+export interface WebStoragePersisterOptions {
+  /** `window.localStorage` or `window.sessionStorage`, or a stand-in. */
+  storage: RouteStateStorage
+  /** For diagnostics — which medium answered. */
+  name?: string
+  /** How a (scope, key) pair becomes a storage key. Defaults to `qdadm:scope:key`. */
+  keyLocator?: RouteStateKeyLocator
+}
+
+export class WebStoragePersister implements RouteStatePersister {
+  readonly name: string
+
+  private readonly _storage: RouteStateStorage
+  private readonly _keys: RouteStateKeyLocator
+  private _warned = false
+
+  constructor(options: WebStoragePersisterOptions) {
+    this._storage = options.storage
+    this._keys = options.keyLocator ?? namespacedKeyLocator
+    this.name = options.name ?? 'web-storage'
+  }
+
+  /**
+   * Web storage throws rather than returning null in more situations than
+   * people expect: Safari's private mode, a browser set to block site data,
+   * a quota that filled up.
+   *
+   * We warn ONCE and carry on with the screen working. That is not the silent
+   * no-op [ADR 0011](../../docs/adr/0011-no-silent-no-ops.md) forbids — the
+   * failure is announced, and it is the environment's, not a mistake in the
+   * app's configuration. Taking the list down because a page number could not
+   * be remembered would be the worse trade.
+   */
+  private _guard<T>(operation: () => T, fallback: T): T {
+    try {
+      return operation()
+    } catch (error) {
+      if (!this._warned) {
+        this._warned = true
+        console.warn(
+          `[qdadm] Route-state persister "${this.name}" cannot reach its storage; ` +
+            `this screen will not remember its state. ` +
+            `Usually private browsing, blocked site data, or a full quota.`,
+          error
+        )
+      }
+      return fallback
+    }
+  }
+
+  read(scope: string): Record<string, unknown> | null {
+    return this._guard(() => {
+      const state: Record<string, unknown> = {}
+      let found = false
+
+      for (const storedKey of this._ownKeys(scope)) {
+        const key = this._keys.decode(scope, storedKey)
+        if (key === null) continue
+        const raw = this._storage.getItem(storedKey)
+        if (raw === null) continue
+        found = true
+        state[key] = decode(raw)
+      }
+
+      return found ? state : null
+    }, null)
+  }
+
+  write(scope: string, state: Record<string, unknown>): void {
+    this._guard(() => {
+      for (const [key, value] of Object.entries(state)) {
+        const storedKey = this._keys.encode(scope, key)
+        // Absent, not stored empty — the same rule every persister follows,
+        // so a pristine screen leaves no trace whichever medium it uses.
+        if (value === null || value === undefined || value === '') {
+          this._storage.removeItem(storedKey)
+        } else {
+          this._storage.setItem(storedKey, JSON.stringify(value))
+        }
+      }
+    }, undefined)
+  }
+
+  clear(scope: string): void {
+    this._guard(() => {
+      for (const storedKey of this._ownKeys(scope)) {
+        if (this._keys.decode(scope, storedKey) !== null) this._storage.removeItem(storedKey)
+      }
+    }, undefined)
+  }
+
+  /**
+   * Snapshot the key names before touching anything.
+   *
+   * `Storage.key(i)` walks a live collection: removing as you iterate
+   * renumbers what is left and skips entries. Reading the names first is the
+   * difference between clearing a scope and clearing every other one of it.
+   */
+  private _ownKeys(scope: string): string[] {
+    const keys: string[] = []
+    for (let i = 0; i < this._storage.length; i++) {
+      const key = this._storage.key(i)
+      if (key !== null && this._keys.decode(scope, key) !== null) keys.push(key)
+    }
+    return keys
+  }
+}
+
+function decode(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    // Written by something other than us, or truncated. Hand back the string
+    // rather than dropping the key: a readable wrong value beats a silent
+    // absent one.
+    return raw
+  }
+}