Skip to content

Commit 9c9078d

Browse files
jamesgoberjamesgober
committed
1.0.0-Rc.1
1 parent a1071a7 commit 9c9078d

File tree

2 files changed

+197
-18
lines changed

2 files changed

+197
-18
lines changed

‎README.md‎

Lines changed: 196 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,202 @@
1-
<h1 align="center">
2-
<picture>
3-
<source media="(prefers-color-scheme: dark)" srcset="./docs/media/jamesgober-logo-dark.png">
4-
<img width="72" height="72" alt="Official brand mark and logo of James Gober. Image shows JG stylish initials encased in a hexagon outline." src="./docs/media/jamesgober-logo.png">
5-
</picture>
1+
<div align="center">
2+
<img width="120px" height="auto" src="https://raw.githubusercontent.com/jamesgober/jamesgober/main/media/icons/hexagon-3.svg" alt="Triple Hexagon">
3+
<h1>
4+
<strong>EVENT FLOW</strong>
5+
<br>
6+
<sub>
7+
<sup>
8+
JAVASCRIPT EVENT MANAGER
9+
</sup>
10+
</sub>
11+
<br>
12+
</h1>
13+
<p>
14+
Centralized, memory-safe event management for modern JavaScript applications — with throttling, debouncing namespaces, and full observer support.
15+
</p>
616
<br>
7-
<b>EventEngine</b>
8-
<br>
9-
<sup>
10-
<small>JavaScript Library</small>
11-
</sup>
12-
<br>
13-
</h1>
17+
<div>
18+
<!-- NPM version -->
19+
<a href="https://www.npmjs.com/package/@jamesgober/eventflow" alt="NPM Version">
20+
<img src="https://img.shields.io/npm/v/@jamesgober/eventflow.svg" alt="NPM Version">
21+
</a>
22+
<span>&nbsp;</span>
23+
<!-- NPM downloads -->
24+
<a href="https://www.npmjs.com/package/@jamesgober/eventflow" alt="NPM Downloads">
25+
<img src="https://img.shields.io/npm/dm/@jamesgober/eventflow.svg" alt="NPM Downloads">
26+
</a>
27+
<span>&nbsp;</span>
28+
<!-- Bundle size -->
29+
<img src="https://img.shields.io/codecov/c/github/jamesgober/event-flow" alt="CommonJS Badge">
30+
<span>&nbsp;</span>
31+
<!-- BCommonJS Badge -->
32+
<img src="https://img.shields.io/badge/module-CJS-informational" alt="CommonJS Badge">
33+
<span>&nbsp;</span>
34+
<img alt="GitHub" src="https://img.shields.io/github/license/jamesgober/event-flow">
35+
</div>
36+
</div>
37+
38+
<br>
39+
<p>
40+
<strong>EventFlow</strong> is a high-performance, memory-efficient event management layer built to replace messy DOM bindings and tangled listener logic.
41+
Instead of scattering <code>addEventListener</code> all over your UI, EventFlow gives you a centralized, declarative system for managing app-wide events with namespaces, throttling, debouncing, and observer support built right in.
42+
</p>
43+
<p>
44+
Ideal for reactive designs/interfaces, modular UIs, and JavaScript apps that demand control and consistency, EventFlow gives you the speed and structure of an event bus—without the bulk of bloated frameworks or the chaos of raw DOM wiring.
45+
</p>
46+
<br>
47+
48+
<h2>Features</h2>
49+
<ul>
50+
<li>
51+
Centralized event management
52+
</i>
53+
<li>
54+
<code>once</code>, <code>throttle</code>, and <code>debounce</code> support
55+
</i>
56+
<li>
57+
Namespaced event listeners (<code>on('click', fn, { namespace: 'ui' })</code>)
58+
</i>
59+
<li>
60+
Observer pattern (<code>observe</code>, <code>unobserve</code>)
61+
</i>
62+
<li>
63+
Full test coverage (Jest)
64+
</i>
65+
<li>
66+
No DOM pollution — pure logic, clean memory
67+
</i>
68+
<li>
69+
Built-in error protection with <code>doEvent</code>
70+
</i>
71+
<li>
72+
Works in <b>Node.js</b>, <b>Browser</b>, <b>JSDOM</b>, and <b>Hybrid environments</b>
73+
</i>
74+
</ul>
75+
76+
<br>
77+
78+
---
79+
80+
<h2>Usage</h2>
81+
82+
<p>
83+
<i>Install using npm</i>
84+
</p>
85+
86+
```bash
87+
npm install @jamesgober/eventflow
88+
```
89+
90+
<h3>Running Tests</h3>
91+
92+
```bash
93+
npm run test
94+
npm run coverage
95+
```
96+
97+
<h3>Documentation</h3>
98+
99+
```bash
100+
npm run docs
101+
```
14102

15-
&nbsp;
103+
<br>
16104

105+
<h3>Basic Usage</h3>
106+
107+
```js
108+
const EventFlow = require('@jamesgober/eventflow'); // or import if you use ESM
109+
const events = new EventFlow({ debug: true });
110+
111+
events.on('save', () => console.log('Saved!'));
112+
events.emit('save');
113+
114+
events.on('scroll', () => console.log('Scrolled!'), { throttle: 250 });
115+
events.on('submit', () => console.log('Form submitted!'), { once: true });
116+
```
117+
118+
<br>
119+
<h4>Observers (reactive-style):</h4>
120+
121+
```js
122+
events.observe('message', (data) => {
123+
console.log('New message received:', data);
124+
});
125+
126+
events.emit('message', { id: 1, text: 'Hello world' });
127+
```
128+
129+
<br>
130+
131+
<h3>API Summary</h3>
132+
<table>
133+
<thead>
134+
<tr>
135+
<th><h4>Method</h4></th>
136+
<th><h4>Description</h4></th>
137+
</tr>
138+
</thead>
139+
<tbody>
140+
<tr>
141+
<td><code>on()</code></td>
142+
<td>Register an event listener with optional modifiers</th>
143+
</tr>
144+
<tr>
145+
<td><code>off()</code></td>
146+
<td>Remove a listener by reference</td>
147+
</tr>
148+
<tr>
149+
<td><code>emit()</code></td>
150+
<td>Trigger an event with optional arguments</td>
151+
</tr>
152+
<tr>
153+
<td><code>observe()</code></td>
154+
<td>Register an observer that watches all emits</td>
155+
</tr>
156+
<tr>
157+
<td><code>unobserve()</code></td>
158+
<td>Remove an observer from an event</td>
159+
</tr>
160+
<td><code>_throttle()</code></td>
161+
<td>Internal helper for throttling</td>
162+
</tr>
163+
<tr>
164+
<td><code>_debounce()</code></td>
165+
<td>Internal helper for debouncing</td>
166+
</tr>
167+
<tr>
168+
<td><code>_applyModifiers()</code></td>
169+
<td>Wraps listeners with debounce/throttle/once logic</td>
170+
</tr>
171+
</tbody>
172+
</table>
173+
174+
175+
<br>
176+
177+
178+
<!-- LICENSE
179+
============================================================================ -->
180+
<div id="license">
181+
<br><hr>
182+
<h2>License</h2>
183+
<p>This is an open-source project licensed under the <b>MIT</b> license.</p>
184+
<p>All rights not explicitly granted in the MIT license are reserved. You may obtain a copy of the
185+
<b>License</b> at:
186+
<a href="https://opensource.org/licenses/MIT" title="MIT License" target="_blank">https://opensource.org/licenses/MIT</a>.
187+
</p>
188+
<p>Unless required by applicable law or agreed to in writing, software distributed under the <b>License</b> is distributed on an "<b>AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND</b>, either express or implied.</p>
189+
<br><p>See the <a href="./LICENSE" title="Software License file">LICENSE</a> file included with this project for the specific language governing permissions and limitations under the <b>License</b>.</p>
190+
<br>
191+
</div>
17192

18-
## Licence & copyright
19-
The **EventEngine** JavaScript library is an open-source project licensed under the **MIT** license.
20193

21-
All rights not explicitly granted in the MIT license are reserved. View the [LICENSE](https://github.com/jamesgober/EventEngine/blob/main/LICENSE) file that was provided with this source code for more information.
194+
<br>
22195

23-
Copyright &copy; 2024 James Gober (https://jamesgober.com).
196+
<!-- COPYRIGHT
197+
============================================================================ -->
198+
<div align="center">
199+
<br>
200+
<h2></h2>
201+
<sup>COPYRIGHT <small>&copy;</small> 2025 <strong>JAMES GOBER.</strong></sup>
202+
</div>

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.0.0-Dev.10
1+
1.0.0-RC1

0 commit comments

Comments
 (0)