@folksdo/shared-lib v1.0.5

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

🧪 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: 'a@b.com' },
});

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!

1. Fork the repo
2. Create your feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m "feat: add new utility"
4. Push the branch: git push origin feat/my-feature
5. 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.