@alwatr/flux 9.18.0 → 9.19.0

package/README.md

@@ -268,6 +268,58 @@ console.log(userPrefs.get()); // {theme: 'dark', lang: 'fa'}
 - **Type-safe** — full TypeScript support
 - **Migration-friendly** — bump `schemaVersion` to reset storage
 
+### 🌐 **SSR State Hydration**
+
+`@alwatr/embedded-data` bridges the gap between server-rendered HTML and client-side reactive state. The server embeds initial data as JSON inside `<script type="application/json">` tags; the client extracts, validates, and feeds it into signals — **zero extra HTTP round-trips, zero flash of empty content**.
+
+```html
+<!-- Server renders this into the HTML -->
+<script
+  type="application/json"
+  data-user-profile
+>
+  {"userId": 42, "name": "Ali", "role": "admin"}
+</script>
+```
+
+```typescript
+import {EmbeddedDataCollector} from '@alwatr/flux';
+import {lazy} from '@alwatr/lazy';
+
+interface UserProfile {
+  userId: number;
+  name: string;
+  role: 'admin' | 'user';
+}
+
+function isUserProfile(data: unknown): data is UserProfile {
+  return typeof data === 'object' && data !== null && 'userId' in data;
+}
+
+// Lazy: extraction runs only when .value is first accessed — not at module load.
+export const userProfile = lazy(() =>
+  new EmbeddedDataCollector<UserProfile>('data-user-profile', isUserProfile).collect(),
+);
+```
+
+```typescript
+// Feed into a signal — the rest of the app reacts normally
+import {createStateSignal} from '@alwatr/flux';
+
+const userSignal = createStateSignal<UserProfile | null>({
+  name: 'user',
+  initialValue: userProfile.value, // hydrated from DOM, no API call needed
+});
+```
+
+**Why this matters:**
+
+- **No flash of empty content** — state is available synchronously on first render
+- **No extra API call** — server already sent the data in the HTML payload
+- **SSR-safe** — `EmbeddedDataCollector` guards against missing `document` in Node.js/Bun
+- **Memory-efficient** — script tag content is cleared after extraction (GC hint)
+- **Type-safe** — optional type-guard validator ensures runtime safety
+
 ### 📄 **Page-Ready Signal for MPA**
 
 Lightweight page identity system for Multi-Page Applications:
@@ -915,6 +967,81 @@ Same as `createLocalStorageProvider` but uses `sessionStorage`.
 
 ---
 
+### Embedded Data
+
+#### `EmbeddedDataCollector<T>`
+
+Extracts, parses, and validates JSON embedded in `<script type="application/json">` DOM nodes. Designed for SSR state hydration — the server renders initial state into the HTML, the client reads it on boot without an extra HTTP round-trip.
+
+```typescript
+import {EmbeddedDataCollector} from '@alwatr/flux';
+
+// HTML: <script type="application/json" data-config>{"apiUrl":"https://api.example.com"}</script>
+
+const collector = new EmbeddedDataCollector<AppConfig>('data-config');
+const config = collector.collect(); // AppConfig | null
+```
+
+**Constructor:**
+
+```typescript
+new EmbeddedDataCollector<T>(
+  attributeName: string,           // HTML attribute to query (e.g. 'data-config')
+  validator?: (data: unknown) => data is T  // optional type-guard
+)
+```
+
+**`collect(): T | null`**
+
+Runs the full extraction pipeline:
+
+1. `querySelector('script[attributeName]')` — SSR-safe, returns `null` if `document` is undefined
+2. Read `textContent`, then set it to `''` (GC hint)
+3. `JSON.parse()`
+4. Run `validator` if provided
+5. Return typed data or `null` on any failure
+
+**With type-guard validation:**
+
+```typescript
+import {EmbeddedDataCollector} from '@alwatr/flux';
+import {createStateSignal} from '@alwatr/flux';
+
+interface CartState {
+  items: {id: number; qty: number}[];
+  total: number;
+}
+
+function isCartState(data: unknown): data is CartState {
+  return typeof data === 'object' && data !== null && Array.isArray((data as CartState).items);
+}
+
+// Extract once at boot, feed into signal
+const collector = new EmbeddedDataCollector<CartState>('data-cart', isCartState);
+
+const cartSignal = createStateSignal<CartState>({
+  name: 'cart',
+  initialValue: collector.collect() ?? {items: [], total: 0},
+});
+```
+
+**Combine with `@alwatr/lazy` for deferred extraction:**
+
+```typescript
+import {lazy} from '@alwatr/lazy';
+import {EmbeddedDataCollector} from '@alwatr/flux';
+
+// Extraction is deferred until .value is first accessed
+export const serverConfig = lazy(() =>
+  new EmbeddedDataCollector<ServerConfig>('data-server-config', isServerConfig).collect(),
+);
+
+// Somewhere in your bootstrap code:
+const config = serverConfig.value; // extracted here, cached forever
+```
+
+---
+
 ### Render State
 
 #### `renderState<R, T>(state, renderRecord, thisArg?)`
@@ -1172,6 +1299,7 @@ todosSignal.subscribe((todos) => {
 - **[@alwatr/signal](https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/signal)** — Fine-grained reactive signals (part of Flux)
 - **[@alwatr/action](https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/action)** — Global event delegation action bus (part of Flux)
 - **[@alwatr/directive](https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/directive)** — Attribute-based DOM directives (part of Flux)
+- **[@alwatr/embedded-data](https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/embedded-data)** — Extract and validate embedded JSON from DOM script tags for SSR hydration (part of Flux)
 - **[@alwatr/fsm](https://github.com/Alwatr/alwatr/tree/next/pkg/fsm)** — Type-safe Finite State Machine
 - **[@alwatr/nanotron](https://github.com/Alwatr/alwatr/tree/next/pkg/nanotron)** — Lightweight API server framework
 - **[@alwatr/nitrobase](https://github.com/Alwatr/alwatr/tree/next/pkg/nitrobase)** — In-memory JSON database

package/dist/main.d.ts

@@ -1,6 +1,7 @@
 export * from '@alwatr/signal';
 export * from '@alwatr/action';
 export * from '@alwatr/directive';
+export * from '@alwatr/embedded-data';
 export * from '@alwatr/render-state';
 export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,mBAAmB,qBAAqB,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAGA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,mBAAmB,qBAAqB,CAAC"}

package/dist/main.js

@@ -1,5 +1,5 @@
-/* 📦 @alwatr/flux v9.18.0 */
-export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as o,render as a,noChange as t,nothing as p}from"lit-html";import{ifDefined as f}from"lit-html/directives/if-defined.js";import{cache as g}from"lit-html/directives/cache.js";import{classMap as i}from"lit-html/directives/class-map.js";import{when as s}from"lit-html/directives/when.js";export{s as when,a as render,p as nothing,t as noChange,f as ifDefined,o as html,i as classMap,g as cache};
+/* 📦 @alwatr/flux v9.19.0 */
+export*from"@alwatr/signal";export*from"@alwatr/action";export*from"@alwatr/directive";export*from"@alwatr/embedded-data";export*from"@alwatr/render-state";export*from"@alwatr/local-storage";export*from"@alwatr/session-storage";export*from"@alwatr/page-ready";import{html as e,render as t,noChange as a,nothing as p}from"lit-html";import{ifDefined as n}from"lit-html/directives/if-defined.js";import{cache as g}from"lit-html/directives/cache.js";import{classMap as i}from"lit-html/directives/class-map.js";import{when as s}from"lit-html/directives/when.js";export{s as when,t as render,p as nothing,a as noChange,n as ifDefined,e as html,i as classMap,g as cache};
 
-//# debugId=432FAE968752561764756E2164756E21
+//# debugId=3C8541CE38BF180764756E2164756E21
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/main.ts", "../src/lit-html.ts"],
   "sourcesContent": [
-    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport * from './lit-html.js';\nexport type * from '@alwatr/type-helper';\n",
+    "// UI and reactive bundle — signals, actions, directives, and client-side storage.\n// This package aggregates all UI-layer nanolibs for convenient single-import usage.\n\nexport * from '@alwatr/signal';\nexport * from '@alwatr/action';\nexport * from '@alwatr/directive';\nexport * from '@alwatr/embedded-data';\nexport * from '@alwatr/render-state';\nexport * from '@alwatr/local-storage';\nexport * from '@alwatr/session-storage';\nexport * from '@alwatr/page-ready';\nexport * from './lit-html.js';\nexport type * from '@alwatr/type-helper';\n",
     "/**\n * Curated re-exports from `lit-html` for use within `@alwatr/flux`.\n *\n * Only the subset of `lit-html` APIs that are commonly needed in a Flux-based\n * application is exported here. This keeps the public surface minimal and\n * avoids pulling in advanced directive utilities that most consumers never use.\n *\n * **Exported APIs:**\n * - `html` — tagged template literal that produces a `TemplateResult`\n * - `render` — renders a `TemplateResult` into a DOM container\n * - `noChange` — sentinel that tells lit-html to leave the current part value unchanged\n * - `nothing` — sentinel that renders nothing (removes the node/attribute)\n * - `ifDefined` — renders a value only when it is not `undefined`\n * - `cache` — caches rendered templates to avoid re-parsing on state changes\n * - `classMap` — efficiently sets/removes CSS classes from an object map\n * - `when` — conditional rendering helper (`when(condition, trueCase, falseCase)`)\n *\n * @example\n * ```typescript\n * import {html, render, classMap, when} from '@alwatr/flux';\n *\n * const template = (isActive: boolean) => html`\n *   <div class=${classMap({active: isActive, hidden: !isActive})}>\n *     ${when(isActive, () => html`<span>Active</span>`, () => html`<span>Inactive</span>`)}\n *   </div>\n * `;\n *\n * render(template(true), document.getElementById('app')!);\n * ```\n */\nexport {html, render, noChange, nothing} from 'lit-html';\n// export {Directive, PartType, directive} from 'lit-html/directive.js';\n// export {AsyncDirective} from 'lit-html/async-directive.js';\n// export {unsafeSVG} from 'lit-html/directives/unsafe-svg.js';\nexport {ifDefined} from 'lit-html/directives/if-defined.js';\nexport {cache} from 'lit-html/directives/cache.js';\nexport {classMap} from 'lit-html/directives/class-map.js';\nexport {when} from 'lit-html/directives/when.js';\n\n// export type {Part, PartInfo} from 'lit-html/directive.js';\n// export type {LitUnstable} from 'lit-html';\n"
   ],
-  "mappings": ";AAGA,4BACA,4BACA,+BACA,kCACA,mCACA,qCACA,gCCqBA,eAAQ,YAAM,cAAQ,aAAU,iBAIhC,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ",
-  "debugId": "432FAE968752561764756E2164756E21",
+  "mappings": ";AAGA,4BACA,4BACA,+BACA,mCACA,kCACA,mCACA,qCACA,gCCoBA,eAAQ,YAAM,cAAQ,aAAU,iBAIhC,oBAAQ,0CACR,gBAAQ,qCACR,mBAAQ,yCACR,eAAQ",
+  "debugId": "3C8541CE38BF180764756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwatr/flux",
-  "version": "9.18.0",
+  "version": "9.19.0",
   "description": "UI and reactive library bundle for ECMAScript (JavaScript/TypeScript) projects — signals, actions, directives, and storage.",
   "license": "MPL-2.0",
   "author": "S. Ali Mihandoost <ali.mihandoost@gmail.com> (https://ali.mihandoost.com)",
@@ -21,8 +21,9 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@alwatr/action": "9.17.0",
+    "@alwatr/action": "9.19.0",
     "@alwatr/directive": "9.18.0",
+    "@alwatr/embedded-data": "9.19.0",
     "@alwatr/local-storage": "9.16.0",
     "@alwatr/page-ready": "9.16.0",
     "@alwatr/render-state": "9.16.0",
@@ -82,5 +83,5 @@
     "ui",
     "unidirectional-data-flow"
   ],
-  "gitHead": "ae7aed95106fd2e6d3c14f0628fc12ae8a29ea15"
+  "gitHead": "20106a8e95925e2b6f895325afe1c7b7c263e2cc"
 }

package/src/main.ts

@@ -4,6 +4,7 @@
 export * from '@alwatr/signal';
 export * from '@alwatr/action';
 export * from '@alwatr/directive';
+export * from '@alwatr/embedded-data';
 export * from '@alwatr/render-state';
 export * from '@alwatr/local-storage';
 export * from '@alwatr/session-storage';