@sveltebase/state 0.3.3 → 0.4.0

package/README.md

@@ -1,188 +1,158 @@
 # `@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 a Standard Schema-compatible validator
 
 ## Install
 
-```bash
-bun add @sveltebase/state zod
-```
+~~~bash
+bun add @sveltebase/state svelte
+~~~
 
-You also need `svelte` as a peer dependency:
+If you want to use `zod` as your schema library:
 
-```bash
-bun add svelte
-```
+~~~bash
+bun add zod
+~~~
 
-## 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.
+- `new State(initialValue)`
+- `state.current`
+- `state.set(updater)`
 
-#### `state.current`
-
-Gets or sets the current value.
+## `PersistentState`
 
-#### `state.set(updater)`
+Cookie-backed state with schema validation.
 
-Updates the current value using a callback.
+It:
 
-## `PersistentState`
+- reads from cookies
+- validates with a Standard Schema-compatible validator
+- writes updates back to cookies
+- can load the initial value during SSR
 
-Use `PersistentState` when you want state that:
+~~~ts
+import { z } from "zod";
+import { PersistentState } from "@sveltebase/state";
 
-- is validated with `zod`
-- hydrates from cookies in the browser
-- can be initialized from request cookies during SSR
-- writes changes back to cookies automatically
+const themeSchema = z.enum(["light", "dark"]).default("light");
 
-## Install requirements
+export const theme = new PersistentState("theme", themeSchema);
 
-`PersistentState` depends on `zod`, so make sure it is installed:
+theme.current = "dark";
+theme.set((value) => (value === "dark" ? "light" : "dark"));
+~~~
 
-```bash
-bun add zod
-```
+## SSR setup
 
-## Example
+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 themeSchema = z.enum(["light", "dark"]).default("light");
+~~~ts
+export async function load({ cookies }) {
+  return {
+    cookies: cookies.getAll()
+  };
+}
+~~~
 
-export const theme = new PersistentState("theme", themeSchema);
+### `src/routes/+layout.svelte`
 
-// read
-console.log(theme.current);
+~~~svelte
+<script lang="ts">
+  import type { LayoutData } from "./$types";
+  import { locale } from "$lib/state";
 
-// write
-theme.current = "dark";
+  let { data }: { data: LayoutData } = $props();
 
-// update
-theme.set((value) => (value === "dark" ? "light" : "dark"));
-```
+  locale.init(() => data.cookies);
+</script>
 
-## SSR usage
+<slot />
+~~~
 
-When rendering on the server, you can initialize the state from cookies before using it.
+### `src/lib/state.ts`
 
-```ts
+~~~ts
 import { z } from "zod";
 import { PersistentState } from "@sveltebase/state";
 
 const localeSchema = z.enum(["en", "uz"]).default("en");
 
 export const locale = new PersistentState("locale", localeSchema);
+~~~
 
-// for example, from a server load or request context:
-locale.init([
-  { name: "locale", value: "\"uz\"" }
-]);
-
-console.log(locale.current); // "uz"
-```
-
-## How persistence works
+With this setup:
 
-`PersistentState` stores the current value in a cookie using the key you pass to the constructor.
-
-- 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
-
-The stored cookie value is JSON-encoded and validated with your `zod` schema.
+- 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`: Standard Schema-compatible validator used for parsing and validation, such as a `zod` schema
 
 ### `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:
+
+- a cookie array
+- a getter function like `() => data.cookies`
 
-Expected shape:
+Expected cookie shape:
 
-```ts
+~~~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
+- any Standard Schema-compatible library can be used here, including `zod`
 - this package is designed for Svelte 5

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { PersistentState, State } from "./state.svelte.js";
-export type { MaybeGetter } from "./state.svelte.js";
+export type { InferInput, InferOutput, MaybeGetter, StandardSchemaV1 } 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;AAC3D,YAAY,EAAE,WAAW,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,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EACjB,MAAM,mBAAmB,CAAC"}

package/dist/state.svelte.d.ts

@@ -1,17 +1,43 @@
-import { z } from "zod";
 export type MaybeGetter<T> = T | (() => T);
-export declare class PersistentState<TSchema extends z.ZodTypeAny> {
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            readonly value: Output;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+            }>;
+        } | Promise<{
+            readonly value: Output;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+            }>;
+        }>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+export type InferInput<TSchema extends StandardSchemaV1> = NonNullable<TSchema["~standard"]["types"]>["input"];
+export type InferOutput<TSchema extends StandardSchemaV1> = NonNullable<TSchema["~standard"]["types"]>["output"];
+export declare class PersistentState<TSchema extends StandardSchemaV1> {
     #private;
     private storageKey;
     private schema;
     constructor(key: string, schema: TSchema);
-    get current(): z.output<TSchema>;
-    set current(newValue: z.output<TSchema>);
+    get current(): InferOutput<TSchema>;
+    set current(newValue: InferOutput<TSchema>);
     init(cookies: MaybeGetter<{
         name: string;
         value: string;
     }[]>): void;
-    set(fn: (value: z.output<TSchema>) => z.output<TSchema>): void;
+    set(fn: (value: InferOutput<TSchema>) => InferOutput<TSchema>): void;
     private static hydrate;
 }
 export declare class State<T> {

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,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"}
+{"version":3,"file":"state.svelte.d.ts","sourceRoot":"","sources":["../src/state.svelte.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAE3C,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KAEZ;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;SAAE,GACvD;YAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;gBAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,GAChE,OAAO,CACH;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;SAAE,GACvD;YAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;gBAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CACnE,CAAC;QACN,QAAQ,CAAC,KAAK,CAAC,EAAE;YACf,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;YACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;SACzB,CAAC;KACH,CAAC;CACH;AAED,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,gBAAgB,IACrD,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AAEtD,MAAM,MAAM,WAAW,CAAC,OAAO,SAAS,gBAAgB,IACtD,WAAW,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEvD,qBAAa,eAAe,CAAC,OAAO,SAAS,gBAAgB;;IAI3D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAU;gBAEZ,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAmBxC,IAAI,OAAO,IAIW,WAAW,CAAC,OAAO,CAAC,CAFzC;IAED,IAAI,OAAO,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,EAEzC;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,WAAW,CAAC,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC;IAIpE,OAAO,CAAC,MAAM,CAAC,OAAO;CAoBvB;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

@@ -1,4 +1,3 @@
-import { z } from "zod";
 import { Cookies } from "@sveltebase/utils";
 export class PersistentState {
     #value = $state();
@@ -25,7 +24,7 @@ export class PersistentState {
         return this.#value;
     }
     set current(newValue) {
-        this.#value = this.schema.parse(newValue);
+        this.#value = parseSchema(this.schema, newValue);
     }
     init(cookies) {
         if (this.#initialized || hasWindow()) {
@@ -38,7 +37,7 @@ export class PersistentState {
             return;
         }
         try {
-            const parsed = this.schema.parse(JSON.parse(rawCookie.value));
+            const parsed = parseSchema(this.schema, JSON.parse(rawCookie.value));
             if (JSON.stringify(parsed) !== JSON.stringify(this.#value)) {
                 this.#value = parsed;
             }
@@ -52,18 +51,18 @@ export class PersistentState {
     }
     static hydrate(key, schema) {
         if (!hasWindow()) {
-            return schema.parse(undefined);
+            return parseSchema(schema, undefined);
         }
         const rawCookie = Cookies.get(key);
         if (rawCookie) {
             try {
-                return schema.parse(JSON.parse(rawCookie));
+                return parseSchema(schema, JSON.parse(rawCookie));
             }
             catch {
                 console.warn(`[PersistentState] Invalid data for "${key}". Resetting.`);
             }
         }
-        return schema.parse(undefined);
+        return parseSchema(schema, undefined);
     }
 }
 export class State {
@@ -84,6 +83,16 @@ export class State {
 function unwrap(value) {
     return typeof value === "function" ? value() : value;
 }
+function parseSchema(schema, value) {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+        throw new Error("[PersistentState] Async schemas are not supported.");
+    }
+    if (result.issues) {
+        throw new Error(result.issues.map((issue) => issue.message).join(", ") || "Validation failed.");
+    }
+    return result.value;
+}
 function hasWindow() {
     return typeof window !== "undefined";
 }

package/package.json

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