@folksdo/shared-lib

Here is your updated, polished, and production-grade README.md with enhanced clarity, formatting consistency, and alignment with your architecture and tooling (e.g. tsc-alias, tsconfig.paths.json, etc.).

# @folksdo/shared-lib

**Shared Infrastructure Library for Microservices**

A reusable, composable set of modules designed to standardize common patterns across all microservices in a distributed architecture. Published as an NPM package, this library includes:

- **bus**: Event bus interfaces and implementations (e.g. RabbitMQ)
- **domain**: Core domain types, entities, and event structures
- **eventstore**: Interfaces and implementations for event sourcing (Mongo, in-memory)
- **exceptions**: Standardized error classes for consistent exception handling
- **repositories**: Generic repository interfaces and in-memory/DB adapters
- **utils**: Utilities for logging, configuration, health checks, and more

---

## 📦 Installation

```bash
npm install @folksdo/shared-lib
# or
yarn add @folksdo/shared-lib
```

⚡️ Quick Start

import {
  RabbitMQEventBus,
  MongoDBEventStore,
  NotFoundException,
  InMemoryRepository,
  logger,
  healthCheck,
} from '@folksdo/shared-lib';

🧩 Modules Overview

Module	Exports	Description
bus	IEventBus, RabbitMQEventBus, InMemoryEventBus	Abstract event bus interface + concrete implementations
domain	Entities, Aggregates, Commands, Queries, Events	Core domain modeling primitives
eventstore	EventStore, Snapshot, MongoDBEventStore, InMemoryStore	Event sourcing store interfaces and backends
exceptions	NotFoundException, InvalidOperationException, ...	Typed, reusable error classes
repositories	IRepository<T>, InMemoryRepository<T>, MongoRepository<T>	Persistence abstractions for aggregates and entities
utils	logger, config, healthCheck, backoff	Logger, health check helpers, backoff, and more

🧪 Usage Examples

1. Publishing an Event

import { RabbitMQEventBus } from '@folksdo/shared-lib';

const bus = new RabbitMQEventBus({ uri: process.env.AMQP_URL! });
await bus.connect();
await bus.publish({
  type: 'UserCreated',
  payload: { id: '123', email: '[e-mail]' },
});

2. Using the MongoDB Event Store

import { MongoDBEventStore } from '@folksdo/shared-lib';

const store = new MongoDBEventStore({ uri: process.env.MONGO_URI!, dbName: 'events' });
await store.connect();
await store.appendEvent({
  aggregateId: 'acc-1',
  type: 'AccountOpened',
  payload: { balance: 0 },
});

3. Logging and Error Handling

import { logger, BasicException } from '@folksdo/shared-lib';

logger.info('Service started');

try {
  // some operation
} catch (err) {
  logger.error('Unexpected error:', err);
  throw new BasicException('Processing failed');
}

4. Express Health Check Endpoint

import express from 'express';
import { healthCheck } from '@folksdo/shared-lib';

const app = express();

app.get('/health', async (_req, res) => {
  const status = await healthCheck();
  res.status(status.healthy ? 200 : 503).json(status);
});

🛠 Development

1. Clone and Install

git clone https://github.com/chammart/folksdo-shared-lib.git
cd folksdo-shared-lib
yarn install

2. Build

yarn build

3. Run Tests

yarn test

4. Lint and Type Check

yarn lint
yarn typecheck
yarn typecheck:tests

🤝 Contributing

We welcome contributions!

• Fork the repo
• Create your feature branch: git checkout -b feat/my-feature
• Commit your changes: git commit -m "feat: add new utility"
• Push the branch: git push origin feat/my-feature
• Open a Pull Request

Make sure to:

• Follow the existing code style and structure
• Add unit tests for new functionality
• Ensure all tests and builds pass

📄 License

Licensed under the ISC License.

© 2025 FolksDo Inc. — Built with passion for clean architecture and scalable microservices.

Let me know if you'd like a badge section (e.g., `npm version`, `build passing`, etc.) or GitHub Actions CI workflow reference added at the top.