@vesk/runtime 0.2.59 → 0.2.60

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.60",
   "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.60"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",