ark-alliance-core

Universal, extensible, and production-ready TypeScript/Node.js core foundation

---

Overview

ark-alliance-core provides battle-tested patterns for building resilient, maintainable backend applications. Built on Clean Architecture and DDD principles with zero mandatory dependencies.

| Principle | Description |
|-----------|-------------|
| Zero Mandatory Dependencies | Core features work with pure TypeScript/Node.js |
| Railway-Oriented Programming | Errors are values, not exceptions |
| Resilience by Default | Built-in circuit breaker, retry, timeout, bulkhead |
| Observability-Ready | Correlation IDs, structured logging, tracing |
| Provider Abstraction | Manifest-driven external service integration |

---

Table of Contents

- Installation
- Quick Start
- Module Reference
- Provider Configuration
- Development
- License

---

Quick Links

| Resource | Link |
|----------|------|
| Root README | Ark.Alliance.Core |
| Math Library | Ark.Alliance.TypeScript.Core.Math |
| Core Tests | Ark.Alliance.TypeScript.Core.Tests |
| Math Tests | Ark.Alliance.TypeScript.Core.Math.Test |
| Contributing | CONTRIBUTING.md |
| Changelog | CHANGELOG.md |

Installation

``bash

npm

npm install ark-alliance-core

yarn

yarn add ark-alliance-core

pnpm

pnpm add ark-alliance-core
`

---

Module Reference

Usage examples and detailed API documentation for each module.

| Module | Schema/Layer | Description | Documentation |
| :--- | :--- | :--- | :--- |
| Auth | src/core/auth | RBAC, JWT tokens, and multi-provider authentication. | 📖 Read |
| Billing | src/core/billing | Billing types, intervals, and invoice state management. | 📖 Read |
| Identity | src/core/identity | User entities, credentials, and session management. | 📖 Read |
| Notification | src/core/notification | Multi-channel notification service abstraction. | 📖 Read |
| Payments | src/core/payments | Payment orchestration, providers (PayPal, Crypto), and gateways. | 📖 Read |
| Result | src/core/result | Railway-oriented programming pattern for error handling. | 📖 Read |
| Services | src/core/services | Base service classes and lifecycle management. | 📖 Read |
| Subscriptions | src/core/subscriptions | Plan management, entitlements, and usage tracking. | 📖 Read |
| Data | src/infrastructure/data | Database-agnostic persistence, repositories, and migrations. | 📖 Read |
| Billing Infra | src/infrastructure/billing | Billing persistence and invoicing logic. | 📖 Read |
| Payments Infra | src/infrastructure/payments | Payment persistence and session management. | 📖 Read |
| Resilience | src/infrastructure/resilience | Circuit breakers, retries, bulkheads, and timeouts. | 📖 Read |
| Providers | src/infrastructure/providers | Manifest-driven external service integration. | 📖 Read |
| HTTP | src/infrastructure/http | Resilient HTTP client with typed responses. | 📖 Read |
| Logging | src/infrastructure/logging | Structured logging with multiple transports. | 📖 Read |
| Cache | src/infrastructure/cache | Concurrent in-memory caching with eviction policies. | 📖 Read |
| Concurrency | src/infrastructure/concurrency | Async locks, semaphores, and synchronization primitives. | 📖 Read |
| Security | src/infrastructure/security | Cryptographic utilities, hashing, and signatures. | 📖 Read |
| Expression | src/infrastructure/expression | Universal expression evaluation engine. | 📖 Read |
| Controllers | src/controllers | Request handling, middleware, and rate limiting. | 📖 Read |
| Domain | src/domain | DDD base classes, entities, and domain events. | 📖 Read |
| Shared | src/shared | Common utilities, enums, and constants. | 📖 Read |

---

Quick Start

$3

Type-safe success/failure handling with railway-oriented programming:

`typescript
import { Result } from 'ark-alliance-core';

async function fetchUser(id: string): Promise> {
try {
const user = await db.users.findById(id);
if (!user) {
return Result.NotFound.withReason(User ${id} not found);
}
return Result.ok(user);
} catch (error) {
return Result.fromError(error);
}
}

// Chain operations with automatic error propagation
const result = await fetchUser('123')
.flatMap(user => validateUser(user))
.flatMap(user => enrichUserProfile(user));

if (result.isSuccess) {
console.log('User:', result.data);
} else {
console.error('Error:', result.error);
}
`

$3

Compose fault-tolerance patterns for production-ready operations:

`typescript
import { ResiliencePipeline } from 'ark-alliance-core';

const pipeline = ResiliencePipeline.create()
.withTimeout({ timeoutMs: 5000 })
.withRetry({ maxAttempts: 3, useExponentialBackoff: true })
.withCircuitBreaker({ failureThreshold: 5 })
.withBulkhead({ maxConcurrency: 10 });

const result = await pipeline.execute(() => httpClient.get('/api/data'));
`

---

Provider Configuration

The Providers module uses JSON manifests for declarative configuration. Located in src/infrastructure/providers/JsonProvidersConfiguration/:

$3

| Category | Providers |
|----------|-----------|
| Brokers | RabbitMQ, Kafka, IBM MQ, ZeroMQ |
| Git | GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, HuggingFace |
| Storage | Azure Blob Storage |
| Notifications | Twilio, SendGrid, Firebase FCM, Telegram, Signal |
| Hardware | Camera, Microphone, Geolocation, Accelerometer, Gamepad |
| Protocols | SFTP, MQTT |

$3

`json
{
"id": "git-github",
"name": "GitHub",
"type": "git",
"connection": {
"baseUrl": "https://api.github.com",
"timeout": 30000
},
"authentication": {
"methods": [
{ "type": "pat", "required": ["token"] },
{ "type": "oauth", "required": ["clientId", "clientSecret"] }
]
},
"resilience": {
"retry": { "enabled": true, "maxAttempts": 3 },
"circuitBreaker": { "enabled": true, "failureThreshold": 5 }
},
"mappings": {
"enums": [{ "enumName": "PullRequestState", "entries": [...] }]
}
}
`

---

Development

$3

`bash

Clone repository

git clone https://github.com/M2H-Machine-to-Human-Race/Ark.Alliance.Core.git
cd Ark.Alliance.Core/Ark.Alliance.TypeScript.Core

Install dependencies

npm install

Build

npm run build

Type check

npm run typecheck

Lint

npm run lint
`

$3

`bash

From repository root

cd Ark.Alliance.TypeScript.Core.Tests
npm install
npm test

With coverage

npm run test:coverage
`

$3

| Command | Description |
|---------|-------------|
| npm run build | Build library (ESM + CJS + DTS) |
| npm run dev | Watch mode for development |
| npm run lint | Run ESLint |
| npm run lint:fix | Fix ESLint issues |
| npm run typecheck | TypeScript type checking |
| npm run format` | Format code with Prettier |

---

License

MIT License - see LICENSE for details.

---

_{M2H.IO (c) 2025 - Ark.Alliance Ecosystem - Armand Richelet-Kleinberg}