@openverb/runtime 2.0.0-alpha.4 → 2.0.0-alpha.6
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 +144 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# @openverb/runtime
|
|
2
|
+
|
|
3
|
+
The execution runtime for the OpenVerb Framework - a verb-driven application architecture.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
```bash
|
|
7
|
+
npm install @openverb/runtime
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Quick Start
|
|
11
|
+
```typescript
|
|
12
|
+
import { createRuntime, loadVerbs } from '@openverb/runtime'
|
|
13
|
+
|
|
14
|
+
// Load verb definitions
|
|
15
|
+
const verbs = loadVerbs('./verbs')
|
|
16
|
+
|
|
17
|
+
// Create runtime
|
|
18
|
+
const runtime = createRuntime({
|
|
19
|
+
verbs,
|
|
20
|
+
handlers: {
|
|
21
|
+
'handlers/example': async (ctx, args) => {
|
|
22
|
+
return { success: true, data: args }
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
adapters: {
|
|
26
|
+
db: myDatabaseAdapter,
|
|
27
|
+
logger: console
|
|
28
|
+
}
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
// Execute a verb
|
|
32
|
+
const result = await runtime.execute({
|
|
33
|
+
verbId: 'example.action',
|
|
34
|
+
args: { name: 'test' },
|
|
35
|
+
actor: { type: 'user', id: 'user-123' },
|
|
36
|
+
context: {
|
|
37
|
+
tenantId: 'tenant-1',
|
|
38
|
+
planId: 'free',
|
|
39
|
+
env: 'production',
|
|
40
|
+
requestId: crypto.randomUUID()
|
|
41
|
+
}
|
|
42
|
+
})
|
|
43
|
+
|
|
44
|
+
console.log(result)
|
|
45
|
+
// {
|
|
46
|
+
// ok: true,
|
|
47
|
+
// result: { success: true, data: { name: 'test' } },
|
|
48
|
+
// receipt: { ... },
|
|
49
|
+
// events: [ ... ]
|
|
50
|
+
// }
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Core Concepts
|
|
54
|
+
|
|
55
|
+
### Verbs
|
|
56
|
+
Verbs are JSON definitions that describe actions in your application:
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"id": "user.create",
|
|
60
|
+
"version": "1.0.0",
|
|
61
|
+
"summary": "Create a new user",
|
|
62
|
+
"inputSchema": { "type": "object", "properties": { ... } },
|
|
63
|
+
"outputSchema": { "type": "object", "properties": { ... } },
|
|
64
|
+
"effects": ["db.write", "email.send"],
|
|
65
|
+
"handler": "handlers/user/create"
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Handlers
|
|
70
|
+
Handler functions implement the business logic:
|
|
71
|
+
```typescript
|
|
72
|
+
import type { HandlerContext } from '@openverb/runtime'
|
|
73
|
+
|
|
74
|
+
export async function handler(
|
|
75
|
+
ctx: HandlerContext,
|
|
76
|
+
args: { email: string; name: string }
|
|
77
|
+
) {
|
|
78
|
+
// Access adapters
|
|
79
|
+
await ctx.adapters.db.insert('users', { email: args.email })
|
|
80
|
+
|
|
81
|
+
// Emit events
|
|
82
|
+
ctx.emitEvent({ type: 'user.created', data: { email: args.email } })
|
|
83
|
+
|
|
84
|
+
return { userId: '123', email: args.email }
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Adapters
|
|
89
|
+
Adapters provide access to external services:
|
|
90
|
+
```typescript
|
|
91
|
+
const adapters = {
|
|
92
|
+
db: {
|
|
93
|
+
insert: async (table, data) => { /* ... */ },
|
|
94
|
+
query: async (sql, params) => { /* ... */ }
|
|
95
|
+
},
|
|
96
|
+
logger: console,
|
|
97
|
+
email: emailService
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## API Reference
|
|
102
|
+
|
|
103
|
+
### `createRuntime(config)`
|
|
104
|
+
|
|
105
|
+
Creates a new runtime instance.
|
|
106
|
+
|
|
107
|
+
**Parameters:**
|
|
108
|
+
- `config.verbs` - Array of verb definitions
|
|
109
|
+
- `config.handlers` - Map of handler functions
|
|
110
|
+
- `config.adapters` - External service adapters
|
|
111
|
+
- `config.policy?` - Optional policy engine
|
|
112
|
+
|
|
113
|
+
**Returns:** Runtime instance
|
|
114
|
+
|
|
115
|
+
### `loadVerbs(directory)`
|
|
116
|
+
|
|
117
|
+
Loads verb definitions from a directory.
|
|
118
|
+
|
|
119
|
+
**Parameters:**
|
|
120
|
+
- `directory` - Path to directory containing `.json` verb files
|
|
121
|
+
|
|
122
|
+
**Returns:** Array of verb definitions
|
|
123
|
+
|
|
124
|
+
### `runtime.execute(request)`
|
|
125
|
+
|
|
126
|
+
Executes a verb.
|
|
127
|
+
|
|
128
|
+
**Parameters:**
|
|
129
|
+
- `request.verbId` - ID of verb to execute
|
|
130
|
+
- `request.args` - Arguments for the verb
|
|
131
|
+
- `request.actor` - User/system making the request
|
|
132
|
+
- `request.context` - Execution context (tenant, plan, etc.)
|
|
133
|
+
|
|
134
|
+
**Returns:** `ExecuteResponse` with result, receipt, and events
|
|
135
|
+
|
|
136
|
+
## Related Packages
|
|
137
|
+
|
|
138
|
+
- [@openverb/policy](https://www.npmjs.com/package/@openverb/policy) - Policy engine for authorization
|
|
139
|
+
- [@openverb/sdk](https://www.npmjs.com/package/@openverb/sdk) - Client SDK with React hooks
|
|
140
|
+
- [@openverb/cli](https://www.npmjs.com/package/@openverb/cli) - CLI tools for developers
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
MIT
|