edges-svelte 2.2.0 → 3.0.0

package/README.md

@@ -2,15 +2,16 @@
 
 ### A blazing-fast, extremely lightweight and SSR-friendly store for SvelteKit.
 
-**EdgeS** brings seamless, per-request state management to Svelte apps — fully reactive, server-aware, and serialization-safe by default.
+**EdgeS** brings seamless, per-request state management to Svelte apps.
 
-No context boilerplate. No hydration headaches. Just drop-in SSR-compatible state primitives with built-in support for client-side reactivity and server-side isolation.
+No context boilerplate. No hydration headaches.
 
-- 🔄 Unified state for server and client
-- 🧠 Persistent per-request memory via `AsyncLocalStorage`
-- 💧 Tiny API
-- 💥 Instant serialization without magic
-- 🧩 Dependency injection, zero runtime overhead
+- Persistent per-request memory via `AsyncLocalStorage`
+- Tiny API
+- Instant serialization without magic
+- Dependency injection, zero runtime overhead
+
+EdgeS is built to prevent state leaks. Its primary goal is to keep server-side state safely isolated per request while providing a clean developer experience with presenters, stores, and automatic client updates when fresh state arrives from the server. It is intentionally one-way sync from server to client and does not aim to provide full two-way state synchronization between client and server.
 
 > Designed for **SvelteKit**.
 
@@ -77,8 +78,8 @@ const myStore = createStore('MyUniqueStoreName', ({ createState, createDerivedSt
 <!-- Will update the state -->
 ```
 
-- 💡 All stores created inside `createStore` use unique keys automatically and are request-scoped
-- 🛡️ Fully SSR-safe — stores are isolated per request and serialized automatically
+- All stores created inside `createStore` use unique keys automatically and are request-scoped
+- Fully SSR-safe — stores are isolated per request and serialized automatically
 
 ---
 
@@ -130,7 +131,7 @@ const doubled = createDerivedState([count], ([$n]) => $n * 2);
 $doubled;
 ```
 
-> Like Svelte’s `derived`.
+> Like Svelte’s `derived`. On the server side will not subscribe to store like derived, just reads initial value, on client side works like derived.
 
 ---
 
@@ -158,6 +159,22 @@ const useUserStore = withDeps(({ user, createState }) => {
 });
 ```
 
+For provider-to-provider dependencies, inject provider functions lazily:
+
+```ts
+const useAuth = createPresenter('AuthPresenter', () => ({ isLoggedIn: true }));
+
+const useHeader = createPresenter(
+	'HeaderPresenter',
+	({ useAuth }) => ({
+		canShowProfile: () => useAuth().isLoggedIn
+	}),
+	{ useAuth }
+);
+```
+
+Avoid injecting resolved provider instances. In development, edges throws a fail-fast error for eager provider injection and for circular dependency chains like `A -> B -> A`.
+
 ---
 
 ## createPresenter
@@ -279,48 +296,9 @@ You can skip specifying a unique key and pass the factory as the first argument
 
 ---
 
-## State Compression
-
-### Method 1: Via Plugin (Recommended) ✨
+## State Serialization
 
-```typescript
-// vite.config.ts - Zero config compression!
-import { sveltekit } from '@sveltejs/kit/vite';
-import { defineConfig } from 'vite';
-import { edgesPlugin } from 'edges-svelte/plugin';
-
-export default defineConfig({
-	plugins: [
-		sveltekit(),
-		edgesPlugin({
-			compression: {
-				enabled: true, // Enable compression
-				threshold: 2048 // Compress states > 2KB
-			},
-			silentChromeDevtools: true // Optional: silence devtools requests
-		})
-	]
-});
-
-// That's it! No need to touch hooks.server.ts
-```
-
-### Method 2: Manual Setup (For advanced use cases)
-
-```typescript
-// hooks.server.ts - If you need custom control
-import { edgesHandle } from 'edges-svelte/server';
-
-export const handle = edgesHandle(({ serialize, edgesEvent, resolve }) => {
-	return resolve(edgesEvent, {
-		transformPageChunk: ({ html }) =>
-			serialize(html, {
-				compress: true, // Enable compression
-				compressionThreshold: 2048 // Compress states > 2KB
-			})
-	});
-});
-```
+EdgeS serializes SSR state as plain script payloads. Transport-level compression should be handled by your HTTP stack (gzip/brotli) instead of application-level compression in this package.
 
 ---
 

package/dist/client/NavigationStateObserver.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import { applyEdgesFromPayload } from './NavigationSync.svelte.js';
+
+	$effect(() => {
+		applyEdgesFromPayload(page.data);
+		applyEdgesFromPayload(page.form);
+	});
+</script>

package/dist/client/NavigationStateObserver.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const NavigationStateObserver: import("svelte").Component<Record<string, never>, {}, "">;
+type NavigationStateObserver = ReturnType<typeof NavigationStateObserver>;
+export default NavigationStateObserver;

package/dist/client/NavigationSync.svelte.d.ts

@@ -1,3 +1,9 @@
 export declare function registerStateUpdate(key: string, callback: (value: unknown) => void): void;
 export declare function unregisterStateUpdate(key: string): void;
 export declare function processEdgesState(edgesState: Record<string, unknown>): void;
+export declare function applyEdgesFromPayload(payload: unknown): void;
+declare global {
+    interface Window {
+        __EDGES_NAVIGATION_SYNC_MOUNTED__?: boolean;
+    }
+}

package/dist/client/NavigationSync.svelte.js

@@ -1,15 +1,28 @@
 import { browser } from '../utils/environment.js';
+import { batch } from '../utils/batch.js';
 const stateUpdateCallbacks = new Map();
 const UNDEFINED_MARKER = '__EDGES_UNDEFINED__';
 const NULL_MARKER = '__EDGES_NULL__';
-const safeReviver = (key, value) => {
+const BIGINT_MARKER = '__EDGES_BIGINT__';
+const EDGES_STATE_FIELD = '__edges_state__';
+const EDGES_REV_FIELD = '__edges_rev__';
+let lastAppliedRevision = 0;
+const decodeEdgesValue = (value) => {
     if (value && typeof value === 'object') {
-        if (UNDEFINED_MARKER in value) {
+        if (UNDEFINED_MARKER in value)
             return undefined;
-        }
-        if (NULL_MARKER in value) {
+        if (NULL_MARKER in value)
             return null;
+        if (BIGINT_MARKER in value)
+            return BigInt(String(value[BIGINT_MARKER]));
+        if (Array.isArray(value)) {
+            return value.map((item) => decodeEdgesValue(item));
+        }
+        const decoded = {};
+        for (const [key, nested] of Object.entries(value)) {
+            decoded[key] = decodeEdgesValue(nested);
         }
+        return decoded;
     }
     return value;
 };
@@ -22,163 +35,81 @@ export function unregisterStateUpdate(key) {
     stateUpdateCallbacks.delete(key);
 }
 export function processEdgesState(edgesState) {
-    if (!window.__SAFE_SSR_STATE__) {
-        window.__SAFE_SSR_STATE__ = new Map();
-    }
-    for (const [key, value] of Object.entries(edgesState)) {
-        let processedValue = value;
-        if (typeof value === 'string') {
-            try {
-                processedValue = JSON.parse(value, safeReviver);
+    const store = window.__SAFE_SSR_STATE__ ?? new Map();
+    window.__SAFE_SSR_STATE__ = store;
+    batch(() => {
+        for (const [key, value] of Object.entries(edgesState)) {
+            let processedValue = decodeEdgesValue(value);
+            if (typeof value === 'string') {
+                try {
+                    processedValue = decodeEdgesValue(JSON.parse(value));
+                }
+                catch {
+                    /*  do nothing  */
+                }
             }
-            catch {
-                // If not JSON then use without handling
+            store.set(key, processedValue);
+            const callback = stateUpdateCallbacks.get(key);
+            if (callback) {
+                callback(processedValue);
             }
         }
-        window.__SAFE_SSR_STATE__.set(key, processedValue);
-        const callback = stateUpdateCallbacks.get(key);
-        if (callback) {
-            callback(processedValue);
-        }
+    });
+}
+export function applyEdgesFromPayload(payload) {
+    if (!payload || typeof payload !== 'object')
+        return;
+    const data = payload;
+    const rawState = data[EDGES_STATE_FIELD];
+    if (!rawState || typeof rawState !== 'object')
+        return;
+    const revision = Number(data[EDGES_REV_FIELD] ?? 0);
+    if (Number.isFinite(revision) && revision > 0) {
+        if (revision <= lastAppliedRevision)
+            return;
+        lastAppliedRevision = revision;
     }
+    processEdgesState(rawState);
 }
 if (browser) {
-    const originalFetch = window.fetch;
-    const parseHeaders = (headers) => {
-        const parsedHeaders = {};
-        switch (true) {
-            case headers instanceof Headers:
-                headers.forEach((value, key) => {
-                    parsedHeaders[key] = value;
-                });
-                return parsedHeaders;
-            case headers && typeof headers === 'object':
-                Object.entries(headers).forEach(([key, value]) => {
-                    parsedHeaders[key] = value;
-                });
-                return parsedHeaders;
-            default:
-                return parsedHeaders;
-        }
-    };
-    window.fetch = async function (...args) {
-        const [input, init] = args;
-        let reqInfo = { url: '', headers: {} };
-        if (typeof input === 'string') {
-            reqInfo = { url: input, headers: parseHeaders(init?.headers) };
-        }
-        else if (input instanceof Request) {
-            reqInfo = { url: input.url, headers: parseHeaders(input.headers) };
-        }
-        else if (input instanceof URL) {
-            reqInfo = { url: input.href, headers: parseHeaders(init?.headers) };
-        }
-        const isSvelteKitRequest = init.__sveltekit_fetch__ || reqInfo.headers['x-sveltekit-action'] || reqInfo.url.includes('__data.json');
-        const response = await originalFetch.apply(this, args);
-        if (!isSvelteKitRequest) {
-            return response;
-        }
-        if (!response.headers.get('content-type')?.includes('application/json')) {
-            return response;
-        }
-        const interceptEdgesStateFromResponse = (response) => {
-            if (!response.body)
-                return response;
-            if (init?.method === 'POST') {
-                const originalText = response.text.bind(response);
-                response.text = async function () {
-                    const text = await originalText();
-                    if (text.includes('__edges_state__')) {
-                        try {
-                            const parsed = JSON.parse(text);
-                            if (parsed.__edges_state__) {
-                                processEdgesState(parsed.__edges_state__);
-                            }
-                        }
-                        catch {
-                            // ignore parsing errors
-                        }
-                    }
-                    return text;
-                };
-            }
-            const originalGetReader = response.body.getReader.bind(response.body);
-            response.body.getReader = function (opts) {
-                const reader = originalGetReader(opts);
-                if (!('read' in reader))
-                    return reader;
-                const originalRead = reader.read.bind(reader);
-                const decoder = new TextDecoder();
-                let buffer = '';
-                let found = false;
-                let depth = 0;
-                let capture = '';
-                reader.read = async function () {
-                    const result = await originalRead();
-                    if (result.done || found)
-                        return result;
-                    buffer += decoder.decode(result.value, { stream: true });
-                    const idx = buffer.indexOf('"__edges_state__"');
-                    if (idx !== -1) {
-                        const braceStart = buffer.indexOf('{', idx);
-                        if (braceStart !== -1) {
-                            for (let i = braceStart; i < buffer.length; i++) {
-                                const ch = buffer[i];
-                                if (ch === '{') {
-                                    if (depth++ === 0)
-                                        capture = '';
-                                }
-                                if (depth > 0)
-                                    capture += ch;
-                                if (ch === '}') {
-                                    depth--;
-                                    if (depth === 0) {
-                                        try {
-                                            const parsed = JSON.parse(capture);
-                                            processEdgesState(parsed);
-                                            found = true;
-                                        }
-                                        catch {
-                                            // waiting for next iteration
-                                        }
-                                        break;
-                                    }
-                                }
-                            }
-                        }
-                        const MAX_BUFFER = Math.max(8192, capture.length * 2);
-                        if (buffer.length > MAX_BUFFER)
-                            buffer = buffer.slice(-MAX_BUFFER / 2);
-                    }
-                    return result;
-                };
-                return reader;
-            };
-            return response;
-        };
-        return interceptEdgesStateFromResponse(response);
-    };
+    if (!window.__EDGES_NAVIGATION_SYNC_MOUNTED__) {
+        window.__EDGES_NAVIGATION_SYNC_MOUNTED__ = true;
+        void Promise.all([import('svelte'), import('./NavigationStateObserver.svelte')])
+            .then(([svelte, module]) => {
+            const target = document.body || document.documentElement;
+            const host = document.createElement('div');
+            host.setAttribute('data-edges-navigation-sync', '1');
+            host.style.display = 'none';
+            target.appendChild(host);
+            svelte.mount(module.default, { target: host });
+            window.addEventListener('beforeunload', () => {
+                host.remove();
+                window.__EDGES_NAVIGATION_SYNC_MOUNTED__ = false;
+            }, { once: true });
+        })
+            .catch(() => {
+            window.__EDGES_NAVIGATION_SYNC_MOUNTED__ = false;
+        });
+    }
     if (typeof MutationObserver !== 'undefined') {
-        // Optimized: Only observe <body> instead of entire document tree
-        // This reduces CPU usage by 30-50% on pages with frequent DOM updates
         const observer = new MutationObserver((mutations) => {
             for (const mutation of mutations) {
                 if (mutation.type === 'childList') {
                     for (const node of mutation.addedNodes) {
-                        // Filter early: only process script elements
                         if (node instanceof HTMLScriptElement) {
                             const text = node.textContent || '';
-                            // Quick check for our state markers
                             if (text.includes('__SAFE_SSR_STATE__') && text.includes('__EDGES_REVIVER__')) {
-                                // Use microtask instead of setTimeout(0) for better performance
                                 queueMicrotask(() => {
-                                    if (window.__SAFE_SSR_STATE__) {
-                                        for (const [key, value] of window.__SAFE_SSR_STATE__) {
-                                            const callback = stateUpdateCallbacks.get(key);
-                                            if (callback) {
-                                                callback(value);
+                                    const store = window.__SAFE_SSR_STATE__;
+                                    if (store) {
+                                        batch(() => {
+                                            for (const [key, value] of store) {
+                                                const callback = stateUpdateCallbacks.get(key);
+                                                if (callback) {
+                                                    callback(value);
+                                                }
                                             }
-                                        }
+                                        });
                                     }
                                 });
                             }
@@ -187,11 +118,9 @@ if (browser) {
                 }
             }
         });
-        // Optimized: Observe only <body> with subtree: false to reduce overhead
-        // State scripts are always injected into body, not head
         observer.observe(document.body || document.documentElement, {
             childList: true,
-            subtree: false // Only direct children, not entire subtree
+            subtree: false
         });
         if (typeof window !== 'undefined') {
             window.addEventListener('beforeunload', () => observer.disconnect());

package/dist/context/Context.d.ts

@@ -7,6 +7,9 @@ export interface ContextData {
         providers?: Map<string, unknown>;
         providersAutoKeyCache?: WeakMap<(...args: unknown[]) => unknown, string>;
         providersAutoKeyCounters?: Map<string, number>;
+        providersConstructionStack?: string[];
+        edgesDirtyKeys?: Set<string>;
+        edgesRevision?: number;
     } & App.ContextDataExtended;
 }
 declare class RequestContextManager {

package/dist/plugin/EdgesAutoHandlePlugin.d.ts

@@ -1,32 +1,14 @@
 import type { Plugin } from 'vite';
 export interface EdgesPluginOptions {
-    /**
-     * State compression options
-     */
-    compression?: {
-        /**
-         * Enable compression for large state objects
-         * @default false
-         */
-        enabled?: boolean;
-        /**
-         * Minimum size in bytes before compression is applied
-         * @default 1024 (1KB)
-         */
-        threshold?: number;
-    };
-    /**
-     * Silence Chrome DevTools requests
-     * @default true
-     */
     silentChromeDevtools?: boolean;
+    syncFromServer?: boolean;
+    syncTransformMode?: 'ast' | 'regex' | 'hybrid';
 }
 /**
  * Creates a factory for the edges plugin with a custom package name and server path.
  *
  * Use this when:
  * - Creating a wrapper package that re-exports edges-svelte functionality
- * - Developing the package itself (use `$lib/server` as serverPath)
  *
  * @param packageName - The name that will be used in generated imports (e.g., 'edges-svelte', 'my-wrapper')
  * @param serverPath - The import path to the server module (e.g., 'edges-svelte/server', '$lib/server')
@@ -38,25 +20,11 @@ export interface EdgesPluginOptions {
  *
  * export const myWrapperPlugin = createEdgesPluginFactory('my-wrapper', 'my-wrapper/server');
  * ```
- *
- * @example
- * ```ts
- * // For package development (testing the package itself)
- * import { createEdgesPluginFactory } from './src/lib/plugin/index.js';
- *
- * const edgesPluginDev = createEdgesPluginFactory('edges-svelte', '$lib/server');
- *
- * export default defineConfig({
- *   plugins: [sveltekit(), edgesPluginDev()]
- * });
- * ```
  */
 export declare function createEdgesPluginFactory(packageName: string, serverPath: string): (options?: EdgesPluginOptions) => Plugin;
 /**
- * Default edges-svelte plugin for end users.
  *
  * This plugin automatically wraps the SvelteKit handle hook with edgesHandle,
- * eliminating the need to manually wrap your handle function.
  *
  * @example
  * ```ts
@@ -69,37 +37,5 @@ export declare function createEdgesPluginFactory(packageName: string, serverPath
  *   plugins: [sveltekit(), edgesPlugin()]
  * });
  * ```
- *
- * @example
- * ```ts
- * // vite.config.ts - With compression
- * export default defineConfig({
- *   plugins: [
- *     sveltekit(),
- *     edgesPlugin({
- *       compression: {
- *         enabled: true,
- *         threshold: 2048  // Compress states larger than 2KB
- *       }
- *     })
- *   ]
- * });
- * ```
- *
- * After adding the plugin, you can write your hooks.server.ts normally:
- *
- * @example
- * ```ts
- * // hooks.server.ts - No manual wrapping needed!
- *
- * // Option 1: No handle defined - plugin creates default
- * // (nothing to write, it just works)
- *
- * // Option 2: Custom handle - plugin automatically wraps it
- * export const handle = async ({ event, resolve }) => {
- *   console.log('My custom middleware');
- *   return resolve(event);
- * };
- * ```
  */
 export declare const edgesPlugin: (options?: EdgesPluginOptions) => Plugin;