@vesk/runtime 0.2.59 → 0.2.61

package/dist/store-persistence.js

@@ -0,0 +1,154 @@
+let serverReadHook = null;
+/**
+ * Install server-side persistence hooks (called by the adapter). `read`
+ * returns the persisted raw JSON string (typically from a request cookie) or
+ * null. The hook is a module-level singleton that reads request-scoped state
+ * itself (e.g. `globalThis.__vesk_request`), so installing it once per module
+ * load is safe under concurrent requests.
+ */
+export function installPersistedStoreServerHooks(hooks) {
+    serverReadHook = typeof hooks.read === 'function' ? hooks.read : null;
+}
+/** The request token scoping persisted-key registrations, or '' outside a render. */
+function currentSsrToken() {
+    const g = globalThis;
+    return typeof g.__vsk_ssr_token === 'string' ? g.__vsk_ssr_token : '';
+}
+/** The cookie name a persisted store is mirrored to, for SSR continuity. */
+export function persistedStoreCookieName(storageKey) {
+    return 'vsk_store_' + encodeURIComponent(storageKey);
+}
+const pendingKeys = new Map();
+function bucketFor(token) {
+    const set = pendingKeys.get(token);
+    if (set)
+        return set;
+    const fresh = new Set();
+    pendingKeys.set(token, fresh);
+    return fresh;
+}
+/**
+ * The storage keys of persisted stores constructed in this SSR render.
+ * `token` overrides the ambient request token for callers that drain the
+ * registry outside the render scope (the no-layout streaming path captures
+ * the render token at its `renderPageStream` call site and passes it here).
+ */
+export function getPersistedStoreKeys(token) {
+    const set = pendingKeys.get(token ?? currentSsrToken());
+    return set ? Array.from(set) : [];
+}
+/** Clear the constructed-key registry (called per SSR render by the adapter). */
+export function resetPersistedStoreKeys(token) {
+    pendingKeys.delete(token ?? currentSsrToken());
+}
+/**
+ * Read a persisted store's raw JSON for the current environment:
+ * - server: register the key (so the adapter emits the pre-paint script) and
+ *   ask the installed read hook,
+ * - client: consume `window.__VESK_STORE_INIT__[key]` if present (then write
+ *   it back to localStorage so a later client pickup still works), else read
+ *   localStorage.
+ */
+export function readPersistedStorage(storageKey) {
+    if (!storageKey)
+        return null;
+    if (typeof window === 'undefined') {
+        bucketFor(currentSsrToken()).add(storageKey);
+        return serverReadHook ? (serverReadHook(storageKey) ?? null) : null;
+    }
+    const init = globalThis.__VESK_STORE_INIT__;
+    if (init && init[storageKey] !== undefined) {
+        const raw = init[storageKey];
+        delete init[storageKey];
+        try {
+            localStorage.setItem(storageKey, raw);
+        }
+        catch {
+            /* storage blocked — the in-memory value still applies */
+        }
+        return raw;
+    }
+    try {
+        return localStorage.getItem(storageKey);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a store's raw JSON on the client: localStorage plus a same-site
+ * cookie mirror (best effort, small stores) so the next server render sees it.
+ */
+export function writePersistedStorage(storageKey, raw) {
+    if (!storageKey)
+        return;
+    if (typeof window !== 'undefined') {
+        try {
+            localStorage.setItem(storageKey, raw);
+        }
+        catch {
+            /* storage blocked — the cookie mirror still applies */
+        }
+    }
+    if (typeof document !== 'undefined') {
+        try {
+            document.cookie =
+                persistedStoreCookieName(storageKey) +
+                    '=' +
+                    encodeURIComponent(raw) +
+                    '; path=/; max-age=31536000; SameSite=Lax';
+        }
+        catch {
+            /* cookie blocked — client still persists via localStorage */
+        }
+    }
+}
+/** Remove a persisted store's localStorage record and expire its cookie mirror. */
+export function clearPersistedStorage(storageKey) {
+    if (!storageKey)
+        return;
+    if (typeof window !== 'undefined') {
+        try {
+            localStorage.removeItem(storageKey);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (typeof document !== 'undefined') {
+        try {
+            document.cookie = persistedStoreCookieName(storageKey) + '=; path=/; max-age=0';
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Plain JS that copies each persisted store's localStorage value into
+ * `window.__VESK_STORE_INIT__` before first paint. `serverValues` maps
+ * storageKey → the value the server rendered with (cookie read), used as a
+ * fallback so the very first client visit does not flash defaults.
+ *
+ * This is served as an origin-hosted script file (`/store-init.js?t=<token>`),
+ * never inlined into the HTML, so strict CSP without `unsafe-inline` cannot
+ * block it. Because the file has no HTML context, JSON.stringify output can be
+ * embedded directly (JSON is a valid JS literal) — no escaping needed. Safe
+ * for `</script>`-style content precisely because it never sits inside a
+ * script element.
+ */
+export function buildStorePrePaintPayload(serverValues) {
+    return ('globalThis.__VESK_STORE_INIT__=(function(){' +
+        'var S=' +
+        JSON.stringify(serverValues) +
+        ';' +
+        'var E={};' +
+        'for(var k in S){var v=null;try{v=localStorage.getItem(k);}catch(e){}' +
+        'if(v===null)v=S[k];if(v!=null)E[k]=v;}' +
+        'return E;' +
+        '})();\n');
+}
+/** The `<script src>` reference for one store-init payload token. */
+export function storeInitScriptTag(token) {
+    return '<script src="/store-init.js?t=' + token + '" data-vesk-store-init></script>';
+}

package/dist/store.d.ts

@@ -0,0 +1,61 @@
+import type { StoreMiddleware } from '@vesk/types';
+/**
+ * @typedef Subscriber
+ * A callback that receives the current store state or derived value.
+ * @example
+ * const unsub = store.subscribe(state => console.log(state));
+ */
+type Subscriber<T> = (value: T) => void;
+/**
+ * @typedef StoreOptions
+ * Options for creating a store.
+ * @property persist Whether to persist store in localStorage (default: false)
+ * @property storageKey The key to use in localStorage if persist is true
+ * @property devtools Whether to send devtools events (default: false)
+ */
+interface StoreOptions {
+    persist?: boolean;
+    storageKey?: string;
+    devtools?: boolean;
+}
+/**
+ * @typedef Middleware
+ * A function that runs before or after each update.
+ * @param state Current state of the store
+ * @param action Optional string describing the event
+ * @param payload Optional data passed to update/set
+ */
+type Middleware<T> = StoreMiddleware<T>;
+/**
+ * @function createStore
+ * Creates a reactive store with optional persistence and tools like watch & middleware.
+ *
+ * @param initial The initial state object
+ * @param options Optional store options
+ * @returns Store API with get, set, update, delete, subscribe, derive, watch, use, clear, batch, reset, rehydrate, toJSON
+ *
+ * @example
+ * const counterStore = createStore({ count: 0 });
+ */
+export declare function createStore<T extends object>(initial: T, options?: StoreOptions): {
+    get: () => T;
+    set: (next: T, action?: string) => void;
+    update: {
+        (partial: Partial<T>): void;
+        (partialFn: (prev: T) => Partial<T>): void;
+    };
+    delete: (keys: (keyof T) | (keyof T)[], action?: string) => void;
+    clear: () => void;
+    subscribe: (fn: Subscriber<T>, selector?: (state: T) => any, equals?: (a: any, b: any) => boolean) => () => boolean;
+    watch: <K>(selector: (s: T) => K, callback: (n: K, o: K) => void, equals?: (a: K, b: K) => boolean) => () => void;
+    use: (middleware: Middleware<T>) => () => void;
+    derive: <K>(selector: (s: T) => K, equals?: (a: K, b: K) => boolean) => {
+        subscribe(cb: (v: K) => void): () => boolean;
+    };
+    batch: <R>(fn: () => R) => R;
+    reset: () => void;
+    rehydrate: (newInitial: Partial<T>) => void;
+    toJSON: () => T;
+};
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;GAKG;AACH,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAExC;;;;;;GAMG;AACH,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,KAAK,UAAU,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAExC;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC1C,OAAO,EAAE,CAAC,EACV,OAAO,GAAE,YAAiB;eAqFV,CAAC;gBAKE,CAAC;;kBAaK,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;oBACf,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;;mBAe/B,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE;;oBA2D3C,UAAU,CAAC,CAAC,CAAC,aACN,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,WACnB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,KAAK,OAAO;YAgCvB,CAAC,YACJ,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,YACX,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,WACrB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO;sBAoBT,UAAU,CAAC,CAAC,CAAC;aAgBtB,CAAC,YACL,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,WACZ,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO;sBAGhB,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI;;YAtGjB,CAAC,MAAM,MAAM,CAAC,KAAG,CAAC;;4BAhBF,OAAO,CAAC,CAAC,CAAC;;EAoJ1C"}

package/dist/store.js

@@ -0,0 +1,275 @@
+import { track, flush_sync } from './ripple-runtime.js';
+import { readPersistedStorage, writePersistedStorage, clearPersistedStorage } from './store-persistence.js';
+/**
+ * @function createStore
+ * Creates a reactive store with optional persistence and tools like watch & middleware.
+ *
+ * @param initial The initial state object
+ * @param options Optional store options
+ * @returns Store API with get, set, update, delete, subscribe, derive, watch, use, clear, batch, reset, rehydrate, toJSON
+ *
+ * @example
+ * const counterStore = createStore({ count: 0 });
+ */
+export function createStore(initial, options = {}) {
+    const { persist = false, storageKey, devtools = false } = options;
+    // Load persisted state if enabled — on the server this reads through the
+    // adapter-installed hook (request cookie) and registers the key for the
+    // pre-paint script; on the client it prefers the pre-painted
+    // `window.__VESK_STORE_INIT__` value, then localStorage. Fallback: seed.
+    let value = { ...initial };
+    if (persist && storageKey) {
+        const stored = readPersistedStorage(storageKey);
+        if (stored) {
+            try {
+                value = JSON.parse(stored);
+            }
+            catch { }
+        }
+    }
+    // Reactive cell holding the state
+    const stateCell = track(value);
+    const subs = new Set();
+    const watchers = [];
+    const middlewares = [];
+    let prevValue = { ...value };
+    // Batching state
+    let batchDepth = 0;
+    let dirty = false;
+    /** Notify subscribers and watchers immediately (used when not batching) */
+    function notifyNow(action, payload) {
+        const current = stateCell.get();
+        // Only notify if state changed (reference equality)
+        if (current === prevValue)
+            return;
+        // Notify subscribers
+        subs.forEach(fn => fn(current));
+        // Notify watchers
+        watchers.forEach(({ selector, cb, equals }) => {
+            const eq = equals ?? Object.is;
+            const newVal = selector(current);
+            const oldVal = selector(prevValue);
+            if (!eq(newVal, oldVal))
+                cb(newVal, oldVal);
+        });
+        // Notify middlewares
+        middlewares.forEach(fn => fn(current, action, payload));
+        // Devtools hook
+        if (devtools && typeof window !== "undefined") {
+            const dt = window.__VESK_STORE_DEVTOOLS__;
+            if (dt && typeof dt.send === "function") {
+                dt.send({ type: action, payload, state: structuredClone(current) });
+            }
+        }
+        // Update prevValue
+        prevValue = { ...current };
+    }
+    /** Called by mutators to signal that a change occurred */
+    function notifyDirty(action, payload) {
+        if (batchDepth > 0) {
+            dirty = true;
+        }
+        else {
+            notifyNow(action, payload);
+        }
+    }
+    /** Persist current state if enabled — localStorage plus a same-site cookie
+     *  mirror so the next SSR render serves the user's actual value. */
+    function persistToStorage() {
+        if (persist && storageKey) {
+            try {
+                writePersistedStorage(storageKey, JSON.stringify(stateCell.get()));
+            }
+            catch (err) {
+                console.log("error saving to localStorage: ", err);
+            }
+        }
+    }
+    /** @function get — Returns the current store state */
+    function get() {
+        return stateCell.get();
+    }
+    /** @function set — Replaces the entire store state */
+    function set(next, action = "set") {
+        stateCell.set(next);
+        persistToStorage();
+        notifyDirty(action, next);
+    }
+    function update(partialOrFn, action = "update") {
+        const current = stateCell.get();
+        const patch = typeof partialOrFn === "function" ? partialOrFn(current) : partialOrFn;
+        const next = { ...current, ...patch };
+        stateCell.set(next);
+        persistToStorage();
+        notifyDirty(action, patch);
+    }
+    /** @function delete — Removes one or multiple keys from the store */
+    function deleteKeys(keys, action = "delete") {
+        const current = stateCell.get();
+        const kArray = Array.isArray(keys) ? keys : [keys];
+        const next = { ...current };
+        kArray.forEach(k => {
+            delete next[k];
+        });
+        stateCell.set(next);
+        persistToStorage();
+        notifyDirty(action, keys);
+    }
+    /** @function reset — Resets state to the original initial value (does not affect persistence) */
+    function reset() {
+        stateCell.set({ ...initial });
+        notifyDirty("reset");
+    }
+    /** @function rehydrate — Merges new initial state and updates store (keeps same identity) */
+    function rehydrate(newInitial) {
+        Object.assign(initial, newInitial);
+        stateCell.set({ ...initial });
+        notifyDirty("rehydrate");
+    }
+    /** @function clear — Clears both state and its localStorage record */
+    function clear() {
+        stateCell.set({ ...initial });
+        if (persist && storageKey) {
+            clearPersistedStorage(storageKey);
+        }
+        notifyDirty("clear");
+    }
+    /** @function batch — Runs a batch of synchronous store operations, delaying subscribers until after. */
+    function batch(fn) {
+        batchDepth++;
+        try {
+            return flush_sync(fn);
+        }
+        finally {
+            batchDepth--;
+            if (batchDepth === 0 && dirty) {
+                notifyDirty("batch");
+                dirty = false;
+            }
+        }
+    }
+    /** @function subscribe
+     * Subscribes to all store changes (full state or a selected part).
+     *
+     * @param {Function} fn Callback to receive state or selected part
+     * @param {Function} [selector] Optional selector to receive subset
+     *
+     * @example
+     * store.subscribe(s => console.log(s)); // full state
+     * store.subscribe(s => console.log(s.theme), s => s.theme); // only theme
+     */
+    function subscribe(fn, selector, equals) {
+        const eq = equals ?? Object.is;
+        let hasPrev = false;
+        let prev;
+        const wrapper = selector
+            ? (state) => {
+                const selected = selector(state);
+                if (!hasPrev || !eq(selected, prev)) {
+                    hasPrev = true;
+                    prev = selected;
+                    fn(selected);
+                }
+            }
+            : fn;
+        subs.add(wrapper);
+        wrapper(stateCell.get()); // initial call
+        return () => subs.delete(wrapper);
+    }
+    /**
+     * @function watch
+     * Watches a specific value in the store and runs callback when it changes.
+     * Provides both new and old values.
+     *
+     * @param {Function} selector Function selecting what to watch
+     * @param {Function} callback Called with (newValue, oldValue)
+     * @param {Function} [equals] Optional equality function (defaults to Object.is)
+     *
+     * @example
+     * store.watch(s => s.count, (n, o) => console.log(`count: ${o} → ${n}`));
+     */
+    function watch(selector, callback, equals) {
+        watchers.push({ selector, cb: callback, equals });
+        return () => {
+            const i = watchers.findIndex(w => w.cb === callback);
+            if (i >= 0)
+                watchers.splice(i, 1);
+        };
+    }
+    /**
+     * @function use
+     * Adds middleware to run on every state change.
+     *
+     * Middleware is for logging, analytics, or side effects.
+     *
+     * @param {Function} middleware Function with (state, action?, payload?)
+     *
+     * @example
+     * store.use((s, action) => console.log(`[${action}]`, s));
+     */
+    function use(middleware) {
+        middlewares.push(middleware);
+        return () => {
+            const i = middlewares.indexOf(middleware);
+            if (i >= 0)
+                middlewares.splice(i, 1);
+        };
+    }
+    /**
+     * @function derive
+     * Creates a derived store that reacts to changes in selected parts of the state.
+     *
+     * @example
+     * const themeStore = store.derive(s => s.theme);
+     * themeStore.subscribe(v => console.log("theme:", v));
+     */
+    function derive(selector, equals) {
+        return {
+            subscribe(cb) {
+                return subscribe((v) => cb(v), selector, equals);
+            },
+        };
+    }
+    /** @function toJSON — Returns a deep copy of the current state for debugging */
+    function toJSON() {
+        return structuredClone(stateCell.get());
+    }
+    return {
+        get,
+        set,
+        update,
+        delete: deleteKeys,
+        clear,
+        subscribe,
+        watch,
+        use,
+        derive,
+        batch,
+        reset,
+        rehydrate,
+        toJSON,
+    };
+}
+// -------------------- Example Stores --------------------
+//
+// Commented out on purpose: a top-level `createStore(...)` is a side effect,
+// so shipping ready-made example stores here would force `store.ts` into every
+// client runtime bundle — the tree-shaker cannot drop a module whose top level
+// runs anything. `createStore` is imported on demand and stays tree-shaken.
+// Build your own with `createStore({ ... })`.
+// /**
+//  * This provides a basic store for your app like theme, user etc.
+//  * It's an example which you can delete;
+//  */
+// export const appStore = createStore(
+//   {
+//     user: { name: "Joe", location: "unknown", preferences: [] },
+//     count: 0,
+//     theme: "dark",
+//   },
+//   { persist: true, storageKey: "appStore" }
+// );
+// export const routeStore = createStore(
+//   { path: "/" },
+//   { persist: true, storageKey: "routeStore" }
+// );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesk/runtime",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "type": "module",
   "description": "Vesk runtime — reactivity, blocks, DOM operations, hydration",
   "main": "./dist/index-client.js",
@@ -22,6 +22,18 @@
       "types": "./dist/index-router.d.ts",
       "default": "./dist/index-router.js"
     },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "default": "./dist/store.js"
+    },
+    "./path-store": {
+      "types": "./dist/path-store.d.ts",
+      "default": "./dist/path-store.js"
+    },
+    "./store-persistence": {
+      "types": "./dist/store-persistence.d.ts",
+      "default": "./dist/store-persistence.js"
+    },
     "./src/*": "./dist/*.js",
     "./package.json": "./package.json"
   },
@@ -30,6 +42,15 @@
       "router": [
         "dist/index-router.d.ts"
       ],
+      "store": [
+        "dist/store.d.ts"
+      ],
+      "path-store": [
+        "dist/path-store.d.ts"
+      ],
+      "store-persistence": [
+        "dist/store-persistence.d.ts"
+      ],
       "client": [
         "dist/index-client.d.ts"
       ],
@@ -51,7 +72,7 @@
     }
   },
   "dependencies": {
-    "@vesk/compiler": "^0.2.59"
+    "@vesk/compiler": "^0.2.61"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",