{"_id":"@alwatr/embedded-data","_rev":"19-e229bd8324ec29819fa048d84a1c95d9","name":"@alwatr/embedded-data","dist-tags":{"latest":"10.2.0"},"versions":{"9.19.0":{"name":"@alwatr/embedded-data","version":"9.19.0","keywords":["alwatr","browser","cross-platform","dom","ECMAScript","embedded-data","esm","framework-agnostic","hydration","javascript","json","module","mpa","nanolib","script-tag","spa","ssr","state","typescript","util","utility","validation"],"author":{"url":"https://ali.mihandoost.com","name":"S. Ali Mihandoost","email":"ali.mihandoost@gmail.com"},"license":"MPL-2.0","_id":"@alwatr/embedded-data@9.19.0","maintainers":[{"name":"alimd","email":"ali.mihan.doost@gmail.com"}],"homepage":"https://github.com/Alwatr/alwatr/tree/next/pkg/nanolib/embedded-data#readme","bugs":{"url":"https://github.com/Alwatr/alwatr/issues"},"dist":{"shasum":"12300c3b1525fa6ed749e86affd36ca899520cf9","tarball":"https://registry.npmjs.org/@alwatr/embedded-data/-/embedded-data-9.19.0.tgz","fileCount":11,"integrity":"sha512-LWk1eXPApsj9wOkE9X7oyPWFEoy3iDYnaa2RTw/YH/rtaXiWZFjx0oUb+NQzYktsqTZacy/dImbC1K1dyFR5aQ==","signatures":[{"sig":"MEUCIDuyuyIxiBMU2LKZvgY7a/Nrj0jzUWjI7wHsSWZKYc1RAiEAirE78KOh02uh74wpJFkQ/WxlcOEdtMz5ByEuDM0kyrg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45976},"type":"module","exports":{".":{"types":"./dist/main.d.ts","import":"./dist/main.js","default":"./dist/main.js"}},"gitHead":"20106a8e95925e2b6f895325afe1c7b7c263e2cc","scripts":{"b":"bun run build","t":"bun run test","w":"bun run watch","cl":"bun run clean","lint":"eslint src/ --ext .ts","test":"ALWATR_DEBUG=0 bun test","build":"bun run build:ts && bun run build:es","clean":"rm -rfv dist *.tsbuildinfo","watch":"bun run watch:ts & bun run watch:es","format":"prettier --write \"src/**/*.ts\"","build:es":"nano-build --preset=module src/main.ts","build:ts":"tsc --build","watch:es":"bun run build:es --watch","watch:ts":"bun run build:ts --watch --preserveWatchOutput"},"_npmUser":{"name":"alimd","email":"ali.mihan.doost@gmail.com"},"repository":{"url":"git+https://github.com/Alwatr/alwatr.git","type":"git","directory":"pkg/nanolib/embedded-data"},"_npmVersion":"lerna/5.2.0/node@v20.20.2+x64 (linux)","description":"Framework-agnostic utility to safely extract, parse, and validate embedded JSON data from \n```\n\nBut extracting this data safely requires:\n\n1. **SSR compatibility** — `document` might not exist in Node.js/Bun server contexts.\n2. **Error handling** — the script tag might be missing, empty, or contain invalid JSON.\n3. **Type safety** — the parsed JSON might not match the expected TypeScript type.\n4. **Memory management** — the (potentially large) JSON string should be freed after extraction.\n\n`@alwatr/embedded-data` encapsulates this entire pattern in a single, reusable class that follows the **Single Responsibility Principle**: it only handles DOM extraction and JSON parsing. Validation logic is externalized via an optional `validator` parameter (Open/Closed Principle).\n\n---\n\n## Architecture\n\n```\n┌───────────────────────────────────────────────────────────┐\n│ EmbeddedDataCollector │\n│ │\n│ constructor(attributeName, validator?) │\n│ └─ stores attributeName_ and optional validator_ │\n│ │\n│ collect(): T | null │\n│ ├─ getElement_() → querySelector script tag │\n│ ├─ extractRawData_() → read textContent, clear DOM │\n│ ├─ JSON.parse(rawData) │\n│ ├─ validator_?.(parsedData) → optional type-guard │\n│ └─ return validated data or null │\n└───────────────────────────────────────────────────────────┘\n```\n\n**Flow:**\n\n```\n[HTML with \n\nconst collector = new EmbeddedDataCollector<{apiUrl: string}>('data-config');\nconst config = collector.collect();\n\nif (config) {\n console.log('API URL:', config.apiUrl);\n}\n```\n\n### With Type-Guard Validation\n\n```ts\nimport {EmbeddedDataCollector} from '@alwatr/embedded-data';\n\ninterface UserProfile {\n userId: number;\n name: string;\n}\n\nfunction isUserProfile(data: unknown): data is UserProfile {\n return (\n typeof data === 'object'\n && data !== null\n && 'userId' in data\n && typeof (data as any).userId === 'number'\n && 'name' in data\n && typeof (data as any).name === 'string'\n );\n}\n\n// HTML: \n\nconst collector = new EmbeddedDataCollector('data-user', isUserProfile);\nconst user = collector.collect();\n\nif (user) {\n console.log(`User ${user.name} (ID: ${user.userId})`);\n} else {\n console.error('Invalid user data');\n}\n```\n\n### With Zod Schema Validation\n\n```ts\nimport {EmbeddedDataCollector} from '@alwatr/embedded-data';\nimport {z} from 'zod';\n\nconst userSchema = z.object({\n userId: z.number(),\n name: z.string(),\n email: z.string().email(),\n});\n\ntype User = z.infer;\n\nconst collector = new EmbeddedDataCollector('data-user', (data) => {\n const result = userSchema.safeParse(data);\n return result.success;\n});\n\nconst user = collector.collect();\n```\n\n### Lazy Initialization with `@alwatr/lazy`\n\nCombine with `@alwatr/lazy` to defer extraction until the data is actually needed:\n\n```ts\nimport {lazy} from '@alwatr/lazy';\nimport {EmbeddedDataCollector} from '@alwatr/embedded-data';\n\ninterface AppConfig {\n apiUrl: string;\n features: string[];\n}\n\nfunction isAppConfig(data: unknown): data is AppConfig {\n return typeof data === 'object' && data !== null && 'apiUrl' in data;\n}\n\nexport const appConfig = lazy(() => {\n const collector = new EmbeddedDataCollector('data-app-config', isAppConfig);\n return collector.collect();\n});\n\n// Later, when config is needed:\nconst config = appConfig.instance;\nif (config) {\n console.log('API URL:', config.apiUrl);\n}\n```\n\n### Centralized Data Registry Pattern\n\nFor larger applications, create a centralized registry of all embedded data sources:\n\n```ts\n// src/data/embedded-data.ts\nimport {lazy} from '@alwatr/lazy';\nimport {EmbeddedDataCollector} from '@alwatr/embedded-data';\nimport type {Shop, Product, User} from '../types.js';\n\nfunction isShopCollection(data: unknown): data is {items: Shop[]} {\n return typeof data === 'object' && data !== null && Array.isArray((data as any).items);\n}\n\nfunction isProductCollection(data: unknown): data is {items: Product[]} {\n return typeof data === 'object' && data !== null && Array.isArray((data as any).items);\n}\n\nfunction isUser(data: unknown): data is User {\n return typeof data === 'object' && data !== null && 'userId' in data;\n}\n\nexport const embeddedData = {\n shops: lazy(() => {\n const collector = new EmbeddedDataCollector<{items: Shop[]}>('data-shops', isShopCollection);\n return collector.collect();\n }),\n\n products: lazy(() => {\n const collector = new EmbeddedDataCollector<{items: Product[]}>('data-products', isProductCollection);\n return collector.collect();\n }),\n\n currentUser: lazy(() => {\n const collector = new EmbeddedDataCollector('data-user', isUser);\n return collector.collect();\n }),\n} as const;\n```\n\n```ts\n// Usage in components\nimport {embeddedData} from './data/embedded-data.js';\n\nconst shops = embeddedData.shops.instance;\nif (shops) {\n console.log('Loaded', shops.items.length, 'shops');\n}\n```\n\n---\n\n## API Reference\n\n### `class EmbeddedDataCollector`\n\n#### `constructor(attributeName: string, validator?: (data: unknown) => data is T)`\n\nCreates a new collector instance.\n\n- **`attributeName`**: The HTML attribute used to query the script tag (e.g., `'data-config'`).\n- **validator** (optional): A type-guard function or validation function (e.g., Zod schema parser) to ensure runtime type safety. Must be synchronous.\n\n#### `collect(): T | null`\n\nSynchronously extracts, parses, and validates the embedded JSON payload.\n\nReturns the validated data or `null` on any failure (missing element, parse error, validation failure).\n\n---\n\n## Design Decisions\n\n| Decision | Rationale |\n| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |\n| **Attribute-based selector** | More flexible than hardcoded IDs. Allows multiple script tags with different attributes on the same page. |\n| **`element.textContent = ''` after extraction** | Proactive memory management — the (potentially large) JSON string can be GC'd immediately after parsing. |\n| **Externalized validation** | Follows the Open/Closed Principle. The class is closed for modification but open for extension via the `validator` parameter. |\n| **Sync-only validator** | Keeps the API simple and synchronous. Async validation belongs in the business layer, not in the data extraction layer. |\n| **SSR guard (`typeof document === 'undefined'`)** | Prevents crashes in Node.js/Bun server contexts where `document` is not available. |\n| **Logger with optional chaining** | Debug methods (`logMethod`, `logMethodArgs`) are stripped in production builds when `ALWATR_DEBUG=0`. |\n\n---\n\n## Relation to Other Packages\n\n| Package | When to use instead |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `@alwatr/lazy` | Defer extraction until the data is actually needed (combine with `EmbeddedDataCollector`). |\n| `@alwatr/signal` | Reactive state management — use `EmbeddedDataCollector` to hydrate the initial state, then manage updates via signals. |\n| `@alwatr/fetch` | Fetching data from HTTP APIs (not embedded in the DOM). |\n| `@alwatr/local-storage` | Persisting state across sessions in the browser (not server-rendered). |\n\n---\n\n## HTML Setup\n\nOn the server side (SSR), render the JSON data into a script tag:\n\n```html\n\n\n \n My App\n \n \n \n \n {\n \"apiUrl\": \"https://api.example.com\",\n \"features\": [\"dark-mode\", \"analytics\"]\n }\n \n\n \n {\n \"userId\": 42,\n \"name\": \"Ali Mihandoost\",\n \"email\": \"ali@example.com\"\n }\n \n\n \n \n \n\n```\n\nOn the client side, use `EmbeddedDataCollector` to extract and validate the data:\n\n```ts\nimport {EmbeddedDataCollector} from '@alwatr/embedded-data';\n\nconst configCollector = new EmbeddedDataCollector('data-app-config');\nconst config = configCollector.collect();\n\nconst userCollector = new EmbeddedDataCollector('data-user-profile');\nconst user = userCollector.collect();\n```\n\n---\n\n## License\n\n[MPL-2.0](https://mozilla.org/MPL/2.0/) © [Alwatr](https://github.com/Alwatr)\n","readmeFilename":"README.md"}