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

# 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

Result Pattern

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

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

async function fetchUser(id: string): Promise<Result<User>> {
    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);
}

Resilience Pipeline

Compose fault-tolerance patterns for production-ready operations:

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/:

Available Provider Categories

| 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 |

Sample Manifest Structure

{
    "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

Building from Source

# 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

Running Tests

# From repository root
cd Ark.Alliance.TypeScript.Core.Tests
npm install
npm test

# With coverage
npm run test:coverage

Available Scripts

| 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.