arvo-core 3.0.20 → 3.0.22
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 +33 -152
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,199 +1,81 @@
|
|
|
1
1
|
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
2
2
|
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
3
3
|
|
|
4
|
+
# Arvo - A toolkit for event driven applications (arvo-core)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
In the landscape of event-driven systems, Arvo attempts to stand apart through its unique approach to complexity. Rather than prescribing rigid solutions, Arvo provides a thoughtful pattern language and methodology for building distributed systems. It achieves this by striking a careful balance between structure and freedom, offering strong conventions while remaining deliberately unopinionated about implementation details.
|
|
6
|
+
The foundational package of, [Arvo](https://www.arvo.land/), a TypeScript toolkit for building event-driven applications that are distributed system-compliant. Arvo Core provides CloudEvents-compliant event primitives, type-safe contract validation, and OpenTelemetry observability without infrastructure lock-in.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
Arvo's fundamental principle is that distributed systems thrive on trust and clear contracts, yet must remain flexible in their technical implementation. While the framework ensures reliability and type safety across service boundaries through these contracts, it consciously avoids dictating how you should implement core functionalities like security, event brokerage, event handling, telemetry, or workflow orchestration. This approach enables seamless integration with your existing infrastructure and tools, whether you're using cloud providers like AWS and Azure or your own on-premise solutions.
|
|
10
|
-
Understanding that teams shouldn't need to reinvent common patterns, Arvo provides thoughtfully designed tools to reduce implementation complexity. The Arvo suite includes libraries like arvo-xstate for workflow orchestration using state machines and arvo-event-handler for implementing contract-based event handlers. However, these tools remain entirely optional – they exist to accelerate development when they align with your needs, but Arvo fully supports teams who choose different approaches that better suit their specific requirements.
|
|
11
|
-
This philosophy particularly benefits teams focusing on business logic who want to avoid rebuilding fundamental event-driven patterns. By providing essential building blocks for event creation, contract validation, state management, and telemetry, while maintaining cloud agnosticism and extensibility, Arvo reduces the complexity of distributed system development without constraining technical choices.
|
|
8
|
+
This package gives you three essential building blocks for event-driven architecture:
|
|
12
9
|
|
|
13
|
-
|
|
14
|
-
Arvo addresses the inherent complexity of distributed systems by establishing clear patterns for event handling, state management, and service communication. Instead of enforcing a rigid framework, it provides a flexible foundation that helps teams reduce cognitive load while preserving their ability to innovate and adapt. This approach ensures that whether you're building a small microservice or orchestrating a large-scale distributed system, Arvo's lightweight core and extensible architecture can grow alongside your needs, allowing you to progressively adopt more sophisticated patterns as your system evolves.
|
|
10
|
+
**ArvoEvent** - CloudEvents-compliant event primitives with built-in validation, tracing, and execution cost tracking.
|
|
15
11
|
|
|
12
|
+
**ArvoContract** - Type-safe service interfaces with semantic versioning. Define what events your services accept and emit with automatic runtime validation and compile-time type inference.
|
|
16
13
|
|
|
17
|
-
|
|
18
|
-
The Arvo framework provides a cohesive set of libraries for building event-driven systems. While designed to work together seamlessly, each component remains independent - adopt what serves your needs and integrate at your own pace.
|
|
14
|
+
**ArvoEventFactory** - Contract-bound factories that create validated events with full IntelliSense support and OpenTelemetry integration.
|
|
19
15
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
| Core | https://www.npmjs.com/package/arvo-core?activeTab=readme | https://github.com/SaadAhmad123/arvo-core | https://saadahmad123.github.io/arvo-core/index.html |
|
|
24
|
-
| Event Handling | https://www.npmjs.com/package/arvo-event-handler?activeTab=readme | https://github.com/SaadAhmad123/arvo-event-handler | https://saadahmad123.github.io/arvo-event-handler/index.html |
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
# Arvo - Core
|
|
28
|
-
|
|
29
|
-
Arvo Core provides the foundational building blocks for creating robust event-driven systems. It implements industry standards while adding enterprise-grade features, enabling developers to build reliable distributed systems without sacrificing flexibility or introducing vendor lock-in.
|
|
30
|
-
|
|
31
|
-
## Core Concepts
|
|
32
|
-
|
|
33
|
-
Understanding Arvo Core begins with its three fundamental components that work together to create a robust event-driven architecture:
|
|
34
|
-
|
|
35
|
-
### 1. Events (ArvoEvent)
|
|
36
|
-
|
|
37
|
-
ArvoEvent extends the CloudEvents specification to provide a standardized way to describe events in your system. Every event is an immutable, validated instance that includes:
|
|
38
|
-
|
|
39
|
-
```typescript
|
|
40
|
-
import { createArvoEvent } from 'arvo-core';
|
|
41
|
-
|
|
42
|
-
const event = createArvoEvent({
|
|
43
|
-
source: 'user-service',
|
|
44
|
-
type: 'user.created',
|
|
45
|
-
subject: 'user/123',
|
|
46
|
-
data: {
|
|
47
|
-
userId: 'usr_123',
|
|
48
|
-
email: 'user@example.com'
|
|
49
|
-
}
|
|
50
|
-
});
|
|
16
|
+
## Installation
|
|
17
|
+
```bash
|
|
18
|
+
npm install arvo-core zod@3
|
|
51
19
|
```
|
|
52
20
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
ArvoContract defines and enforces agreements between services, ensuring type safety and validation across your distributed system:
|
|
56
|
-
|
|
21
|
+
## Quick Start
|
|
57
22
|
```typescript
|
|
58
|
-
import { createArvoContract,
|
|
23
|
+
import { createArvoContract, createArvoEventFactory } from 'arvo-core';
|
|
24
|
+
import { z } from 'zod';
|
|
59
25
|
|
|
26
|
+
// Define a contract
|
|
60
27
|
const userContract = createArvoContract({
|
|
61
28
|
uri: '#/contracts/user',
|
|
62
|
-
type: 'user.
|
|
29
|
+
type: 'user.create',
|
|
63
30
|
versions: {
|
|
64
31
|
'1.0.0': {
|
|
65
32
|
accepts: z.object({
|
|
66
|
-
|
|
67
|
-
|
|
33
|
+
email: z.string().email(),
|
|
34
|
+
name: z.string()
|
|
68
35
|
}),
|
|
69
36
|
emits: {
|
|
70
|
-
'user.
|
|
37
|
+
'evt.user.create.success': z.object({
|
|
71
38
|
userId: z.string(),
|
|
72
|
-
timestamp: z.
|
|
39
|
+
timestamp: z.string()
|
|
73
40
|
})
|
|
74
41
|
}
|
|
75
42
|
}
|
|
76
43
|
}
|
|
77
44
|
});
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### 3. Event Factory (ArvoEventFactory)
|
|
81
45
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
```typescript
|
|
85
|
-
import { createArvoEventFactory } from 'arvo-core';
|
|
86
|
-
|
|
87
|
-
// Create a factory for a specific contract version
|
|
46
|
+
// Create events with type safety
|
|
88
47
|
const factory = createArvoEventFactory(userContract.version('1.0.0'));
|
|
89
48
|
|
|
90
|
-
|
|
91
|
-
const inputEvent = factory.accepts({
|
|
49
|
+
const event = factory.accepts({
|
|
92
50
|
source: 'api/users',
|
|
93
|
-
subject: 'user/creation',
|
|
94
|
-
data: {
|
|
95
|
-
userId: 'usr_123',
|
|
96
|
-
email: 'user@example.com'
|
|
97
|
-
}
|
|
98
|
-
});
|
|
99
|
-
|
|
100
|
-
// Create an event that emits output
|
|
101
|
-
const outputEvent = factory.emits({
|
|
102
|
-
type: 'user.notification.sent',
|
|
103
|
-
source: 'notification-service',
|
|
104
|
-
subject: 'notification/sent',
|
|
105
51
|
data: {
|
|
106
|
-
|
|
107
|
-
|
|
52
|
+
email: 'user@example.com',
|
|
53
|
+
name: 'John Doe'
|
|
108
54
|
}
|
|
109
55
|
});
|
|
110
|
-
|
|
111
|
-
// Create a system error event
|
|
112
|
-
const errorEvent = factory.systemError({
|
|
113
|
-
error: new Error('Validation failed'),
|
|
114
|
-
source: 'validation-service',
|
|
115
|
-
subject: 'validation/error'
|
|
116
|
-
});
|
|
117
56
|
```
|
|
118
57
|
|
|
119
|
-
##
|
|
58
|
+
## Why Arvo?
|
|
120
59
|
|
|
121
|
-
|
|
122
|
-
# Using npm
|
|
123
|
-
npm install arvo-core
|
|
60
|
+
Arvo abstracts infrastructure concerns from your business logic. Write application code once and deploy it anywhere - Node.js servers, serverless functions, browsers, or distributed clusters. Your business logic encapsulated in event handlers and contracts remain unchanged while you swap infrastructure integrations.
|
|
124
61
|
|
|
125
|
-
|
|
126
|
-
yarn add arvo-core
|
|
127
|
-
```
|
|
62
|
+
The same primitives work for simple request-response services, complex multi-service workflows, AI agent systems, and everything in between. No framework lock-in, no mandatory infrastructure, just clean event-driven code that integrates with your existing stack.
|
|
128
63
|
|
|
129
|
-
##
|
|
64
|
+
## What is `arvo-core`?
|
|
130
65
|
|
|
131
|
-
|
|
66
|
+
The `arvo-core` is one of the two foundational packages in the Arvo ecosystem, alongside `arvo-event-handler`. Together, they provide the complete foundation for building event-driven applications that are distributed system-compliant. Explore additional tools and integrations in the `@arvo-tools` namespace.
|
|
132
67
|
|
|
133
|
-
|
|
68
|
+
Learn more at the official Arvo website: [https://www.arvo.land/](https://www.arvo.land/)
|
|
134
69
|
|
|
135
|
-
|
|
136
|
-
const versionedContract = createArvoContract({
|
|
137
|
-
uri: '#/contracts/order',
|
|
138
|
-
type: 'order.process',
|
|
139
|
-
versions: {
|
|
140
|
-
'1.0.0': {
|
|
141
|
-
accepts: z.object({ orderId: z.string() }),
|
|
142
|
-
emits: {
|
|
143
|
-
'order.processed': z.object({ status: z.string() })
|
|
144
|
-
}
|
|
145
|
-
},
|
|
146
|
-
'2.0.0': {
|
|
147
|
-
accepts: z.object({
|
|
148
|
-
orderId: z.string(),
|
|
149
|
-
metadata: z.record(z.string())
|
|
150
|
-
}),
|
|
151
|
-
emits: {
|
|
152
|
-
'order.processed': z.object({
|
|
153
|
-
status: z.string(),
|
|
154
|
-
metrics: z.object({ duration: z.number() })
|
|
155
|
-
})
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
});
|
|
160
|
-
|
|
161
|
-
// Create version-specific factories
|
|
162
|
-
const v1Factory = createArvoEventFactory(versionedContract.version('1.0.0'));
|
|
163
|
-
const v2Factory = createArvoEventFactory(versionedContract.version('2.0.0'));
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
## Integration with Other Arvo Components
|
|
167
|
-
|
|
168
|
-
Arvo Core works seamlessly with:
|
|
169
|
-
- arvo-event-handler: For processing events
|
|
170
|
-
- arvo-xstate: For orchestration and workflow management
|
|
70
|
+
## Documentation
|
|
171
71
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
## Best Practices
|
|
175
|
-
|
|
176
|
-
1. Use factories for event creation to ensure contract compliance
|
|
177
|
-
2. Implement proper error handling using the standard error schema
|
|
178
|
-
3. Enable distributed tracing in production systems
|
|
179
|
-
4. Share contracts as separate packages or monorepo internals
|
|
180
|
-
5. Utilize version-specific factories for different API versions
|
|
181
|
-
|
|
182
|
-
## Resources
|
|
183
|
-
|
|
184
|
-
| Resource | Link |
|
|
185
|
-
|--------------|-------------------------------------------------------------|
|
|
186
|
-
| Documentation | https://saadahmad123.github.io/arvo-core/index.html |
|
|
187
|
-
| GitHub | https://github.com/SaadAhmad123/arvo-core |
|
|
188
|
-
| NPM Package | https://www.npmjs.com/package/arvo-core |
|
|
72
|
+
Complete guides, API reference, and tutorials at [https://www.arvo.land/](https://www.arvo.land/)
|
|
189
73
|
|
|
190
74
|
## License
|
|
191
75
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
## Change Logs
|
|
76
|
+
MIT - See [LICENSE.md](LICENSE.md)
|
|
195
77
|
|
|
196
|
-
|
|
78
|
+
---
|
|
197
79
|
|
|
198
80
|
### SonarCloud Metrics
|
|
199
81
|
|
|
@@ -207,5 +89,4 @@ For a detailed list of changes and updates, please refer to the [document](CHANG
|
|
|
207
89
|
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
208
90
|
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
209
91
|
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
210
|
-
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
|
211
|
-
|
|
92
|
+
[](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "arvo-core",
|
|
3
|
-
"version": "3.0.
|
|
3
|
+
"version": "3.0.22",
|
|
4
4
|
"main": "dist/index.js",
|
|
5
5
|
"description": "The core Arvo package which provides application tier core primitives and contract system for building production-grade event-driven application. Provides ArvoEvent (CloudEvents-compliant), ArvoContract for type-safe service interfaces, event factories, OpenTelemetry integration, and orchestration utilities - enabling infrastructure-agnostic, composable, and observable distributed systems-compliant applications.",
|
|
6
6
|
"repository": {
|