feat: add PersistedState

[Not-Jayden]

Creates reactive state that is persisted and synced across sessions and browser tabs. Inspired by https://github.com/joshnuss/svelte-persisted-store

See docs: https://not-jayden-persisted-state.runed.pages.dev/docs/utilities/persisted-state

[changeset-bot]

🦋 Changeset detected

Latest commit: 41f9495

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	✅ Ready (View Log)	Visit Preview	41f9495

[Not-Jayden]

Self-review notes:

• Maybe just rename to Persisted? Simpler and consistent with the svelte-persisted-store package naming
• Maybe add a reset() method like svelte-persisted-store? Very much a nice-to-have addition useful for only a small set of use cases, with the trade-off that it comes with a small memory overhead of needing to store the initial state. Can ultimately be achieved without needing the explicit method either way.
• svelte-persisted-store also contains the following optional props for error handling and data transformation that I omitted. Don't personally feel they are necessary, though they could easily be added in a later PR if desired.

  onWriteError: (error) => {/* handle or rethrow */}, // Defaults to console.error with the error object
  onParseError: (raw, error) => {/* handle or rethrow */}, // Defaults to console.error with the error object
  beforeRead: (value) => {/* change value after serialization but before setting store to return value*/},
  beforeWrite: (value) => {/* change value after writing to store, but before writing return value to local storage*/},

[huntabyte]

I haven't had a chance to give this a thorough review, but I love what I see.

Regarding the name, I think Persisted is cleaner, though I'll defer to the others if dropping the State makes what it does less obvious.

For something like this, I wonder if we can take it a step further and accept a custom Storage type rather than just the custom serializer/deserializer. We can include adapters for session and local storage out of the box while allowing users to BYOS any storage system they wish as long as it follows our Storage interface.

I'm currently imagining a situation where we could leverage this along with something like Supabase or any real-time DB to bind specific values. If something changes in the DB, it updates, and if something changes that value in the app, it updates the DB. Having a flexible StorageAdapter would be sick for something like this!

[Not-Jayden]

I haven't had a chance to give this a thorough review, but I love what I see.

Regarding the name, I think Persisted is cleaner, though I'll defer to the others if dropping the State makes what it does less obvious.

For something like this, I wonder if we can take it a step further and accept a custom Storage type rather than just the custom serializer/deserializer. We can include adapters for session and local storage out of the box while allowing users to BYOS any storage system they wish as long as it follows our Storage interface.

I'm currently imagining a situation where we could leverage this along with something like Supabase or any real-time DB to bind specific values. If something changes in the DB, it updates, and if something changes that value in the app, it updates the DB. Having a flexible StorageAdapter would be sick for something like this!

@huntabyte thanks! Agree the adapter might be good for future extensibility, I've had a crack at it in this branch: #118

Seems to be working fine but will sanity check it over the weekend to be sure and update docs if all looks good. If you have any feedback in the meantime it would be appreciated to make sure I don't sink too much time into going the wrong direction :)

[huntabyte]

Going to give this a review this week, I promise @Not-Jayden!

Thanks for your patience!

[huntabyte]

Discussing the storage adapter PR with the other maintainers as we speak! Hopefully we can polish it and get this shipped sooner rather than later 😃