feat: add WebStorageStore for persistent (localStorage) caching

[FarajiOranj]

Summary

Closes #84.

Adds a built-in persistent Store so a client's cache can survive page reloads
by persisting to localStorage (or any other Web Storage-compatible source).

drift's cache is already pluggable via the Store interface (with an in-memory
LruStore default), and the README points users to implement their own store
for localStorage. This adds a ready-made one so they don't have to, handling the
tricky parts (BigInt serialization and namespacing) out of the box.

Usage

import { createDrift, WebStorageStore } from "@gud/drift";

const drift = createDrift({
  adapter,
  // Persist the cache to localStorage across page reloads.
  store: new WebStorageStore(),
});

No changes to Client/createDrift were needed, the store option already
accepts any Store instance.

WebStorageStore

• Implements Store, backed by the Web Storage API, localStorage by
  default or any compatible storage (sessionStorage, polyfills) via the
  storage option.
• Write-through: every set persists immediately, so there's no interval to
  manage and no data-loss window.
• Namespaced with a prefix (default "drift:") so entries() and
  clear() only ever touch this store's own keys and never wipe unrelated data
  in the same storage.

Serialization

Web Storage only holds strings, and cached values contain BigInts, so values
go through a serializer (overridable via the serialize/deserialize options).
The default codec (serializeValue/deserializeValue) is designed to be a true
round-trip:

• BigInts are encoded with a sentinel prefix that real cached data never
  collides with (and is escaped in the rare case it could), so neither a
  look-alike string (e.g. a contract string return of "42n") nor an
  arbitrary object value is ever mistaken for a bigint, and malformed data can't
  throw.
• A value with no JSON form (e.g. undefined) is treated as a delete, so
  has/get/entries stay consistent.
• Writes are best-effort: a setItem failure (an exceeded quota or
  private-mode storage) is swallowed so a failed cache write can never fail an
  otherwise-successful read, matching the in-memory LruStore whose set never
  throws.

Tests

WebStorageStore.test.ts covers bigint round-trips, look-alike-string
preservation, unserializable-value handling, best-effort writes on a failing
storage, prefix isolation, persistence across store instances (the reload
scenario), a custom serializer, and the full ClientCache path including
deleteMatches-based invalidation. Also updated the README "Stores" section and
added a changeset.

Possible follow-ups

Happy to add these in separate PRs if useful:

• A TtlStore wrapper for time-based expiry (the linked Bancor inspiration used
  a TTL).
• An async/IndexedDB-backed store; the Store interface already supports async,
  so it can layer on top of this.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7e0fb20

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@gud/drift	Minor
@gud/drift-ethers-v5	Minor
@gud/drift-ethers	Minor
@gud/drift-viem	Minor
@gud/drift-web3	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[FarajiOranj]

Pushed a follow-up hardening commit after auditing the store for edge cases:

• Value codec: the default serializer previously reused drift's key codec (bigint → "<n>n"), which would silently coerce a real cached string like "42n" (e.g. a contract string return) into a BigInt on reload. Bigints are now encoded as an unambiguous tagged wrapper via new serializeValue/deserializeValue helpers, so look-alike strings round-trip intact.
• undefined/unserializable values: set now treats a value with no JSON form as a delete, keeping has/get/entries consistent instead of persisting the literal string "undefined" and later throwing on parse.
• Quota / best-effort writes: a setItem failure (exceeded quota, private-mode storage) is now swallowed so a failed cache write can't fail an otherwise-successful read (matching the in-memory LruStore, whose set never throws).

Added regression tests for each and made the test storage double coerce to strings like real Web Storage.

[FarajiOranj]

A follow-up re-audit caught that my first serialization fix wasn't quite right: encoding bigints as a { "$drift$bigint": ... } wrapper object could collide with a real cached object of that exact shape (silent coercion, or a BigInt() throw that broke entries()/deleteMatches).

Reworked the codec to encode bigints as a sentinel-prefixed string instead of a wrapper object, so no object shape can ever be mistaken for a bigint, look-alike strings like "42n" stay strings, and malformed data is guarded so it can't throw. Verified with a 16-case round-trip repro and new regression tests; a fresh adversarial pass over the new codec came back clean.