@quazardous/quarkernel 2.2.2 → 2.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +143 -28
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,21 +1,45 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
Event orchestration with dependency ordering and shared context.
|
|
1
|
+
# QuarKernel
|
|
4
2
|
|
|
5
3
|
[](https://www.npmjs.com/package/@quazardous/quarkernel)
|
|
6
4
|
[](https://bundlephobia.com/package/@quazardous/quarkernel)
|
|
5
|
+
[](https://github.com/quazardous/quarkernel/blob/main/LICENSE)
|
|
6
|
+
|
|
7
|
+
**Event orchestration with dependency ordering, shared context, and state machines.**
|
|
8
|
+
|
|
9
|
+
TypeScript-first. Zero dependencies. < 2KB gzipped.
|
|
10
|
+
|
|
11
|
+
[](https://quazardous.github.io/quarkernel/qk-studio/)
|
|
12
|
+
[](https://quazardous.github.io/quarkernel/fsm-studio/)
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Why QuarKernel?
|
|
7
17
|
|
|
8
|
-
|
|
18
|
+
```typescript
|
|
19
|
+
// Other event libs: fire and pray
|
|
20
|
+
emitter.emit('user:login', data);
|
|
21
|
+
|
|
22
|
+
// QuarKernel: orchestrate with confidence
|
|
23
|
+
qk.on('user:login', fetchUser, { id: 'fetch' });
|
|
24
|
+
qk.on('user:login', logAnalytics, { after: ['fetch'] }); // Guaranteed order
|
|
25
|
+
qk.on('user:login', (e) => greet(e.context.user)); // Shared context
|
|
26
|
+
```
|
|
9
27
|
|
|
10
|
-
|
|
11
|
-
- **Shared context** - Pass state between listeners
|
|
12
|
-
- **Composite events** - React to event combinations
|
|
13
|
-
- **Wildcards** - Pattern matching (`user:*`)
|
|
14
|
-
- **TypeScript-first** - Full type safety
|
|
15
|
-
- **Zero dependencies** - No runtime deps
|
|
16
|
-
- **< 2KB gzipped**
|
|
28
|
+
**What makes it different:**
|
|
17
29
|
|
|
18
|
-
|
|
30
|
+
| Feature | mitt | emittery | **QuarKernel** |
|
|
31
|
+
|---------|:----:|:--------:|:--------------:|
|
|
32
|
+
| Dependency ordering | - | - | **Yes** |
|
|
33
|
+
| Shared context | - | - | **Yes** |
|
|
34
|
+
| Composite events | - | - | **Yes** |
|
|
35
|
+
| Wildcards | - | - | **Yes** |
|
|
36
|
+
| Async/await | - | Yes | **Yes** |
|
|
37
|
+
| TypeScript | Yes | Yes | **Yes** |
|
|
38
|
+
| < 2KB | Yes | Yes | **Yes** |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Install
|
|
19
43
|
|
|
20
44
|
```bash
|
|
21
45
|
npm install @quazardous/quarkernel
|
|
@@ -26,6 +50,8 @@ npm install @quazardous/quarkernel
|
|
|
26
50
|
<script src="https://unpkg.com/@quazardous/quarkernel@2/dist/index.umd.js"></script>
|
|
27
51
|
```
|
|
28
52
|
|
|
53
|
+
---
|
|
54
|
+
|
|
29
55
|
## Quick Start
|
|
30
56
|
|
|
31
57
|
```typescript
|
|
@@ -33,24 +59,21 @@ import { createKernel } from '@quazardous/quarkernel';
|
|
|
33
59
|
|
|
34
60
|
const qk = createKernel();
|
|
35
61
|
|
|
36
|
-
// Dependency ordering
|
|
62
|
+
// 1. Dependency ordering - control execution sequence
|
|
37
63
|
qk.on('checkout', async (e) => {
|
|
38
|
-
e.context.
|
|
64
|
+
e.context.inventory = await checkStock(e.data.items);
|
|
39
65
|
}, { id: 'stock' });
|
|
40
66
|
|
|
41
67
|
qk.on('checkout', async (e) => {
|
|
42
|
-
// Runs AFTER stock check
|
|
43
|
-
await processPayment(e.data.card, e.context.
|
|
68
|
+
// Runs AFTER stock check - guaranteed
|
|
69
|
+
await processPayment(e.data.card, e.context.inventory);
|
|
44
70
|
}, { after: ['stock'] });
|
|
45
71
|
|
|
46
72
|
await qk.emit('checkout', { items: ['sku-123'], card: 'tok_visa' });
|
|
47
73
|
```
|
|
48
74
|
|
|
49
|
-
## Composition
|
|
50
|
-
|
|
51
|
-
React to multiple events:
|
|
52
|
-
|
|
53
75
|
```typescript
|
|
76
|
+
// 2. Composite events - react to event combinations
|
|
54
77
|
import { Composition } from '@quazardous/quarkernel';
|
|
55
78
|
|
|
56
79
|
const checkout = new Composition([
|
|
@@ -59,22 +82,114 @@ const checkout = new Composition([
|
|
|
59
82
|
]);
|
|
60
83
|
|
|
61
84
|
checkout.onComposed(() => {
|
|
62
|
-
console.log('Both events fired!');
|
|
85
|
+
console.log('Both events fired - proceed to shipping!');
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
// 3. Wildcards - catch event patterns
|
|
91
|
+
qk.on('user:*', (e) => console.log('User action:', e.name));
|
|
92
|
+
// Matches: user:login, user:logout, user:signup...
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## State Machines (FSM)
|
|
98
|
+
|
|
99
|
+
Built-in finite state machine support with XState-compatible format:
|
|
100
|
+
|
|
101
|
+
```typescript
|
|
102
|
+
import { createMachine } from '@quazardous/quarkernel/fsm';
|
|
103
|
+
|
|
104
|
+
const order = createMachine({
|
|
105
|
+
id: 'order',
|
|
106
|
+
initial: 'draft',
|
|
107
|
+
context: { items: 0 },
|
|
108
|
+
states: {
|
|
109
|
+
draft: { on: { SUBMIT: 'pending' } },
|
|
110
|
+
pending: { on: { APPROVE: 'confirmed', REJECT: 'draft' } },
|
|
111
|
+
confirmed: { on: { SHIP: 'shipped' } },
|
|
112
|
+
shipped: {}
|
|
113
|
+
},
|
|
114
|
+
onEnter: {
|
|
115
|
+
confirmed: (ctx, { log }) => log('Order confirmed!')
|
|
116
|
+
},
|
|
117
|
+
on: {
|
|
118
|
+
SUBMIT: (ctx, { set }) => set({ submittedAt: Date.now() })
|
|
119
|
+
}
|
|
63
120
|
});
|
|
121
|
+
|
|
122
|
+
order.send('SUBMIT');
|
|
123
|
+
console.log(order.state); // 'pending'
|
|
64
124
|
```
|
|
65
125
|
|
|
126
|
+
**Features:**
|
|
127
|
+
- XState import/export (`fromXState`, `toXState`)
|
|
128
|
+
- Behavior helpers: `set()`, `send()`, `log()`
|
|
129
|
+
- Auto-timers for delayed transitions
|
|
130
|
+
- Visual debugging with [FSM Studio](https://quazardous.github.io/quarkernel/fsm-studio/)
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
66
134
|
## Framework Adapters
|
|
67
135
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
136
|
+
Official bindings with auto-cleanup on unmount:
|
|
137
|
+
|
|
138
|
+
| Package | Framework | Docs |
|
|
139
|
+
|---------|-----------|------|
|
|
140
|
+
| `@quazardous/quarkernel-vue` | Vue 3 | [README](https://github.com/quazardous/quarkernel/blob/main/packages/vue/README.md) |
|
|
141
|
+
| `@quazardous/quarkernel-react` | React 18+ | [README](https://github.com/quazardous/quarkernel/blob/main/packages/react/README.md) |
|
|
142
|
+
| `@quazardous/quarkernel-svelte` | Svelte 5 | [README](https://github.com/quazardous/quarkernel/blob/main/packages/svelte/README.md) |
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
# Vue
|
|
146
|
+
npm install @quazardous/quarkernel @quazardous/quarkernel-vue
|
|
147
|
+
|
|
148
|
+
# React
|
|
149
|
+
npm install @quazardous/quarkernel @quazardous/quarkernel-react
|
|
150
|
+
|
|
151
|
+
# Svelte
|
|
152
|
+
npm install @quazardous/quarkernel @quazardous/quarkernel-svelte
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
71
156
|
|
|
72
157
|
## Documentation
|
|
73
158
|
|
|
74
|
-
|
|
75
|
-
- [
|
|
76
|
-
- [
|
|
159
|
+
**Guides:**
|
|
160
|
+
- [Getting Started](https://github.com/quazardous/quarkernel/blob/main/docs/getting-started.md) - Installation, first event, basic usage
|
|
161
|
+
- [API Reference](https://github.com/quazardous/quarkernel/blob/main/docs/api-reference.md) - Complete API documentation
|
|
162
|
+
- [Advanced Patterns](https://github.com/quazardous/quarkernel/blob/main/docs/advanced-qk.md) - Multi-machine, composition, sagas
|
|
163
|
+
- [Async Integration](https://github.com/quazardous/quarkernel/blob/main/docs/async-patterns.md) - QK + FSM + Promises synergies
|
|
164
|
+
- [Migration v1 to v2](https://github.com/quazardous/quarkernel/blob/main/docs/migration-v1-to-v2.md) - Upgrade guide
|
|
165
|
+
|
|
166
|
+
**Packages:**
|
|
167
|
+
- [Core package](https://github.com/quazardous/quarkernel/blob/main/packages/quarkernel/README.md) - Main QuarKernel library
|
|
168
|
+
|
|
169
|
+
**Resources:**
|
|
170
|
+
- [Benchmarks](https://github.com/quazardous/quarkernel/blob/main/benchmarks/README.md) - Performance comparisons
|
|
171
|
+
- [Demos](https://github.com/quazardous/quarkernel/blob/main/demos/README.md) - Live examples
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Use Cases
|
|
176
|
+
|
|
177
|
+
**Request pipeline** - Auth, validate, transform, respond in guaranteed order
|
|
178
|
+
|
|
179
|
+
**Game events** - Combo detection with composite events
|
|
180
|
+
|
|
181
|
+
**Form wizards** - Step dependencies with shared validation context
|
|
182
|
+
|
|
183
|
+
**Order workflows** - State machines for order lifecycle (draft → pending → confirmed → shipped)
|
|
184
|
+
|
|
185
|
+
**Analytics** - Wildcard listeners for all `track:*` events
|
|
186
|
+
|
|
187
|
+
**Microservices** - Event choreography with dependency graphs
|
|
188
|
+
|
|
189
|
+
**UI flows** - FSM-driven modals, wizards, and multi-step forms
|
|
190
|
+
|
|
191
|
+
---
|
|
77
192
|
|
|
78
193
|
## License
|
|
79
194
|
|
|
80
|
-
MIT
|
|
195
|
+
[MIT](https://github.com/quazardous/quarkernel/blob/main/LICENSE) - Made by [quazardous](https://github.com/quazardous)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@quazardous/quarkernel",
|
|
3
|
-
"version": "2.2.
|
|
3
|
+
"version": "2.2.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Micro Custom Events Kernel with dependency ordering, shared context, and composite events",
|
|
6
6
|
"author": "quazardous <berliozdavid@gmail.com>",
|
|
@@ -62,6 +62,7 @@
|
|
|
62
62
|
"node": ">=18.0.0"
|
|
63
63
|
},
|
|
64
64
|
"scripts": {
|
|
65
|
+
"prebuild": "cp ../../README.md ./README.md && sed -i 's|(\\./docs/|(https://github.com/quazardous/quarkernel/blob/main/docs/|g; s|(\\./packages/|(https://github.com/quazardous/quarkernel/blob/main/packages/|g; s|(\\./benchmarks/|(https://github.com/quazardous/quarkernel/blob/main/benchmarks/|g; s|(\\./demos/|(https://github.com/quazardous/quarkernel/blob/main/demos/|g; s|(\\./LICENSE)|(https://github.com/quazardous/quarkernel/blob/main/LICENSE)|g' ./README.md",
|
|
65
66
|
"build": "tsup",
|
|
66
67
|
"build:watch": "tsup --watch",
|
|
67
68
|
"test": "vitest run",
|