edges-svelte 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pixel1917
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# Edge-S
+
+### A blazing-fast, extremely lightweight and SSR-friendly store for Svelte.
+
+**Edge-S** brings seamless, per-request state management to Svelte apps — fully reactive, server-aware, and serialization-safe by default.
+
+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.
+
+- 🔄 Unified state for server and client
+- 🧠 Persistent per-request memory via `AsyncLocalStorage`
+- 💧 Tiny API — no subscriptions needed unless you want them
+- 💥 Instant serialization without magic
+- 🧩 Provider-based dependency injection, zero runtime overhead
+
+> Designed for **SvelteKit**.
+
+---
+
+## Installation
+
+```bash
+npm install edges-svelte
+```
+
+---
+
+## Setup
+
+To enable **Edge-S**, wrap your SvelteKit `handle` hook and serialize the state in `transformPageChunks`:
+
+```ts
+// hooks.server.ts
+import { edgesHandle } from 'edges-svelte/server';
+
+export const handle: Handle = async ({ event, resolve }) => {
+	return edgesHandle(
+		event,
+		({ serialize, edgesEvent }) => {
+			//...Your handle code, use edgesEvent as a default svelte event (RequestEvent)
+			return resolve(edgesEvent, { transformPageChunk: ({ html }) => serialize(html) });
+		},
+		true
+	);
+};
+```
+
+---
+
+## Basic usage
+
+### `createProvider` - creates store with access to `createState` and `createDerivedState`
+
+```ts
+import { createProvider } from 'edges-svelte';
+
+const myProvider = createProvider({
+	factory: ({ createState, createDerivedState }) => {
+		// Works just like writable
+		const collection = createState<number[]>('unique-key', () => []);
+		// Works just like derived
+		const collectionLengthDoubled = createDerivedState([collection], ([$c]) => $c.length * 2);
+		// Advanced derived
+		const collectionLengthMultiplied = createDerivedState([collection], ([$c]) => (count: number) => {
+			return $c.length * count;
+		});
+
+		const updateAction = (num: number) => {
+			collection.update((n) => {
+				n = [...n, num];
+				return n;
+			});
+		};
+
+		// ...Your code;
+
+		return { collection, collectionLengthDoubled, collectionLengthMultiplied, updateAction };
+	}
+});
+```
+
+```sveltehtml
+<script lang="ts">
+  import {myProvider} from 'your-alias';
+
+  const {collection, collectionLengthDoubled, collectionLengthMultiplied, updateAction} = myProvider();
+</script>
+
+{$collection.join(', ')} <!-- Empty string before button click, 25 after button click -->
+{$collectionLengthDoubled} <!-- 0 before button click, 2 after button click -->
+{$collectionLengthMultiplied(5)}  <!-- 0 before button click, 5 after button click -->
+<button onclick={() => updateAction(25)}></button>  <!-- Will update the state -->
+```
+
+- 💡 You get access to `createRawState`, `createState`, and `createDerivedState` in providers created by `createProvider`
+- 🛡️ Fully SSR-safe — all internal state is per-request
+
+---
+
+## Core Concepts
+
+### SSR-safe state access
+
+All state is isolated per request and never shared between users thanks to `AsyncLocalStorage`. Access to state primitives (`createRawState`, `createState`, `createDerivedState`) is only possible through provider functions — ensuring that you never accidentally share state across requests.
+
+---
+
+## State Primitives
+
+### `createState`
+
+```ts
+const count = createState('count', () => 0);
+
+$count;
+// in template: {$count}
+
+count.update((n) => n + 1);
+```
+
+> This behaves like native Svelte `writable`, but scoped to request. Fully SSR-safe.
+
+---
+
+### `createDerivedStore`
+
+```ts
+const count = createState('count', () => 1);
+const doubled = createDerivedState([count], ([$n]) => $n * 2);
+
+$doubled;
+```
+
+> Works just like Svelte’s `derived`, but fully SSR-compatible. On the server, computes once and reuses the value.
+
+---
+
+### `createRawState`
+
+```ts
+const counter = createRawState('counter', () => 0);
+counter.value += 1;
+```
+
+> Lightweight, reactive, SSR-safe variable. No subscriptions. Access through `.value`.
+
+- ✅ Fully server-aware
+- ✅ Serialization-safe
+- ✅ Sync updates
+
+---
+
+## Dependency Injection
+
+### `createProviderFactory`
+
+For shared injected dependencies:
+
+```ts
+const withDeps = createProviderFactory({ user: getUserFromSession });
+
+const useUserStore = withDeps({
+	factory: ({ user, createState }) => {
+		const userState = createState('user', () => user);
+		return { userState };
+	}
+});
+```
+
+---
+
+## Imports
+
+| Feature                                   | Import from           |
+| ----------------------------------------- | --------------------- |
+| `createProvider`, `createProviderFactory` | `edges-svelte`        |
+| `edgesHandle`                             | `edges-svelte/server` |
+
+---
+
+## Best Practices
+
+- Use unique keys for each state to avoid collisions
+- Always create your states via providers to avoid shared memory across requests
+- Prefer `createProvider` even for simple state logic — it scales better and stays testable
+
+---
+
+## About edgesHandle
+
+```ts
+/**
+ * Wraps request handling in an AsyncLocalStorage context and provides a `serialize` function
+ * for injecting state into the HTML response.
+ *
+ * @param event - The SvelteKit RequestEvent for the current request.
+ * @param callback - A function that receives the edgesEvent and a serialize function,
+ *   and expects resolve of edgesEvent as a return result.
+ * @param silentChromeDevtools - If true, intercepts requests to
+ *   `/.well-known/appspecific/com.chrome.devtools.json` (triggered by Chrome DevTools)
+ *   and returns a 204 No Content response just to avoid spamming logs.
+ */
+type EdgesHandle = (
+	event: RequestEvent,
+	callback: (params: { edgesEvent: RequestEvent; serialize: (html: string) => string }) => Promise<Response> | Response,
+	silentChromeDevtools?: boolean
+) => Promise<Response>;
+```
+
+---
+
+## FAQ
+
+### Why not just use `writable, derived`?
+
+Because `writable` and `derived` shares state between requests when used on the server. That means users could leak state into each other’s responses. **Edge-S** solves that by isolating state per request.
+
+### Difference between `createState` and `createRawState`
+
+`createRawState` is just like `$state`, but ssr-safe. It is a lightweight reactive variable and has no subscription. Access and change value through `.value`.
+💡 Use `myState.value` to get/set the value directly — no `$` sugar and set, update methods.
+
+---
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+Crafted with ❤️ by Pixel1917.

package/dist/context/Context.d.ts

@@ -0,0 +1,9 @@
+import type { RequestEvent } from '@sveltejs/kit';
+export interface ContextData {
+    event?: RequestEvent;
+    symbol?: symbol;
+}
+declare const _default: {
+    current(): ContextData;
+};
+export default _default;

package/dist/context/Context.js

@@ -0,0 +1,9 @@
+import { browser } from '$app/environment';
+export default {
+    current() {
+        if (!browser) {
+            throw new Error('AsyncLocalStorage has not been initialized');
+        }
+        return {};
+    }
+};

package/dist/context/index.d.ts

@@ -0,0 +1 @@
+export { default as RequestContext, type ContextData } from './Context.js';

package/dist/context/index.js

@@ -0,0 +1 @@
+export { default as RequestContext } from './Context.js';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './provider/Provider.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './provider/Provider.js';

package/dist/provider/Provider.d.ts

@@ -0,0 +1,13 @@
+import { createState, createDerivedState, createRawState } from '../store/index.js';
+type StoreDeps = {
+    createRawState: typeof createRawState;
+    createState: typeof createState;
+    createDerivedState: typeof createDerivedState;
+};
+interface CreateProviderOptions<T, I extends Record<string, unknown> = Record<string, unknown>> {
+    inject?: I;
+    factory: (args: StoreDeps & I) => T;
+}
+export declare const createProvider: <T, I extends Record<string, unknown> = Record<string, unknown>>(options: CreateProviderOptions<T, I>) => (() => T);
+export declare const createProviderFactory: <I extends Record<string, unknown>>(inject: I) => <T>(options: CreateProviderOptions<T, I>) => () => T;
+export {};

package/dist/provider/Provider.js

@@ -0,0 +1,20 @@
+import { createState, createDerivedState, createRawState } from '../store/index.js';
+export const createProvider = (options) => {
+    const deps = {
+        ...{
+            createState,
+            createRawState,
+            createDerivedState
+        },
+        ...(options.inject || {})
+    };
+    return () => options.factory(deps);
+};
+export const createProviderFactory = (inject) => {
+    return function createInjectedProvider(options) {
+        return createProvider({
+            ...options,
+            inject
+        });
+    };
+};

package/dist/provider/index.d.ts

@@ -0,0 +1 @@
+export * from './Provider.js';

package/dist/provider/index.js

@@ -0,0 +1 @@
+export * from './Provider.js';

package/dist/server/EdgesHandle.d.ts

@@ -0,0 +1,18 @@
+import type { RequestEvent } from '@sveltejs/kit';
+type EdgesHandle = (event: RequestEvent, callback: (params: {
+    edgesEvent: RequestEvent;
+    serialize: (html: string) => string;
+}) => Promise<Response> | Response, silentChromeDevtools?: boolean) => Promise<Response>;
+/**
+ * Wraps request handling in an AsyncLocalStorage context and provides a `serialize` function
+ * for injecting state into the HTML response.
+ *
+ * @param event - The SvelteKit RequestEvent for the current request.
+ * @param callback - A function that receives the event and a serialize function,
+ *   and returns a Response or a Promise of one.
+ * @param silentChromeDevtools - If true, intercepts requests to
+ *   `/.well-known/appspecific/com.chrome.devtools.json` (triggered by Chrome DevTools)
+ *   and returns a 204 No Content response instead of a 404 error.
+ */
+export declare const edgesHandle: EdgesHandle;
+export {};

package/dist/server/EdgesHandle.js

@@ -0,0 +1,37 @@
+import { stateSerialize } from '../store/State.svelte.js';
+import { AsyncLocalStorage } from 'async_hooks';
+import RequestContext, {} from '../context/Context.js';
+const storage = new AsyncLocalStorage();
+/**
+ * Wraps request handling in an AsyncLocalStorage context and provides a `serialize` function
+ * for injecting state into the HTML response.
+ *
+ * @param event - The SvelteKit RequestEvent for the current request.
+ * @param callback - A function that receives the event and a serialize function,
+ *   and returns a Response or a Promise of one.
+ * @param silentChromeDevtools - If true, intercepts requests to
+ *   `/.well-known/appspecific/com.chrome.devtools.json` (triggered by Chrome DevTools)
+ *   and returns a 204 No Content response instead of a 404 error.
+ */
+export const edgesHandle = async (event, callback, silentChromeDevtools = false) => {
+    return await storage.run({ event: event, symbol: Symbol() }, async () => {
+        RequestContext.current = () => {
+            const context = storage.getStore();
+            if (context === undefined) {
+                throw new Error('Request symbol has not been initialized');
+            }
+            return context;
+        };
+        if (silentChromeDevtools && event.url.pathname === '/.well-known/appspecific/com.chrome.devtools.json') {
+            return new Response(null, { status: 204 });
+        }
+        return callback({
+            edgesEvent: event,
+            serialize: (html) => {
+                if (!html)
+                    return html ?? '';
+                return html.replace('</body>', `${stateSerialize()}</body>`);
+            }
+        });
+    });
+};

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export * from './EdgesHandle.js';

package/dist/server/index.js

@@ -0,0 +1 @@
+export * from './EdgesHandle.js';

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

@@ -0,0 +1,12 @@
+import { type Readable, type Writable } from 'svelte/store';
+declare global {
+    interface Window {
+        __SAFE_SSR_STATE__?: Map<string, unknown>;
+    }
+}
+export declare const stateSerialize: () => string;
+export declare const createRawState: <T>(key: string, initial: () => T) => {
+    value: T;
+};
+export declare const createState: <T>(key: string, initial: () => T) => Writable<T>;
+export declare const createDerivedState: <T, D>(stores: Readable<T>[] | [Readable<T>], deriveFn: (values: [T] | T[]) => D) => Readable<D>;

package/dist/store/State.svelte.js

@@ -0,0 +1,100 @@
+import RequestContext from '../context/Context.js';
+import { uneval } from 'devalue';
+import { browser } from '$app/environment';
+import { derived, writable } from 'svelte/store';
+const RequestStores = new WeakMap();
+export const stateSerialize = () => {
+    const map = getRequestContext();
+    if (map) {
+        const entries = Array.from(map).map(([key, value]) => [uneval(key), uneval(value)]);
+        return `<script>
+			window.__SAFE_SSR_STATE__ = new Map();
+			${entries.map(([key, value]) => `window.__SAFE_SSR_STATE__.set(${key}, ${value})`).join(';')}
+			</script>`;
+    }
+    return '';
+};
+const getRequestContext = () => {
+    const sym = RequestContext.current().symbol;
+    if (sym) {
+        return RequestStores.get(sym) ?? RequestStores.set(sym, new Map()).get(sym);
+    }
+};
+const getBrowserState = (key, initial) => {
+    const state = window.__SAFE_SSR_STATE__?.get(key);
+    if (state)
+        return state;
+    return initial;
+};
+export const createRawState = (key, initial) => {
+    if (browser) {
+        let state = getBrowserState(key, initial());
+        return {
+            get value() {
+                return state;
+            },
+            set value(val) {
+                state = val;
+            }
+        };
+    }
+    const map = getRequestContext();
+    return {
+        get value() {
+            if (!map)
+                return undefined;
+            if (!map.has(key))
+                map.set(key, structuredClone(initial()));
+            return map.get(key);
+        },
+        set value(val) {
+            if (map) {
+                map.set(key, val);
+            }
+        }
+    };
+};
+export const createState = (key, initial) => {
+    if (browser) {
+        return writable(getBrowserState(key, initial()));
+    }
+    const map = getRequestContext();
+    if (!map)
+        throw new Error('No RequestContext available');
+    if (!map.has(key))
+        map.set(key, structuredClone(initial()));
+    const subscribers = new Set();
+    return {
+        subscribe(run) {
+            run(map.get(key));
+            subscribers.add(run);
+            return () => subscribers.delete(run);
+        },
+        set(val) {
+            map.set(key, val);
+            subscribers.forEach((fn) => fn(val));
+        },
+        update(updater) {
+            const oldVal = map.get(key);
+            const newVal = updater(oldVal);
+            map.set(key, newVal);
+            subscribers.forEach((fn) => fn(newVal));
+        }
+    };
+};
+export const createDerivedState = (stores, deriveFn) => {
+    if (browser) {
+        return derived(stores, deriveFn);
+    }
+    const values = stores.map((s) => {
+        let value;
+        s.subscribe((v) => (value = v))();
+        return value;
+    });
+    return {
+        subscribe(run) {
+            run(deriveFn(values));
+            return () => { };
+        }
+    };
+};

package/dist/store/index.d.ts

@@ -0,0 +1 @@
+export { createState, createRawState, createDerivedState } from './State.svelte.js';

package/dist/store/index.js

@@ -0,0 +1 @@
+export { createState, createRawState, createDerivedState } from './State.svelte.js';

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "edges-svelte",
+  "version": "0.3.1",
+  "license": "MIT",
+  "author": "Pixel1917",
+  "description": "A blazing-fast, extremely lightweight and SSR-friendly store for Svelte",
+  "homepage": "https://github.com/Pixel1917/edge-s",
+  "bugs": {
+    "url": "https://github.com/Pixel1917/edge-s/issues",
+    "email": "sank195951@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pixel1917/edge-s.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/EdgesHandle.d.ts",
+      "svelte": "./dist/server/EdgesHandle.js"
+    },
+    "./state": {
+      "types": "./dist/store/index.d.ts",
+      "svelte": "./dist/store/index.js"
+    }
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0",
+    "@sveltejs/kit": "^2.16.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^1.2.5",
+    "@eslint/js": "^9.18.0",
+    "@playwright/test": "^1.49.1",
+    "@sveltejs/adapter-auto": "^6.0.0",
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/package": "^2.0.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/svelte": "^5.2.4",
+    "@types/node": "^22.15.23",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-svelte": "^3.0.0",
+    "globals": "^16.0.0",
+    "jsdom": "^26.0.0",
+    "prettier": "^3.4.2",
+    "prettier-plugin-svelte": "^3.3.3",
+    "publint": "^0.3.2",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.20.0",
+    "vite": "^6.2.6",
+    "vitest": "^3.0.0",
+    "semantic-release": "^24.2.3",
+    "husky": "^9.1.7",
+    "git-cz": "^4.9.0",
+    "commitizen": "^4.3.1",
+    "env-cmd": "^10.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@commitlint/cli": "^19.7.1"
+  },
+  "config": {
+    "commitizen": {
+      "path": "git-cz"
+    }
+  },
+  "keywords": [
+    "sveltekit",
+    "svelte",
+    "store",
+    "state",
+    "edge-s",
+    "ssr state",
+    "state management",
+    "ssr store"
+  ],
+  "dependencies": {
+    "devalue": "^5.1.1"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && npm run prepack",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "prettier --write .",
+    "lint": "prettier --check . && eslint .",
+    "test:unit": "vitest",
+    "test": "npm run test:unit -- --run && npm run test:e2e",
+    "test:e2e": "playwright test",
+    "precommit": "pnpm lint && pnpm check",
+    "semantic-release": "env-cmd semantic-release",
+    "commit": "pnpm format && git add . && git-cz && git push",
+    "release": "pnpm commit && pnpm semantic-release"
+  }
+}