{"_id":"@adalink/spark-echo","name":"@adalink/spark-echo","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@adalink/spark-echo","version":"1.0.0","description":"Echo reactive web components library","type":"module","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/Adalink-ai/spark_echo.git"},"bugs":{"url":"https://github.com/Adalink-ai/spark_echo/issues"},"homepage":"https://github.com/Adalink-ai/spark_echo#readme","author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"exports":{".":{"import":"./dist/echo.js","require":"./dist/echo.cjs"},"./filter":{"import":"./dist/filter.js","require":"./dist/filter.cjs"}},"keywords":["web-components","custom-elements","reactive","filter","echo","web-development","event-system"],"devDependencies":{"@biomejs/biome":"2.4.7","@commitlint/cli":"^20.5.0","@commitlint/config-conventional":"^20.5.0","esbuild":"^0.27.2","husky":"^9.1.7","lint-staged":"^16.4.0","vite":"^8.0.0"},"scripts":{"build":"vite build","dev":"vite","lint":"biome check .","prepare":"husky"},"_id":"@adalink/spark-echo@1.0.0","gitHead":"50d9288c0ab282c9416e4a3fc53e60a70de8c45a","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-E4FVHrJLiR2IKUi5s0gEZuBBt7Hiy1p7BDxyR8ly+LOOR57qQmVlhH6wurbRLdNCOXI+JnxEduxnAiYH6dxFCA==","shasum":"70f7b00c1b24822fa80e2e17d1de3fb7d78b5da1","tarball":"https://registry.npmjs.org/@adalink/spark-echo/-/spark-echo-1.0.0.tgz","fileCount":9,"unpackedSize":31726,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHeLh09phwvgE9X51rCTRm3dCIF17FWuTJSVPMOs3s9UAiATjJL65wkH3U/1W0t6loh3HiMD9MzMA6hrdFygZm2Q9g=="}]},"_npmUser":{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"},"directories":{},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/spark-echo_1.0.0_1773856912113_0.14458963273207637"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T18:01:52.022Z","1.0.0":"2026-03-18T18:01:52.290Z","modified":"2026-03-18T18:01:52.514Z"},"maintainers":[{"name":"cleiton.couto","email":"cleiton.couto@adalink.ai"}],"description":"Echo reactive web components library","homepage":"https://github.com/Adalink-ai/spark_echo#readme","keywords":["web-components","custom-elements","reactive","filter","echo","web-development","event-system"],"repository":{"type":"git","url":"git+https://github.com/Adalink-ai/spark_echo.git"},"author":{"name":"Cleber de Moraes Goncalves","email":"cleber.engineer@gmail.com","url":"https://github.com/deMGoncalves"},"bugs":{"url":"https://github.com/Adalink-ai/spark_echo/issues"},"license":"Apache-2.0","readme":"# ⚡ Spark Echo Library\n\n[![npm version](https://img.shields.io/npm/v/@adalink/spark-echo?style=flat-square)](https://www.npmjs.com/package/@adalink/spark-echo)\n[![License](https://img.shields.io/npm/l/@adalink/spark-echo?style=flat-square)](LICENSE)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/Adalink-ai/spark_echo/ci.yml?style=flat-square)](https://github.com/Adalink-ai/spark_echo/actions)\n[![Code Style](https://img.shields.io/badge/code_style-biome-purple?style=flat-square)](https://biomejs.dev)\n\n**Echo reactive web components library. Zero dependencies, reactive event-driven architecture.**\n\n---\n\n## 📖 What is Echo?\n\nEcho is a modern, lightweight library that provides a **reactive event arc system** for Web Components. Built on native Web Components APIs, it enables components to communicate through a declarative event routing system with powerful data transformation capabilities.\n\n### 🎯 Why Choose Echo?\n\n- **Zero Dependencies** - No runtime dependencies, just pure Web Platform APIs\n- **Declarative Event Arcs** - Describe component communication via HTML attributes\n- **Reactive by Default** - Components automatically respond to events\n- **Framework Agnostic** - Works with any framework or vanilla JavaScript\n- **Performance First** - Optimized for speed with minimal bundle size (~2KB)\n- **Production Ready** - Battle-tested in real-world applications\n\n### 🚀 Perfect For\n\n- **Web Components Projects** - Add reactive communication to native Web Components\n- **Event-Driven Architecture** - Build applications with pub/sub patterns\n- **Performance-Critical Apps** - Minimal overhead, maximum speed\n- **Micro-Frontends** - Isolated components with clean event interfaces\n- **Real-time Updates** - Reactive data flows between components\n\n---\n\n## ✨ Key Features\n\n### 🎯 Declarative Event Arcs\n\nDescribe component communication declaratively using HTML attributes:\n\n```javascript\n// Traditional approach\nclass MyComponent extends HTMLElement {\n  connectedCallback() {\n    document.addEventListener('custom-event', this.handleEvent.bind(this));\n  }\n\n  disconnectedCallback() {\n    document.removeEventListener('custom-event', this.handleEvent.bind(this));\n  }\n\n  handleEvent(event) {\n    if (event.detail.id === 'some-component') {\n      this.value = event.detail.data;\n    }\n  }\n}\n\n// Echo approach\nclass MyComponent extends Echo(HTMLElement) {}\n\n// In HTML:\n<my-component on=\"*custom-event:attribute/value\"></my-component>\n```\n\n### 📦 Simple API\n\nOnly import what you need:\n\n```javascript\nimport Echo, { filter } from '@adalink/spark-echo';\n\n// Create reactive component\nclass MyComponent extends Echo(HTMLElement) {}\n```\n\n### ⚡ High Performance\n\n- Event delegation (single listener per component)\n- Automatic cleanup (no memory leaks)\n- Lazy event registration\n- No framework overhead\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Using npm\nnpm install @adalink/spark-echo\n\n# Using yarn\nyarn add @adalink/spark-echo\n\n# Using pnpm\npnpm add @adalink/spark-echo\n\n# Using bun\nbun add @adalink/spark-echo\n```\n\n### Your First Reactive Component\n\nCreate a reactive counter with automatic event propagation:\n\n```javascript\nimport Echo, { filter } from '@adalink/spark-echo';\n\nclass Counter extends Echo(HTMLElement) {\n  #count = 0;\n\n  static observedAttributes = ['count'];\n\n  attributeChangedCallback(name, oldValue, newValue) {\n    if (name === 'count') {\n      this.#count = parseInt(newValue, 10);\n      this.updateDisplay();\n    }\n  }\n\n  connectedCallback() {\n    this.updateDisplay();\n  }\n\n  updateDisplay() {\n    this.innerHTML = `\n      <div class=\"counter\">\n        <h2>Count: ${this.#count}</h2>\n        <button class=\"increment\">+1</button>\n        <button class=\"reset\">Reset</button>\n      </div>\n    `;\n\n    this.querySelector('.increment').addEventListener('click', () => {\n      this.#count++;\n      this.dispatchEvent(new CustomEvent('change', {\n        detail: this.#count,\n        bubbles: true,\n        composed: true\n      }));\n    });\n\n    this.querySelector('.reset').addEventListener('click', () => {\n      this.#count = 0;\n      this.dispatchEvent(new CustomEvent('change', {\n        detail: this.#count,\n        bubbles: true,\n        composed: true\n      }));\n    });\n  }\n}\n\ncustomElements.define('my-counter', Counter);\n```\n\nUse it in your HTML:\n\n```html\n<my-counter id=\"counter1\" count=\"0\"></my-counter>\n\n<!-- Another component that listens to counter changes -->\n<my-display on=\"#counter1/change:method/handleUpdate\"></my-display>\n```\n\n---\n\n## 📦 Event Arc Syntax\n\nThe power of Echo comes from its declarative event arc syntax:\n\n### Arc Format\n\n```\nsource/event:type/sink|filter1|filter2\n```\n\n### Components\n\n- **source**: Where the event comes from\n  - `*` - Any component\n  - `#id` - Specific component by ID\n  - `name` - Component by name attribute\n  - `node` - Component by node name (tag)\n\n- **event**: Event type to listen for\n  - `click`, `change`, `input`, `custom-event`, etc.\n\n- **type**: How to apply the result\n  - `method` - Call a method on this component\n  - `attribute` - Set an HTML attribute\n  - `setter` - Set a property\n\n- **sink**: Where to apply the result\n  - Method name, attribute name, or property name\n\n- **filters**: Data transformations (optional, multiple with `|`)\n  - `filtername=value` - Apply filter with parameter\n\n### Examples\n\n```html\n<!-- Listen to any component's click events and call handleClick -->\n<my-component on=\"*click:method/handleClick\"></my-component>\n\n<!-- Listen to specific component's change events and set value attribute -->\n<my-display on=\"#counter/change:attribute/value\"></my-display>\n\n<!-- Listen to component by name and set property -->\n<my-log on=\"logger/input:setter/message\"></my-log>\n\n<!-- Multiple filters: add 10 then convert to string -->\n<my-component on=\"*data:method/handleData|add=10|toString\"></my-component>\n```\n\n---\n\n## 🎯 Available Filters\n\nEcho includes powerful data transformation filters:\n\n### Basic Filters\n\n```javascript\nimport filter from '@adalink/spark-echo/filter';\n```\n\n- **truthy** - Filter truthy values\n- **always** - Always return the value\n- **equals** - Compare with value\n- **different** - Compare for difference\n\n### Math Filters\n\n- **add** - Add value: `|add=10`\n- **subtract** - Subtract value: `|subtract=5`\n- **inc** - Increment by 1: `|inc`\n- **dec** - Decrement by 1: `|dec`\n\n### Comparison Filters\n\n- **gt** - Greater than: `|gt=10`\n- **gte** - Greater than or equal: `|gte=10`\n- **lt** - Less than: `|lt=10`\n- **lte** - Less than or equal: `|lte=10`\n\n### Property Filters\n\n- **prop** - Get nested property: `|prop=user.name`\n- **len** - Get length: `|len`\n\n### Register Custom Filters\n\n```javascript\nimport filter from '@adalink/spark-echo/filter';\n\nfilter.set('uppercase', (data) => data.toUpperCase());\nfilter.set('reverse', (data) => data.split('').reverse().join(''));\n```\n\n---\n\n## 🎯 Real-World Use Cases\n\n### Form Validation\n\n```html\n<form>\n  <input type=\"text\" id=\"username\" />\n  <input type=\"password\" id=\"password\" />\n  <my-button on=\"*change:method/checkValidity\"></my-button>\n  <my-error on=\"*invalid:method/showError\"></my-error>\n</form>\n```\n\n```javascript\nclass FormValidator extends Echo(HTMLElement) {\n  checkValidity({ detail }) {\n    const isValid = this.validate(detail);\n    if (!isValid) {\n      this.dispatchEvent(new CustomEvent('invalid', {\n        detail: { field: detail.field, error: 'Invalid input' }\n      }));\n    }\n  }\n}\n```\n\n### Data Synchronization\n\n```html\n<my-list id=\"items\" data='[1,2,3]'></my-list>\n<my-chart on=\"#items/change:method/update|prop=length\"></my-chart>\n<my-counter on=\"#items/change:method/setCount|prop=length\"></my-counter>\n```\n\n### Parent-Child Communication\n\n```html\n<parent-component>\n  <child-component on=\"parent/action:method/childAction\"></child-component>\n</parent-component>\n```\n\n---\n\n## 🎯 Advanced Usage\n\n### Multiple Event Arcs\n\n```html\n<my-component\n  on=\"*click:method/handleClick|add=1|toString\"\n  on=\"*change:attribute/value|prop=data.newValue\"\n  on=\"*error:method/handleError\">\n</my-component>\n```\n\n### Filter Chains\n\n```html\n<!-- Transform data through multiple filters -->\n<my-component on=\"*data:method/process|add=10|multiply=2|toFixed=2|toString\"></my-component>\n```\n\n### Cross-Component Communication\n\n```html\n<!-- Component A broadcasts events -->\n<my-broadcaster id=\"broadcaster\"></my-broadcaster>\n\n<!-- Component B listens to A -->\n<my-listener on=\"#broadcaster/message:method/handleMessage|prop=content\"></my-listener>\n\n<!-- Component C also listens to A -->\n<my-logger on=\"#broadcaster/message:method/logMessage|len|toString\"></my-logger>\n```\n\n---\n\n## 📊 Why Echo Over Alternatives?\n\n| Feature | Echo | Event Bus | Redux | Signals |\n|---------|------|-----------|-------|---------|\n| Zero Dependencies | ✅ | ❌ | ❌ | ⚠️ |\n| Native Web Components | ✅ | ✅ | ⚠️ | ✅ |\n| Declarative Syntax | ✅ | ❌ | ❌ | ⚠️ |\n| Built-in Filters | ✅ | ❌ | ❌ | ❌ |\n| Automatic Cleanup | ✅ | ⚠️ | ✅ | ✅ |\n| Bundle Size | ~2KB | ~5KB | ~15KB | ~8KB |\n| Framework Agnostic | ✅ | ✅ | ⚠️ | ✅ |\n\n---\n\n## 🌐 Usage in Frameworks\n\n### With React\n\n```javascript\nimport Echo from '@adalink/spark-echo';\n\nclass ReactBridge extends Echo(HTMLElement) {\n  connectedCallback() {\n    this.addEventListener('react-click', (e) => {\n      // Call React component method\n      this._reactHandler?.(e.detail);\n    });\n  }\n}\n\ncustomElements.define('react-bridge', ReactBridge);\n\n// In React\nfunction App() {\n  const handleClick = (data) => console.log(data);\n\n  return <react-bridge ref={(el) => el._reactHandler = handleClick} />;\n}\n```\n\n### With Vue\n\n```javascript\nimport Echo from '@adalink/spark-echo';\n\nclass VueBridge extends Echo(HTMLElement) {\n  connectedCallback() {\n    this.addEventListener('vue-event', (e) => {\n      // Emit to Vue component\n      this._vueComponent?.$emit('vue-event', e.detail);\n    });\n  }\n}\n\ncustomElements.define('vue-bridge', VueBridge);\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js 18+\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/Adalink-ai/spark_echo.git\ncd spark_echo\n\n# Install dependencies\nnpm install\n\n# Build package\nnpm run build\n\n# Start development server\nnpm run dev\n\n# Lint and format\nnpm run lint\n```\n\n---\n\n## 📚 Documentation\n\n- **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md) - Design decisions and patterns\n- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) - Development guidelines\n- **Security:** [SECURITY.md](SECURITY.md) - Security policies\n- **Changelog:** [CHANGELOG.md](CHANGELOG.md) - Project changes\n- **Authors:** [AUTHORS.md](AUTHORS.md) - Author information\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) before getting started.\n\n**Ways to contribute:**\n- 🐛 [Report bugs](https://github.com/Adalink-ai/spark_echo/issues/new?template=bug_report.md)\n- 💡 [Suggest features](https://github.com/Adalink-ai/spark_echo/issues/new?template=feature_request.md)\n- 📖 [Improve documentation](https://github.com/Adalink-ai/spark_echo/issues/new?template=documentation.md)\n- 🔧 [Submit pull requests](https://github.com/Adalink-ai/spark_echo/pulls)\n\n---\n\n## 👥 Author & Community\n\n**Cleber de Moraes Goncalves** - Creator & Lead Maintainer\n\n- 📧 Email: cleber.engineer@gmail.com\n- 🐙 GitHub: [deMGoncalves](https://github.com/deMGoncalves)\n- 💼 LinkedIn: [deMGoncalves](https://linkedin.com/in/deMGoncalves)\n- 📸 Instagram: [deMGoncalves](https://instagram.com/deMGoncalves)\n\n### 🌟 Star the Project\n\nIf you find Echo useful, please ⭐ star it on GitHub!\n\n### 📢 Share\n\nShare Echo with your network:\n- [Twitter](https://twitter.com/intent/tweet?text=Check%20out%20@adalink/spark-echo%20-%20Reactive%20event%20arc%20system%20for%20web%20components!&url=https://github.com/Adalink-ai/spark_echo)\n- [LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https://github.com/Adalink-ai/spark_echo&title=Spark%20Echo%20Library&summary=Reactive%20event%20arc%20system%20for%20web%20components)\n\n---\n\n## 📄 License\n\n[Apache-2.0](LICENSE) © 2026 Adalink\n\n---\n\n## 🔗 Links\n\n- **Repository:** [github.com/Adalink-ai/spark_echo](https://github.com/Adalink-ai/spark_echo)\n- **NPM Package:** [npmjs.com/package/@adalink/spark-echo](https://www.npmjs.com/package/@adalink/spark-echo)\n- **Organization:** [github.com/Adalink-ai](https://github.com/Adalink-ai)\n\n---\n\n**Built with ❤️ by [Adalink](https://github.com/Adalink-ai)**\n\n**Spark Echo Library** - Build reactive web components with event arcs. ⚡\n","readmeFilename":"README.md","_rev":"1-90a23c63723340b75c07a090708099f6"}