@nwire/forge 0.7.0 → 0.7.1
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 +67 -40
- package/package.json +13 -11
package/README.md
CHANGED
|
@@ -1,77 +1,104 @@
|
|
|
1
1
|
# @nwire/forge
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> The framework's domain primitives — one import for actions, actors, events, workflows, projections, modules, and the runtime that ties them together.
|
|
4
4
|
|
|
5
5
|
## What it does
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Provides the `define*` surface that domain code uses every day, plus the
|
|
8
|
+
runtime that fires them. Forge composes lower packages (`@nwire/messages`,
|
|
9
|
+
`@nwire/handler`, `@nwire/app`) into one ergonomic API; you can also use
|
|
10
|
+
the lower packages directly when you want a narrower surface.
|
|
8
11
|
|
|
9
12
|
## Install
|
|
10
13
|
|
|
11
14
|
```bash
|
|
12
|
-
pnpm add @nwire/forge
|
|
15
|
+
pnpm add @nwire/forge zod
|
|
13
16
|
```
|
|
14
17
|
|
|
15
18
|
## Quick start
|
|
16
19
|
|
|
17
20
|
```ts
|
|
18
21
|
import { z } from "zod";
|
|
19
|
-
import {
|
|
22
|
+
import { defineEvent } from "@nwire/messages";
|
|
23
|
+
import { defineAction, defineActor, defineModule, createApp } from "@nwire/forge";
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
// 1. A past-tense fact the domain cares about.
|
|
26
|
+
export const StudentWasEnrolled = defineEvent({
|
|
27
|
+
name: "enrollments.student-was-enrolled",
|
|
22
28
|
schema: z.object({ studentId: z.string(), courseId: z.string() }),
|
|
23
|
-
})
|
|
29
|
+
});
|
|
24
30
|
|
|
25
|
-
|
|
26
|
-
|
|
31
|
+
// 2. An aggregate that holds state + invariants.
|
|
32
|
+
export const Student = defineActor("Student", {
|
|
33
|
+
schema: z.object({
|
|
34
|
+
studentId: z.string(),
|
|
35
|
+
enrolments: z.array(z.string()),
|
|
36
|
+
}),
|
|
37
|
+
initial: (id: string) => ({ studentId: id, enrolments: [] }),
|
|
27
38
|
methods: {
|
|
28
39
|
enrol(state, courseId: string) {
|
|
40
|
+
if (state.enrolments.includes(courseId)) return state;
|
|
29
41
|
return { ...state, enrolments: [...state.enrolments, courseId] };
|
|
30
42
|
},
|
|
31
43
|
},
|
|
32
44
|
});
|
|
33
45
|
|
|
34
|
-
|
|
35
|
-
|
|
46
|
+
// 3. A user-visible command that emits the event.
|
|
47
|
+
export const enrolStudent = defineAction({
|
|
48
|
+
name: "enrollments.enrol-student",
|
|
49
|
+
schema: z.object({ studentId: z.string(), courseId: z.string() }),
|
|
36
50
|
emits: [StudentWasEnrolled],
|
|
37
|
-
handler: async (
|
|
51
|
+
handler: async (input, { use }) => {
|
|
38
52
|
const student = await use(Student, input.studentId);
|
|
39
53
|
student.enrol(input.courseId);
|
|
40
|
-
|
|
54
|
+
return StudentWasEnrolled({
|
|
55
|
+
studentId: input.studentId,
|
|
56
|
+
courseId: input.courseId,
|
|
57
|
+
});
|
|
41
58
|
},
|
|
42
|
-
})
|
|
59
|
+
});
|
|
43
60
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
actions: [enrolStudent],
|
|
61
|
+
// 4. A module bundles the bounded context.
|
|
62
|
+
export const enrollmentsModule = defineModule("enrollments", {
|
|
47
63
|
events: [StudentWasEnrolled],
|
|
64
|
+
actors: [Student],
|
|
65
|
+
actions: [enrolStudent.public()],
|
|
48
66
|
});
|
|
49
67
|
|
|
50
|
-
|
|
68
|
+
// 5. createApp wires the modules into a runnable app.
|
|
69
|
+
export const app = createApp({ modules: [enrollmentsModule] });
|
|
70
|
+
await app.start();
|
|
71
|
+
await app.runtime.dispatch(enrolStudent, { studentId: "avi", courseId: "heb-1" });
|
|
51
72
|
```
|
|
52
73
|
|
|
53
74
|
## API surface
|
|
54
75
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
-
|
|
58
|
-
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
76
|
+
| Primitive | Purpose |
|
|
77
|
+
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
78
|
+
| `defineAction` | User-visible command — validated input, emits events |
|
|
79
|
+
| `defineEvent` | Past-tense fact (re-exported from `@nwire/messages`) |
|
|
80
|
+
| `defineHandler` | Operation primitive — transport-agnostic |
|
|
81
|
+
| `defineActor` | Aggregate with state, methods, optional state machine |
|
|
82
|
+
| `defineSchema` | Data shape + lifecycle states + storage hints |
|
|
83
|
+
| `defineProjection` | Read-model fold over events |
|
|
84
|
+
| `defineQuery` | Projection-backed read function |
|
|
85
|
+
| `defineWorkflow` | Reaction + saga unified — stateful or stateless |
|
|
86
|
+
| `defineModule` | Bundle of actors + actions + events + projections + queries |
|
|
87
|
+
| `defineApp` | App declaration (multi-wire instantiation) |
|
|
88
|
+
| `createApp` | App runtime — boots modules, owns the bus |
|
|
89
|
+
| `definePlugin` | Cross-cutting: provide bindings, hook lifecycle, intercept dispatch |
|
|
90
|
+
| `defineResource` | Public response shape (field allowlist + OpenAPI schema) |
|
|
91
|
+
| `defineError` | Typed throwable with status code |
|
|
92
|
+
| `defineMiddleware` | Reusable handler middleware step |
|
|
93
|
+
| `defineCron`, `defineInbox`, `defineOutbox`, `defineExternalCall`, `defineInboundWebhook` | Orchestrator primitives |
|
|
94
|
+
| `runCli(app, argv)` | Argv dispatcher — operator CLI without HTTP |
|
|
95
|
+
|
|
96
|
+
Forge also re-exports `MessageEnvelope`, `seedEnvelope`, `deriveEnvelope`
|
|
97
|
+
from `@nwire/envelope` and the `Logger` contract from `@nwire/logger`.
|
|
98
|
+
|
|
99
|
+
## When to use forge
|
|
100
|
+
|
|
101
|
+
When you want the full framework DX in one import. If you only need typed
|
|
102
|
+
handlers without the actor/event machinery, pull `@nwire/handler` instead;
|
|
103
|
+
if you only need lifecycle + plugins, pull `@nwire/app`. Forge is the
|
|
104
|
+
default for app code; the smaller packages are the standalone path.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nwire/forge",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Nwire — the framework's core primitives. defineAction, defineEvent, defineHandler, defineActor, defineProjection, defineQuery, defineWorkflow, defineModule, defineApp, definePlugin, createApp. MessageEnvelope with correlation/causation. The runtime is the bus.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"actions",
|
|
@@ -11,9 +11,11 @@
|
|
|
11
11
|
"framework",
|
|
12
12
|
"nwire"
|
|
13
13
|
],
|
|
14
|
+
"license": "MIT",
|
|
14
15
|
"files": [
|
|
15
16
|
"dist",
|
|
16
|
-
"README.md"
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
17
19
|
],
|
|
18
20
|
"type": "module",
|
|
19
21
|
"main": "./dist/foundation.js",
|
|
@@ -32,15 +34,15 @@
|
|
|
32
34
|
"emittery": "1.0.1",
|
|
33
35
|
"koa": "^2.16.4",
|
|
34
36
|
"zod": "^4.0.0",
|
|
35
|
-
"@nwire/container": "0.7.
|
|
36
|
-
"@nwire/envelope": "0.7.
|
|
37
|
-
"@nwire/
|
|
38
|
-
"@nwire/bus": "0.7.
|
|
39
|
-
"@nwire/
|
|
40
|
-
"@nwire/interface": "0.7.
|
|
41
|
-
"@nwire/dead-letter": "0.7.
|
|
42
|
-
"@nwire/app": "0.7.
|
|
43
|
-
"@nwire/messages": "0.7.
|
|
37
|
+
"@nwire/container": "0.7.1",
|
|
38
|
+
"@nwire/envelope": "0.7.1",
|
|
39
|
+
"@nwire/logger": "0.7.1",
|
|
40
|
+
"@nwire/bus": "0.7.1",
|
|
41
|
+
"@nwire/handler": "0.7.1",
|
|
42
|
+
"@nwire/interface": "0.7.1",
|
|
43
|
+
"@nwire/dead-letter": "0.7.1",
|
|
44
|
+
"@nwire/app": "0.7.1",
|
|
45
|
+
"@nwire/messages": "0.7.1"
|
|
44
46
|
},
|
|
45
47
|
"devDependencies": {
|
|
46
48
|
"@types/koa": "^2.15.0",
|