edges-svelte 3.0.1 → 3.1.0

package/README.md

@@ -13,6 +13,15 @@ No context boilerplate. No hydration headaches.
 
 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.
 
+### Sync Scope & Limitations
+
+EdgeS does **not** aim to provide full server-to-client synchronization for all SvelteKit flows.
+
+- The main goal of this package is **server-side state isolation per request**.
+- Server-to-client sync is a convenience layer for common cases, not a strict consistency protocol.
+- `svelte actions` with redirects are **not fully synchronized** by design.
+- Redirect-driven flows (and similar edge cases) should be handled with explicit app-level patterns (for example cookies/session/flash state) when you need guaranteed transfer of action results across navigation.
+
 > Designed for **SvelteKit**.
 
 ---

package/dist/client/NavigationSync.svelte.js

@@ -1,4 +1,4 @@
-import { browser } from '../utils/environment.js';
+import { BROWSER } from '@azure-net/tools/environment';
 import { batch } from '../utils/batch.js';
 const stateUpdateCallbacks = new Map();
 const UNDEFINED_MARKER = '__EDGES_UNDEFINED__';
@@ -6,7 +6,8 @@ const NULL_MARKER = '__EDGES_NULL__';
 const BIGINT_MARKER = '__EDGES_BIGINT__';
 const EDGES_STATE_FIELD = '__edges_state__';
 const EDGES_REV_FIELD = '__edges_rev__';
-let lastAppliedRevision = 0;
+const SEEN_REVISIONS_LIMIT = 200;
+const seenRevisions = new Set();
 const decodeEdgesValue = (value) => {
     if (value && typeof value === 'object') {
         if (UNDEFINED_MARKER in value)
@@ -26,8 +27,23 @@ const decodeEdgesValue = (value) => {
     }
     return value;
 };
+const tryDecodeLegacyString = (value) => {
+    const trimmed = value.trim();
+    if (!(trimmed.startsWith('{') || trimmed.startsWith('['))) {
+        return value;
+    }
+    if (!trimmed.includes(UNDEFINED_MARKER) && !trimmed.includes(NULL_MARKER) && !trimmed.includes(BIGINT_MARKER)) {
+        return value;
+    }
+    try {
+        return decodeEdgesValue(JSON.parse(trimmed));
+    }
+    catch {
+        return value;
+    }
+};
 export function registerStateUpdate(key, callback) {
-    if (browser) {
+    if (BROWSER) {
         stateUpdateCallbacks.set(key, callback);
     }
 }
@@ -39,15 +55,7 @@ export function processEdgesState(edgesState) {
     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  */
-                }
-            }
+            const processedValue = typeof value === 'string' ? tryDecodeLegacyString(value) : decodeEdgesValue(value);
             store.set(key, processedValue);
             const callback = stateUpdateCallbacks.get(key);
             if (callback) {
@@ -63,15 +71,21 @@ export function applyEdgesFromPayload(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)
+    const revision = data[EDGES_REV_FIELD];
+    if (typeof revision === 'string' && revision.length > 0) {
+        if (seenRevisions.has(revision))
             return;
-        lastAppliedRevision = revision;
+        seenRevisions.add(revision);
+        if (seenRevisions.size > SEEN_REVISIONS_LIMIT) {
+            const oldestRevision = seenRevisions.values().next().value;
+            if (oldestRevision) {
+                seenRevisions.delete(oldestRevision);
+            }
+        }
     }
     processEdgesState(rawState);
 }
-if (browser) {
+if (BROWSER) {
     if (!window.__EDGES_NAVIGATION_SYNC_MOUNTED__) {
         window.__EDGES_NAVIGATION_SYNC_MOUNTED__ = true;
         void Promise.all([import('svelte'), import('./NavigationStateObserver.svelte')])

package/dist/context/Context.d.ts

@@ -9,7 +9,7 @@ export interface ContextData {
         providersAutoKeyCounters?: Map<string, number>;
         providersConstructionStack?: string[];
         edgesDirtyKeys?: Set<string>;
-        edgesRevision?: number;
+        edgesRevision?: string;
     } & App.ContextDataExtended;
 }
 declare class RequestContextManager {

package/dist/context/Context.js

@@ -1,11 +1,11 @@
-import { browser } from '../utils/environment.js';
+import { BROWSER } from '@azure-net/tools/environment';
 class RequestContextManager {
     _currentGetter;
     init(getter) {
         this._currentGetter = getter;
     }
     current() {
-        if (browser) {
+        if (BROWSER) {
             return { data: { message: 'Do not use request context on client side' } };
         }
         if (!this._currentGetter) {

package/dist/provider/Provider.js

@@ -1,8 +1,7 @@
 import { createState as BaseCreateState, createDerivedState as BaseCreateDerivedState, createRawState as BaseCreateRawState } from '../store/index.js';
+import { BROWSER, DEV } from '@azure-net/tools/environment';
 import { RequestContext } from '../context/index.js';
-import { browser } from '../utils/environment.js';
-import { DevTools } from '../utils/dev.js';
-import { dev } from '../utils/environment.js';
+import { recordProviderAccess, registerProviderDefinition, trackFactoryUniqueness, validateNamedProviderUniqueness } from './Utils.js';
 const globalClientCache = new Map();
 const globalConstructionStack = [];
 const PROVIDER_FACTORY_MARK = Symbol.for('edges-svelte.provider.factory');
@@ -17,7 +16,7 @@ class AutoKeyGenerator {
             cache = this.cache;
             counters = this.counters;
         };
-        if (browser) {
+        if (BROWSER) {
             setGlobalCacheSystem();
         }
         else {
@@ -45,7 +44,7 @@ class AutoKeyGenerator {
             counters.set(baseKey, 0);
         }
         cache.set(factory, finalKey);
-        DevTools.validateFactoryUniqueness(factory, finalKey);
+        trackFactoryUniqueness(factory, finalKey);
         return finalKey;
     }
     static hash(str) {
@@ -58,7 +57,7 @@ class AutoKeyGenerator {
     }
 }
 export const clearCache = (pattern) => {
-    if (browser) {
+    if (BROWSER) {
         if (pattern) {
             for (const [key] of globalClientCache) {
                 if (key.includes(pattern)) {
@@ -73,7 +72,7 @@ export const clearCache = (pattern) => {
 };
 const createUiProvider = (cacheKey, factory, dependencies, inject) => {
     const readConstructionStack = () => {
-        if (browser)
+        if (BROWSER)
             return globalConstructionStack;
         try {
             const context = RequestContext.current();
@@ -89,7 +88,7 @@ const createUiProvider = (cacheKey, factory, dependencies, inject) => {
         return `[edges-svelte] Circular provider dependency detected while constructing "${key}". Chain: ${chain.join(' -> ')}.`;
     };
     const validateLazyInjection = (ownerKey, injections) => {
-        if (!dev || !injections)
+        if (!DEV || !injections)
             return;
         for (const [depKey, depValue] of Object.entries(injections)) {
             if (depValue && typeof depValue === 'object') {
@@ -119,7 +118,7 @@ const createUiProvider = (cacheKey, factory, dependencies, inject) => {
     };
     const provider = (() => {
         let contextMap;
-        if (browser) {
+        if (BROWSER) {
             contextMap = globalClientCache;
         }
         else {
@@ -137,6 +136,7 @@ const createUiProvider = (cacheKey, factory, dependencies, inject) => {
         if (contextMap.has(cacheKey)) {
             const cached = contextMap.get(cacheKey);
             if (cached !== undefined) {
+                recordProviderAccess(cacheKey, cached, BROWSER ? contextMap.size : undefined);
                 return cached;
             }
         }
@@ -161,6 +161,7 @@ const createUiProvider = (cacheKey, factory, dependencies, inject) => {
         }
         markProviderInstance(instance);
         contextMap.set(cacheKey, instance);
+        recordProviderAccess(cacheKey, instance, BROWSER ? contextMap.size : undefined);
         return instance;
     });
     try {
@@ -181,7 +182,11 @@ export function createStore(nameOrFactory, factoryOrInject, inject) {
     const name = isNameProvided ? nameOrFactory : undefined;
     const factory = isNameProvided ? factoryOrInject : nameOrFactory;
     const injections = isNameProvided ? inject : factoryOrInject;
+    if (isNameProvided) {
+        validateNamedProviderUniqueness(name, 'store', factory);
+    }
     const cacheKey = name || AutoKeyGenerator.generate(factory);
+    registerProviderDefinition(cacheKey, 'store', factory, Boolean(name));
     return createUiProvider(cacheKey, factory, (key) => {
         let stateCounter = 0;
         return {
@@ -215,7 +220,11 @@ export function createPresenter(nameOrFactory, factoryOrInject, inject) {
     const name = isNameProvided ? nameOrFactory : undefined;
     const factory = isNameProvided ? factoryOrInject : nameOrFactory;
     const injections = isNameProvided ? inject : factoryOrInject;
+    if (isNameProvided) {
+        validateNamedProviderUniqueness(name, 'presenter', factory);
+    }
     const cacheKey = name || AutoKeyGenerator.generate(factory);
+    registerProviderDefinition(cacheKey, 'presenter', factory, Boolean(name));
     return createUiProvider(cacheKey, factory, {}, injections);
 }
 export const createPresenterFactory = (inject) => {

package/dist/provider/Utils.d.ts

@@ -0,0 +1,34 @@
+import type { UnknownFunc } from '../types.js';
+export type ProviderKind = 'store' | 'presenter';
+export interface ProviderDevDefinitionSnapshot {
+    key: string;
+    kind: ProviderKind;
+    factoryName: string;
+    named: boolean;
+    registeredAt: number;
+}
+export interface ProviderDevRuntimeSnapshot {
+    key: string;
+    instantiated: boolean;
+    hits: number;
+    lastAccessedAt: number | null;
+    instanceSizeBytes: number;
+}
+export interface ProviderDevSnapshot {
+    definitions: ProviderDevDefinitionSnapshot[];
+    runtimes: ProviderDevRuntimeSnapshot[];
+    providerCacheEntries: number;
+    providerCacheSizeBytes: number;
+}
+export interface ProviderDuplicateAttempt {
+    key: string;
+    attemptedKind: ProviderKind;
+    existingKind: ProviderKind;
+    at: number;
+}
+export declare const trackFactoryUniqueness: (factory: UnknownFunc, key: string) => void;
+export declare const validateNamedProviderUniqueness: (key: string, kind: ProviderKind, factory: UnknownFunc) => void;
+export declare const registerProviderDefinition: (key: string, kind: ProviderKind, factory: UnknownFunc, named: boolean) => void;
+export declare const recordProviderAccess: (key: string, instance: unknown, cacheEntriesHint?: number) => void;
+export declare const getProviderDevSnapshot: () => ProviderDevSnapshot;
+export declare const getProviderDuplicateAttempts: () => ProviderDuplicateAttempt[];

package/dist/provider/Utils.js

@@ -0,0 +1,102 @@
+import { BROWSER, DEV } from '@azure-net/tools/environment';
+const seenFactories = new WeakSet();
+const namedProviderRegistry = new Map();
+const duplicateNamedProviderEvents = [];
+const providerDefinitions = new Map();
+const providerRuntime = new Map();
+let providerCacheEntries = 0;
+let providerCacheSizeBytes = 0;
+const safeJsonLength = (value) => {
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized ? serialized.length : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+const estimateSize = (value) => {
+    if (typeof value === 'bigint')
+        return value.toString().length;
+    if (typeof value === 'function' || typeof value === 'symbol')
+        return 0;
+    if (typeof value === 'string')
+        return value.length;
+    if (value === undefined || value === null)
+        return 0;
+    return safeJsonLength(value);
+};
+export const trackFactoryUniqueness = (factory, key) => {
+    if (!DEV)
+        return;
+    if (seenFactories.has(factory)) {
+        console.warn(`[edges-svelte] Factory collision detected for key "${key}". ` +
+            `This might cause unexpected behavior.` +
+            `Set a unique __storeKey__ property on your factory function.`);
+    }
+    seenFactories.add(factory);
+};
+export const validateNamedProviderUniqueness = (key, kind, factory) => {
+    if (!DEV)
+        return;
+    const existing = namedProviderRegistry.get(key);
+    if (!existing) {
+        namedProviderRegistry.set(key, { kind, factory });
+        return;
+    }
+    if (existing.factory === factory && existing.kind === kind) {
+        return;
+    }
+    duplicateNamedProviderEvents.push({
+        key,
+        attemptedKind: kind,
+        existingKind: existing.kind,
+        at: Date.now()
+    });
+    throw new Error(`[edges-svelte] Duplicate ${kind} key "${key}" detected. ` +
+        `This key is already used by a ${existing.kind}. Use unique names for createStore/createPresenter.`);
+};
+export const registerProviderDefinition = (key, kind, factory, named) => {
+    if (!DEV || !BROWSER)
+        return;
+    if (providerDefinitions.has(key))
+        return;
+    providerDefinitions.set(key, {
+        key,
+        kind,
+        factoryName: factory.displayName || factory.name || '(anonymous)',
+        named,
+        registeredAt: Date.now()
+    });
+};
+export const recordProviderAccess = (key, instance, cacheEntriesHint) => {
+    if (!DEV || !BROWSER)
+        return;
+    const runtime = providerRuntime.get(key) ?? {
+        key,
+        instantiated: false,
+        hits: 0,
+        lastAccessedAt: null,
+        instanceSizeBytes: 0
+    };
+    runtime.instantiated = true;
+    runtime.hits += 1;
+    runtime.lastAccessedAt = Date.now();
+    runtime.instanceSizeBytes = estimateSize(instance);
+    providerRuntime.set(key, runtime);
+    if (typeof cacheEntriesHint === 'number') {
+        providerCacheEntries = cacheEntriesHint;
+    }
+    providerCacheSizeBytes = 0;
+    for (const [providerKey, tracked] of providerRuntime) {
+        providerCacheSizeBytes += providerKey.length;
+        providerCacheSizeBytes += tracked.instanceSizeBytes;
+    }
+};
+export const getProviderDevSnapshot = () => ({
+    definitions: Array.from(providerDefinitions.values()),
+    runtimes: Array.from(providerRuntime.values()),
+    providerCacheEntries,
+    providerCacheSizeBytes
+});
+export const getProviderDuplicateAttempts = () => [...duplicateNamedProviderEvents];

package/dist/server/EdgesHandle.js

@@ -1,14 +1,14 @@
 import { stateSerialize } from '../store/State.svelte.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import { RequestContext } from '../context/Context.js';
 const storage = new AsyncLocalStorage();
-let requestRevision = 0;
 export const edgesHandle = async (event, callback, silentChromeDevtools = false) => {
     const requestSymbol = Symbol('request');
     return await storage.run({
         event: event,
         symbol: requestSymbol,
-        data: { providers: new Map(), edgesDirtyKeys: new Set(), edgesRevision: ++requestRevision }
+        data: { providers: new Map(), edgesDirtyKeys: new Set(), edgesRevision: randomUUID() }
     }, async () => {
         RequestContext.init(() => {
             const context = storage.getStore();
@@ -33,6 +33,8 @@ export const edgesHandle = async (event, callback, silentChromeDevtools = false)
             serialize: (html) => {
                 if (!html)
                     return html ?? '';
+                if (!html.includes('</body>'))
+                    return html;
                 const serialized = stateSerialize();
                 if (!serialized)
                     return html;

package/dist/server/ServerSync.js

@@ -1,6 +1,6 @@
 import { getStateMap } from '../store/State.svelte.js';
 import { RequestContext } from '../context/Context.js';
-import { build, dev } from '../utils/environment.js';
+import { DEV } from '@azure-net/tools/environment';
 const UNDEFINED_MARKER = '__EDGES_UNDEFINED__';
 const NULL_MARKER = '__EDGES_NULL__';
 const BIGINT_MARKER = '__EDGES_BIGINT__';
@@ -9,7 +9,6 @@ const EDGES_REV_FIELD = '__edges_rev__';
 const isObjectRecord = (value) => {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 };
-const PROFILE_EDGES_DELTA = dev && !build;
 const encodeEdgesValue = (value) => {
     if (value === undefined)
         return { [UNDEFINED_MARKER]: true };
@@ -30,11 +29,11 @@ const encodeEdgesValue = (value) => {
     return value;
 };
 const getEdgesDelta = () => {
-    const startedAt = PROFILE_EDGES_DELTA ? performance.now() : 0;
+    const startedAt = DEV ? performance.now() : 0;
     try {
         const context = RequestContext.current();
         const dirtyKeys = context.data.edgesDirtyKeys;
-        const rev = context.data.edgesRevision ?? 0;
+        const rev = context.data.edgesRevision;
         const stateMap = getStateMap();
         if (!dirtyKeys || dirtyKeys.size === 0 || !stateMap || stateMap.size === 0)
             return undefined;
@@ -44,7 +43,7 @@ const getEdgesDelta = () => {
                 continue;
             state[key] = encodeEdgesValue(stateMap.get(key));
         }
-        if (Object.keys(state).length === 0)
+        if (!rev || Object.keys(state).length === 0)
             return undefined;
         return { state, rev };
     }
@@ -52,7 +51,7 @@ const getEdgesDelta = () => {
         return undefined;
     }
     finally {
-        if (PROFILE_EDGES_DELTA) {
+        if (DEV) {
             const duration = performance.now() - startedAt;
             if (duration > 4) {
                 console.debug(`[edges-svelte] edges delta encode took ${duration.toFixed(2)}ms`);

package/dist/store/State.svelte.d.ts

@@ -2,7 +2,7 @@ import { type Readable, type Writable } from 'svelte/store';
 declare global {
     interface Window {
         __SAFE_SSR_STATE__?: Map<string, unknown>;
-        __EDGES_DEVTOOLS__: Record<string, unknown>;
+        __EDGES_DEVTOOLS__?: Record<string, unknown>;
     }
 }
 export declare const stateSerialize: () => string;

package/dist/store/State.svelte.js

@@ -1,5 +1,5 @@
 import { RequestContext } from '../context/Context.js';
-import { browser } from '../utils/environment.js';
+import { BROWSER } from '@azure-net/tools/environment';
 import { derived, writable } from 'svelte/store';
 import { registerStateUpdate } from '../client/NavigationSync.svelte.js';
 import { queueUpdate, isBatching } from '../utils/batch.js';
@@ -56,7 +56,7 @@ const getRequestContext = () => {
     }
 };
 const markStateDirty = (key) => {
-    if (browser)
+    if (BROWSER)
         return;
     try {
         const context = RequestContext.current();
@@ -85,7 +85,7 @@ const getBrowserState = (key, initial) => {
     return initial;
 };
 export const createRawState = (key, initial) => {
-    if (browser) {
+    if (BROWSER) {
         let state = $state(getBrowserState(key, initial()));
         const updateWindowState = (val) => {
             if (!window.__SAFE_SSR_STATE__) {
@@ -138,7 +138,7 @@ export const createRawState = (key, initial) => {
     };
 };
 export const createState = (key, initial) => {
-    if (browser) {
+    if (BROWSER) {
         const initialValue = getBrowserState(key, initial());
         const state = writable(initialValue);
         let currentValue = initialValue;
@@ -222,7 +222,7 @@ export const createState = (key, initial) => {
     };
 };
 export const createDerivedState = (stores, deriveFn) => {
-    if (browser) {
+    if (BROWSER) {
         return derived(stores, deriveFn);
     }
     return {