feat(PersistedState): connection & null value handling

[huntabyte]

This PR enhances PersistedState to handle null values and adds connection control capabilities.

Changes

Null Value Handling

Previously, users were not able to set the value of the PersistedState to null for reasons unknown to me:

const a = new PersistedState<string | null>("a", "hello")
a.current = null // a no-op
console.log(a.current) // still "hello"

This has been fixed, null can now be stored and retrieved from storage.

Closes #343
Closes #267

Connection Control

Multiple issues have been opened requesting something along the lines of having more control over the values being persisted to storage, mostly focused around removing a persisted value from storage.

This PR adds the ability to control when state connects/syncs to storage, enabling use cases like privacy modes that disable storage.

New API:

1. connected option - start disconnected from storage:

      const state = new PersistedState("key", initialValue, {
        connected: false // start in memory-only mode
      });

2. disconnect() method - disconnect/removes value from storage, preserves current value in memory, stops cross-tab synchronization, prevents future writes to storage (only updates memory)

   const state = new PersistedState("key", "someValue")
   state.disconnect() // removed from storage, value only in memory

3. connect() method - connect to storage after disconnecting/initializing disconnected

   const state = new PersistedState("key", "someValue")
   state.disconnect() // removed from storage, value only in memory
   // later...
   state.connect() // added to storage, will sync when storage is updated

4. connected getter - check connection status

   const state = new PersistedState("key", "someValue")
   console.log(state.connected) // true
   state.disconnect()
   console.log(state.connected) // false

When disconnected:

• State changes are kept in memory only
• Storage changes don't affect the state
• Cross-tab sync is disabled
• Both disconnect() and connect() are idempotent

Closes #208

[changeset-bot]

🦋 Changeset detected

Latest commit: cd5f90c

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

This PR includes changesets to release 1 package

Name	Type
runed	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

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
runed	❌ Failed (View Log)		cd5f90c

[1337MARCEL]

Hi! 👋 Just wondering if there’s any update or timeline for this PR.
These additions would help us a lot. Thanks so much for maintaining this project!

[huntabyte]

cc @TGlide - waiting for his approval before merging!

[TGlide]

I still don't think disconnect should remove from storage, but I think its okay for now! The changes are great overall :)