@sveltebase/state 0.3.2 → 0.3.4

package/README.md

@@ -1,80 +1,56 @@
 # `@sveltebase/state`
 
-Small rune-friendly state helpers for Svelte 5.
+Small state helpers for Svelte 5.
 
-This package provides two classes:
+This package exports two classes:
 
-- `State<T>` for simple in-memory reactive state
-- `PersistentState<TSchema>` for validated state that is persisted in cookies using `zod`
+- `State<T>`: simple reactive in-memory state
+- `PersistentState<TSchema>`: reactive state backed by cookies and validated with `zod`
 
 ## Install
 
-```bash
-bun add @sveltebase/state zod
-```
+~~~bash
+bun add @sveltebase/state zod svelte
+~~~
 
-You also need `svelte` as a peer dependency:
-
-```bash
-bun add svelte
-```
-
-## What it exports
+## Exports
 
 - `State`
 - `PersistentState`
 
 ## `State`
 
-Use `State` when you want a tiny reactive wrapper around a value.
-
-### Example
+A tiny wrapper around a value.
 
-```ts
+~~~ts
 import { State } from "@sveltebase/state";
 
-const counter = new State(0);
+const count = new State(0);
 
-counter.current = 1;
-counter.set((value) => value + 1);
+count.current = 1;
+count.set((value) => value + 1);
 
-console.log(counter.current); // 2
-```
+console.log(count.current); // 2
+~~~
 
 ### API
 
-#### `new State(initialValue)`
-
-Creates a new reactive state container.
-
-#### `state.current`
-
-Gets or sets the current value.
-
-#### `state.set(updater)`
-
-Updates the current value using a callback.
+- `new State(initialValue)`
+- `state.current`
+- `state.set(updater)`
 
 ## `PersistentState`
 
-Use `PersistentState` when you want state that:
+Cookie-backed state with schema validation.
 
-- is validated with `zod`
-- hydrates from cookies in the browser
-- can be initialized from request cookies during SSR
-- writes changes back to cookies automatically
+It:
 
-## Install requirements
+- reads from cookies
+- validates with `zod`
+- writes updates back to cookies
+- can load the initial value during SSR
 
-`PersistentState` depends on `zod`, so make sure it is installed:
-
-```bash
-bun add zod
-```
-
-## Example
-
-```ts
+~~~ts
 import { z } from "zod";
 import { PersistentState } from "@sveltebase/state";
 
@@ -82,107 +58,95 @@ const themeSchema = z.enum(["light", "dark"]).default("light");
 
 export const theme = new PersistentState("theme", themeSchema);
 
-// read
-console.log(theme.current);
-
-// write
 theme.current = "dark";
-
-// update
 theme.set((value) => (value === "dark" ? "light" : "dark"));
-```
+~~~
 
-## SSR usage
+## SSR setup
 
-When rendering on the server, you can initialize the state from cookies before using it.
+For SSR, return all cookies from `+layout.server.ts`, then initialize the state with `state.init(() => data.cookies)` so it loads the server value first.
 
-```ts
-import { z } from "zod";
-import { PersistentState } from "@sveltebase/state";
+### `src/routes/+layout.server.ts`
 
-const localeSchema = z.enum(["en", "uz"]).default("en");
+~~~ts
+export async function load({ cookies }) {
+  return {
+    cookies: cookies.getAll()
+  };
+}
+~~~
 
-export const locale = new PersistentState("locale", localeSchema);
+### `src/routes/+layout.svelte`
 
-// for example, from a server load or request context:
-locale.init([
-  { name: "locale", value: "\"uz\"" }
-]);
+~~~svelte
+<script lang="ts">
+  import type { LayoutData } from "./$types";
+  import { locale } from "$lib/state";
 
-console.log(locale.current); // "uz"
-```
+  let { data }: { data: LayoutData } = $props();
 
-## How persistence works
+  locale.init(() => data.cookies);
+</script>
 
-`PersistentState` stores the current value in a cookie using the key you pass to the constructor.
+<slot />
+~~~
 
-- On the client, it reads the cookie during hydration
-- On updates, it writes the new value back to the cookie
-- On the server, you can call `init(cookies)` to sync the initial value from request cookies
+### `src/lib/state.ts`
 
-The stored cookie value is JSON-encoded and validated with your `zod` schema.
+~~~ts
+import { z } from "zod";
+import { PersistentState } from "@sveltebase/state";
+
+export const locale = new PersistentState(
+  "locale",
+  z.enum(["en", "uz"]).default("en")
+);
+~~~
+
+With this setup:
+
+- on the server, `init` reads from `data.cookies`
+- the initial SSR render uses that cookie value
+- in the browser, updates keep syncing back to cookies
 
 ## API
 
 ### `new PersistentState(key, schema)`
 
-Creates a persistent reactive state value.
+Creates a persistent state value.
 
 - `key`: cookie name
-- `schema`: `zod` schema used to validate and parse the value
+- `schema`: `zod` schema for parsing and validation
 
 ### `persistentState.current`
 
-Gets or sets the parsed current value.
+Gets or sets the current value.
 
 ### `persistentState.set(updater)`
 
-Updates the current value using a callback.
+Updates the current value.
 
 ### `persistentState.init(cookies)`
 
-Initializes the state from server-side cookies.
+Loads the value from server cookies.
+
+It accepts either:
 
-Expected shape:
+- a cookie array
+- a getter function like `() => data.cookies`
 
-```ts
+Expected cookie shape:
+
+~~~ts
 type Cookie = {
   name: string;
   value: string;
 };
-```
-
-## Example with Svelte
-
-```svelte
-<script lang="ts">
-  import { z } from "zod";
-  import { State, PersistentState } from "@sveltebase/state";
-
-  const count = new State(0);
-  const locale = new PersistentState("locale", z.enum(["en", "uz"]).default("en"));
-
-  function increment() {
-    count.set((value) => value + 1);
-  }
-
-  function toggleLocale() {
-    locale.current = locale.current === "en" ? "uz" : "en";
-  }
-</script>
-
-<button onclick={increment}>
-  Count: {count.current}
-</button>
-
-<button onclick={toggleLocale}>
-  Locale: {locale.current}
-</button>
-```
+~~~
 
 ## Notes
 
-- `PersistentState` uses cookies for persistence
-- values are validated with `zod` before being accepted
-- if cookie data is invalid, the schema fallback/default is used
+- `PersistentState` stores JSON in cookies
+- invalid cookie data falls back to the schema result
+- `init(...)` is for server-side initialization
 - this package is designed for Svelte 5

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { PersistentState, State } from "./state.svelte.js";
+export type { MaybeGetter } from "./state.svelte.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/state.svelte.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export type MaybeGetter<T> = T | (() => T);
 export declare class PersistentState<TSchema extends z.ZodTypeAny> {
     #private;
     private storageKey;
@@ -6,10 +7,10 @@ export declare class PersistentState<TSchema extends z.ZodTypeAny> {
     constructor(key: string, schema: TSchema);
     get current(): z.output<TSchema>;
     set current(newValue: z.output<TSchema>);
-    init(cookies: {
+    init(cookies: MaybeGetter<{
         name: string;
         value: string;
-    }[]): void;
+    }[]>): void;
     set(fn: (value: z.output<TSchema>) => z.output<TSchema>): void;
     private static hydrate;
 }

package/dist/state.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.svelte.d.ts","sourceRoot":"","sources":["../src/state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,qBAAa,eAAe,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU;;IAGvD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAU;gBAEZ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAmBxC,IAAI,OAAO,IAIW,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAFtC;IAED,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAEtC;IAEM,IAAI,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE;IAsB/C,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAI9D,OAAO,CAAC,MAAM,CAAC,OAAO;CAiBvB;AAED,qBAAa,KAAK,CAAC,CAAC;;gBAGN,YAAY,EAAE,CAAC;IAI3B,IAAI,OAAO,IAIQ,CAAC,CAFnB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,EAEnB;IAED,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;CAGxB"}
+{"version":3,"file":"state.svelte.d.ts","sourceRoot":"","sources":["../src/state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAE3C,qBAAa,eAAe,CAAC,OAAO,SAAS,CAAC,CAAC,UAAU;;IAIvD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAU;gBAEZ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAmBxC,IAAI,OAAO,IAIW,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAFtC;IAED,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,EAEtC;IAEM,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAyB5D,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IAI9D,OAAO,CAAC,MAAM,CAAC,OAAO;CAiBvB;AAED,qBAAa,KAAK,CAAC,CAAC;;gBAGN,YAAY,EAAE,CAAC;IAI3B,IAAI,OAAO,IAIQ,CAAC,CAFnB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,EAEnB;IAED,GAAG,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;CAGxB"}

package/dist/state.svelte.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { Cookies } from "@sveltebase/utils";
 export class PersistentState {
     #value = $state();
+    #initialized = false;
     storageKey;
     schema;
     constructor(key, schema) {
@@ -27,10 +28,12 @@ export class PersistentState {
         this.#value = this.schema.parse(newValue);
     }
     init(cookies) {
-        if (hasWindow()) {
+        if (this.#initialized || hasWindow()) {
             return;
         }
-        const rawCookie = cookies.find((cookie) => cookie.name === this.storageKey);
+        this.#initialized = true;
+        const resolvedCookies = unwrap(cookies);
+        const rawCookie = resolvedCookies.find((cookie) => cookie.name === this.storageKey);
         if (!rawCookie) {
             return;
         }
@@ -78,6 +81,9 @@ export class State {
         this.#internalState = fn(this.#internalState);
     }
 }
+function unwrap(value) {
+    return typeof value === "function" ? value() : value;
+}
 function hasWindow() {
     return typeof window !== "undefined";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltebase/state",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,7 +18,7 @@
     }
   },
   "dependencies": {
-    "@sveltebase/utils": "0.3.2",
+    "@sveltebase/utils": "0.3.4",
     "zod": "^4.1.11"
   },
   "peerDependencies": {