arvo-core 3.0.20 → 3.0.21

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.
Files changed (2) hide show
  1. package/README.md +34 -151
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,199 +1,83 @@
1
1
  [![SonarCloud](https://sonarcloud.io/images/project_badges/sonarcloud-white.svg)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
2
2
  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
3
3
 
4
+ # Arvo - A toolkit for event driven application (arvo-core)
4
5
 
5
- # Arvo
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, 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
- ## Core Philosophy
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
+ ## What is Arvo Core?
12
9
 
13
- ## Design Goals
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
+ Arvo Core gives you three essential building blocks for event-driven architecture:
15
11
 
12
+ **ArvoEvent** - CloudEvents-compliant event primitives with built-in validation, tracing, and execution cost tracking.
16
13
 
17
- ## The Arvo Framework: Build at Your Own Pace
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
+ **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.
19
15
 
20
- | Scope | NPM | Github | Documentation |
21
- | ------------ | ------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
22
- | Orchestration | https://www.npmjs.com/package/arvo-xstate?activeTab=readme | https://github.com/SaadAhmad123/arvo-xstate | https://saadahmad123.github.io/arvo-xstate/index.html |
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 |
16
+ **ArvoEventFactory** - Contract-bound factories that create validated events with full IntelliSense support and OpenTelemetry integration.
25
17
 
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
- });
18
+ ## Installation
19
+ ```bash
20
+ npm install arvo-core zod@3
51
21
  ```
52
22
 
53
- ### 2. Contracts (ArvoContract)
54
-
55
- ArvoContract defines and enforces agreements between services, ensuring type safety and validation across your distributed system:
56
-
23
+ ## Quick Start
57
24
  ```typescript
58
- import { createArvoContract, z } from 'arvo-core';
25
+ import { createArvoContract, createArvoEventFactory } from 'arvo-core';
26
+ import { z } from 'zod';
59
27
 
28
+ // Define a contract
60
29
  const userContract = createArvoContract({
61
30
  uri: '#/contracts/user',
62
- type: 'user.created',
31
+ type: 'user.create',
63
32
  versions: {
64
33
  '1.0.0': {
65
34
  accepts: z.object({
66
- userId: z.string(),
67
- email: z.string().email()
35
+ email: z.string().email(),
36
+ name: z.string()
68
37
  }),
69
38
  emits: {
70
- 'user.notification.sent': z.object({
39
+ 'evt.user.create.success': z.object({
71
40
  userId: z.string(),
72
- timestamp: z.date()
41
+ timestamp: z.string()
73
42
  })
74
43
  }
75
44
  }
76
45
  }
77
46
  });
78
- ```
79
-
80
- ### 3. Event Factory (ArvoEventFactory)
81
-
82
- ArvoEventFactory provides a type-safe way to create events that conform to your contracts. It handles validation, OpenTelemetry integration, and ensures events meet their contract specifications:
83
47
 
84
- ```typescript
85
- import { createArvoEventFactory } from 'arvo-core';
86
-
87
- // Create a factory for a specific contract version
48
+ // Create events with type safety
88
49
  const factory = createArvoEventFactory(userContract.version('1.0.0'));
89
50
 
90
- // Create an event that accepts input
91
- const inputEvent = factory.accepts({
51
+ const event = factory.accepts({
92
52
  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
53
  data: {
106
- userId: 'usr_123',
107
- timestamp: new Date()
54
+ email: 'user@example.com',
55
+ name: 'John Doe'
108
56
  }
109
57
  });
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
- ```
118
-
119
- ## Installation
120
-
121
- ```bash
122
- # Using npm
123
- npm install arvo-core
124
-
125
- # Using yarn
126
- yarn add arvo-core
127
58
  ```
128
59
 
129
- ## Advanced Usage
130
-
131
- ### Working with Contract Versions
132
-
133
- The versioning system in ArvoContract allows you to evolve your APIs while maintaining compatibility:
134
-
135
- ```typescript
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
- ```
60
+ ## Why Arvo?
165
61
 
166
- ## Integration with Other Arvo Components
62
+ 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.
167
63
 
168
- Arvo Core works seamlessly with:
169
- - arvo-event-handler: For processing events
170
- - arvo-xstate: For orchestration and workflow management
64
+ 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.
171
65
 
172
- Each component builds upon these core primitives while maintaining the same principles of flexibility and reliability.
66
+ ## What is `arvo-core`?
173
67
 
174
- ## Best Practices
68
+ 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.
175
69
 
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
70
+ Learn more at the official Arvo website: [https://www.arvo.land/](https://www.arvo.land/)
181
71
 
182
- ## Resources
72
+ ## Documentation
183
73
 
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 |
74
+ Complete guides, API reference, and tutorials at [https://www.arvo.land/](https://www.arvo.land/)
189
75
 
190
76
  ## License
191
77
 
192
- This package is available under the MIT License. For more details, refer to the [LICENSE.md](LICENSE.md) file in the project repository.
193
-
194
- ## Change Logs
78
+ MIT - See [LICENSE.md](LICENSE.md)
195
79
 
196
- For a detailed list of changes and updates, please refer to the [document](CHANGELOG.md) file.
80
+ ---
197
81
 
198
82
  ### SonarCloud Metrics
199
83
 
@@ -207,5 +91,4 @@ For a detailed list of changes and updates, please refer to the [document](CHANG
207
91
  [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
208
92
  [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
209
93
  [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
210
- [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=SaadAhmad123_arvo-core)
211
-
94
+ [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=SaadAhmad123_arvo-core&metric=vulnerabilities)](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.20",
3
+ "version": "3.0.21",
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": {