@xeno-js/shared 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Xeno
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+<div align="center">
+  <img src="logo/logo.png" alt="Xeno Shared Logo" width="140" />
+
+  <h1>Xeno Shared</h1>
+
+  <p><em>Enterprise-grade primitive types, constants, and utilities for the Xeno ecosystem</em></p>
+
+  <p>
+    <a href="https://github.com/xeno-js/xeno-js">
+      <img src="https://img.shields.io/badge/Powered%20by-Xeno-blueviolet?style=flat-square" alt="Powered by Xeno" />
+    </a>
+    <a href="https://github.com/xeno-js/xeno-shared/blob/main/LICENSE">
+      <img src="https://img.shields.io/npm/l/@xeno-js/shared?style=flat-square" alt="License: ISC" />
+    </a>
+    <a href="https://www.npmjs.com/package/@xeno-js/shared">
+      <img src="https://img.shields.io/npm/v/@xeno-js/shared?style=flat-square" alt="NPM Version" />
+    </a>
+    <a href="https://buymeacoffee.com/xenojs">
+      <img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-Support-FFdd00?style=flat-square&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me A Coffee" />
+    </a>
+  </p>
+</div>
+
+---
+
+## What is Xeno Shared?
+
+**Xeno Shared** (`@xeno-js/shared`) is the foundational package for the entire
+Xeno framework ecosystem. It acts as the core dependency bridging both the
+backend (`@xeno-js/core`) and frontend (`@xeno-js/vue`) implementations.
+
+This package is meticulously designed to provide zero-dependency (where
+possible), highly optimized primitives, enforcing structural consistency, type
+safety, and architectural boundaries across all Xeno modules. It guarantees that
+constants, interfaces, and utilities behave identically whether executed in a
+Node.js server or a browser environment.
+
+---
+
+## 💡 Key Features & Offerings
+
+- **Universal Type Definitions**: Centralizes critical `TypeScript` interfaces
+  and types (`ResponseDto`, `IPaginatedResult`, `ICommand`, `IQuery`,
+  `InjectionToken`) to ensure a unified contract between the client and server.
+- **Agnostic Constants**: Exports canonical constants (`STATUS_CODES`,
+  `ERROR_CODES`, `LOG_LEVEL`, `REQUEST_TYPE`) preventing magic strings/numbers
+  and maintaining unified semantics across the infrastructure.
+- **Validation & Guards**: Provides the `Guards` utility object for robust,
+  zero-magic runtime type checking and validation (e.g., `isDefined`,
+  `isNullOrEmpty`, `isDate`).
+- **Resiliency & Async Utilities**: Includes `PromiseHelper` for advanced async
+  timing logic (delays, jitter for mitigating thundering herds) and constants
+  for `Cockatiel` resilience policies (`RESILIENCE_DEFAULTS`).
+- **Security Primitives**: Features `SanitizeHelper` to enforce OWASP guidelines
+  against Log Injection (CWE-117) and unsafe URIs.
+- **Shared Infrastructural Adapters**: Includes base infrastructural classes and
+  mappers (e.g., `ReadDao`, `Repository`, `ConsoleLogger`, `AxiosHttpClient`,
+  `SupabaseClaimsMapper`) allowing downstream packages to extend them.
+
+---
+
+## 📦 Installation
+
+This package is typically installed automatically as a dependency of
+`@xeno-js/core` or `@xeno-js/vue`. If you need to install it directly for shared
+domain logic in a monorepo:
+
+```bash
+npm install @xeno-js/shared
+
+```
+
+Xeno uses **Optional Peer Dependencies**. You only install the external
+libraries you actually need.
+
+```bash
+# Example: Install tools only if you enable them
+npm install axios cockatiel zod @supabase/supabase-js
+
+```
+
+---
+
+## 📖 Core Usage Examples
+
+### 1. Unified API Responses
+
+Use `HttpHelper` to generate standardized success and error payloads.
+
+```typescript
+import { HttpHelper, STATUS_CODES, ERROR_CODES } from '@xeno-js/shared'
+
+// Success Response
+const response = HttpHelper.success(
+  { id: 1, name: 'Xeno' },
+  STATUS_CODES.CREATED,
+)
+
+// Error Response
+const errorResponse = HttpHelper.error(
+  {
+    success: false,
+    error: {
+      code: ERROR_CODES.VALIDATION_FAILED,
+      message: 'Invalid input provided',
+    },
+    correlationId: '...',
+    requestId: '...',
+    spanId: '...',
+    timestamp: new Date().toISOString(),
+  },
+  STATUS_CODES.BAD_REQUEST,
+)
+```
+
+### 2. Runtime Type Guards
+
+Use the `Guards` namespace to ensure bulletproof runtime checks.
+
+```typescript
+import { Guards } from '@xeno-js/shared'
+
+function processData(payload: unknown) {
+  if (Guards.isNullOrEmpty(payload)) {
+    throw new Error('Payload cannot be empty')
+  }
+
+  if (Guards.isString(payload)) {
+    console.log(payload.toUpperCase())
+  }
+}
+```
+
+### 3. Asynchronous Jitter
+
+Use `PromiseHelper` to stagger requests and avoid network congestion.
+
+```typescript
+import { PromiseHelper } from '@xeno-js/shared'
+
+async function fetchWithRetry() {
+  const BASE_DELAY = 100
+  const MAX_JITTER = 50
+
+  // Wait for 100ms + a random value up to 50ms
+  await PromiseHelper.delayWithJitter(BASE_DELAY, MAX_JITTER)
+  return performNetworkCall()
+}
+```
+
+---
+
+## 🤝 For Contributors
+
+We welcome contributions to Xeno! To maintain the highest code quality and
+stability of the core framework, **direct pushes to the `main` and `develop`
+branches are strictly prohibited.** Please follow this Git Flow to contribute:
+
+1. **Branch off from `develop**`: Create a new branch for your feature or
+   bugfix.
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feat/your-awesome-feature
+
+```
+
+2. **Make your changes**: Write your code and ensure it passes all local checks
+   (linting, types, and tests).
+
+```bash
+npm run check
+
+```
+
+3. **Commit your changes**: We enforce
+   [Conventional Commits](https://www.conventionalcommits.org/?utm_source=gemini).
+   Husky will verify your commit message format.
+
+4. **Commit Format:**
+
+```bash
+feat(scope): add new feature
+fix(scope): resolve bug
+chore(scope): update dependencies
+
+```
+
+5. **Submit a Pull Request (PR)**: Push your branch to GitHub and open a Pull
+   Request targeting the **`develop`** branch.
+6. **Review**: The repository owner will review your code, run pipeline tests,
+   and merge it into `develop`.
+
+_Note: The `main` branch is strictly reserved for production releases. Code
+flows from feature branches ➡️ `develop` ➡️ `main`._
+
+### Scripts
+
+| Command             | Description                                        |
+| ------------------- | -------------------------------------------------- |
+| `npm run build`     | Builds the TypeScript source code into `dist/`<br> |
+| `npm run typecheck` | Checks types without emitting files                |
+
+| | `npm run lint` | Runs ESLint
+
+| | `npm run format` | Formats code with Prettier
+
+| | `npm run test` | Runs the Vitest test suite
+
+| | `npm run test:coverage` | Runs tests and generates a coverage report
+
+|
+
+### Code Quality (Husky & Git Hooks)
+
+This project strictly enforces code quality rules before pushing to the
+repository:
+
+- **`pre-commit`**: Runs `lint-staged` on staged files (ESLint + Prettier).
+
+- **`commit-msg`**: Checks commit messages with `commitlint` (we use
+  Conventional Commits).
+
+- **`pre-push`**: Runs type checking, linting, and testing before code leaves
+  your machine.
+
+---
+
+## 🌱 Support & Appreciation
+
+Building, benchmarking, and maintaining a progressive, enterprise-ready
+open-source framework requires a massive amount of continuous dedication and
+architectural engineering.
+
+If Xeno has brought value to your development workflows, helped decouple your
+core business logic, or simplified your system infrastructure layout, consider
+supporting its open-source lifecycle. Your backing directly accelerates our
+strategic roadmap.
+
+**[Read our support guidelines and find out how to help](https://www.xeno-js.it/support-us)**
+
+Thank you for being part of this decoupled open-source journey!
+
+<amp-bounce>
+</amp-bounce>
+<a href="https://www.buymeacoffee.com/xenojs" target="_blank">
+<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="42" style="height: 42px !important;" />
+</a>
+
+---
+
+## 🛡️ Powered by Xeno
+
+If you are using Xeno in your project, let the world know! Add this badge to
+your README:
+
+```html
+<a
+  href="[https://github.com/xeno-js/xeno-js](https://github.com/xeno-js/xeno-js)"
+  target="_blank"
+>
+  <img
+    src="[https://img.shields.io/badge/Powered%20by-Xeno-black?style=flat-square](https://img.shields.io/badge/Powered%20by-Xeno-black?style=flat-square)"
+    alt="Powered by Xeno"
+    height="20"
+  />
+</a>
+```
+
+## 📄 License
+
+Copyright (c) 2026 Xeno. Licensed under the
+[ISC License](https://www.google.com/search?q=LICENSE&utm_source=gemini).

package/dist/application/cqrs/command/command.d.ts

@@ -0,0 +1,8 @@
+import type { ICommand } from '../../../domain';
+import type { RequestType } from '../../../shared';
+export declare abstract class Command<TResponse = unknown> implements ICommand<TResponse> {
+    readonly intent: string;
+    readonly type: RequestType;
+    constructor(intent: string);
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/application/cqrs/command/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../src/application/cqrs/command/command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAG3C,8BAAsB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAE,YAAW,QAAQ,CAAC,SAAS,CAAC;IAGnE,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFnC,SAAgB,IAAI,EAAE,WAAW,CAAuB;gBAEnC,MAAM,EAAE,MAAM;CACpC"}

package/dist/application/cqrs/command/command.js

@@ -0,0 +1,9 @@
+import { REQUEST_TYPE } from '../../../shared';
+export class Command {
+    intent;
+    type = REQUEST_TYPE.COMMAND;
+    constructor(intent) {
+        this.intent = intent;
+    }
+}
+//# sourceMappingURL=command.js.map

package/dist/application/cqrs/command/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../../../src/application/cqrs/command/command.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,OAAgB,OAAO;IAGN;IAFL,IAAI,GAAgB,YAAY,CAAC,OAAO,CAAA;IAExD,YAAqB,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;CACxC"}

package/dist/application/cqrs/command/index.d.ts

@@ -0,0 +1,2 @@
+export * from './command';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/cqrs/command/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/application/cqrs/command/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/application/cqrs/command/index.js

@@ -0,0 +1,2 @@
+export * from './command';
+//# sourceMappingURL=index.js.map

package/dist/application/cqrs/command/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/application/cqrs/command/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA"}

package/dist/application/cqrs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './command';
+export * from './query';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/cqrs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/cqrs/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA"}

package/dist/application/cqrs/index.js

@@ -0,0 +1,3 @@
+export * from './command';
+export * from './query';
+//# sourceMappingURL=index.js.map

package/dist/application/cqrs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/cqrs/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA"}

package/dist/application/cqrs/query/index.d.ts

@@ -0,0 +1,2 @@
+export * from './query';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/cqrs/query/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/application/cqrs/query/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA"}

package/dist/application/cqrs/query/index.js

@@ -0,0 +1,2 @@
+export * from './query';
+//# sourceMappingURL=index.js.map

package/dist/application/cqrs/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/application/cqrs/query/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA"}

package/dist/application/cqrs/query/query.d.ts

@@ -0,0 +1,9 @@
+import type { IQuery } from '../../../domain';
+import type { ICacheableOptions, RequestType } from '../../../shared';
+export declare abstract class Query<TResponse = unknown> implements IQuery<TResponse> {
+    readonly intent: string;
+    readonly cacheOptions: ICacheableOptions;
+    readonly type: RequestType;
+    constructor(intent: string, cacheOptions: ICacheableOptions);
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/application/cqrs/query/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/application/cqrs/query/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAG9D,8BAAsB,KAAK,CAAC,SAAS,GAAG,OAAO,CAAE,YAAW,MAAM,CAAC,SAAS,CAAC;IAIzE,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,YAAY,EAAE,iBAAiB;IAJ1C,SAAgB,IAAI,EAAE,WAAW,CAAqB;gBAG3C,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,iBAAiB;CAE3C"}

package/dist/application/cqrs/query/query.js

@@ -0,0 +1,11 @@
+import { REQUEST_TYPE } from '../../../shared';
+export class Query {
+    intent;
+    cacheOptions;
+    type = REQUEST_TYPE.QUERY;
+    constructor(intent, cacheOptions) {
+        this.intent = intent;
+        this.cacheOptions = cacheOptions;
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/application/cqrs/query/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../../../src/application/cqrs/query/query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,OAAgB,KAAK;IAId;IACA;IAJK,IAAI,GAAgB,YAAY,CAAC,KAAK,CAAA;IAEtD,YACW,MAAc,EACd,YAA+B;QAD/B,WAAM,GAAN,MAAM,CAAQ;QACd,iBAAY,GAAZ,YAAY,CAAmB;IACvC,CAAC;CACL"}

package/dist/application/index.d.ts

@@ -0,0 +1,3 @@
+export * from './cqrs';
+export * from './loggers';
+//# sourceMappingURL=index.d.ts.map

package/dist/application/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA"}

package/dist/application/index.js

@@ -0,0 +1,3 @@
+export * from './cqrs';
+export * from './loggers';
+//# sourceMappingURL=index.js.map

package/dist/application/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/application/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA"}

package/dist/application/loggers/__tests__/base.logger.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base.logger.test.d.ts.map

package/dist/application/loggers/__tests__/base.logger.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.logger.test.d.ts","sourceRoot":"","sources":["../../../../src/application/loggers/__tests__/base.logger.test.ts"],"names":[],"mappings":""}

package/dist/application/loggers/__tests__/base.logger.test.js

@@ -0,0 +1,132 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { LOG_LEVEL, LOG_LEVEL_NAMES } from '../../../shared';
+import { BaseLogger } from '../base.logger';
+const makeRequestContext = (executionContext) => ({
+    getContext: vi.fn().mockReturnValue(executionContext),
+});
+const makeExecutionContext = () => ({
+    identity: {
+        userId: '123',
+        email: 'admin@example.com',
+        name: 'admin',
+        tenantId: '456',
+        roles: ['admin'],
+        permissions: ['read'],
+    },
+    network: {
+        requestId: '789',
+        clientIp: '127.0.0.1',
+        userAgent: 'Mozilla/5.0',
+        formatIndicator: 'json',
+        path: '/api/test',
+        transport: {
+            res: '',
+            req: '',
+        },
+        csrf: undefined,
+        origin: 'http://localhost:3000',
+    },
+    tracing: {
+        correlationId: 'req-1',
+        startTime: Date.now(),
+        spanId: 'span-1',
+        parentSpanId: 'parent-span-1',
+    },
+    messaging: undefined,
+});
+describe('BaseLogger', () => {
+    let trackMock;
+    let requestContext;
+    let executionContext;
+    beforeEach(() => {
+        trackMock = vi.fn();
+        executionContext = makeExecutionContext();
+        requestContext = makeRequestContext(executionContext);
+    });
+    describe('info()', () => {
+        it('forwards an INFO message to the client when minLevel is INFO', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, [client]);
+            logger.info('hello');
+            expect(trackMock).toHaveBeenCalledOnce();
+            expect(trackMock).toHaveBeenCalledWith(LOG_LEVEL.INFO, `[${LOG_LEVEL_NAMES[LOG_LEVEL.INFO]}] hello`, executionContext, undefined);
+        });
+        it('does NOT forward when INFO is below minLevel WARN', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.WARN, [client]);
+            logger.info('silent');
+            expect(trackMock).not.toHaveBeenCalled();
+        });
+    });
+    describe('warn()', () => {
+        it('forwards a WARN message to the client when minLevel is INFO', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, [client]);
+            logger.warn('careful');
+            expect(trackMock).toHaveBeenCalledOnce();
+            expect(trackMock).toHaveBeenCalledWith(LOG_LEVEL.WARN, `[${LOG_LEVEL_NAMES[LOG_LEVEL.WARN]}] careful`, executionContext, undefined);
+        });
+        it('does NOT forward when WARN is below minLevel ERROR', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.ERROR, [client]);
+            logger.warn('silent');
+            expect(trackMock).not.toHaveBeenCalled();
+        });
+    });
+    describe('debug()', () => {
+        it('forwards a DEBUG message when minLevel is DEBUG', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.DEBUG, [client]);
+            logger.debug('verbose');
+            expect(trackMock).toHaveBeenCalledOnce();
+            expect(trackMock).toHaveBeenCalledWith(LOG_LEVEL.DEBUG, `[${LOG_LEVEL_NAMES[LOG_LEVEL.DEBUG]}] verbose`, executionContext, undefined);
+        });
+        it('does NOT forward DEBUG when minLevel is INFO', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, [client]);
+            logger.debug('silent');
+            expect(trackMock).not.toHaveBeenCalled();
+        });
+    });
+    describe('error()', () => {
+        it('forwards an ERROR message with error object', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, [client]);
+            const err = new Error('boom');
+            logger.error('something went wrong', err);
+            expect(trackMock).toHaveBeenCalledOnce();
+            expect(trackMock).toHaveBeenCalledWith(LOG_LEVEL.ERROR, `[${LOG_LEVEL_NAMES[LOG_LEVEL.ERROR]}] something went wrong`, executionContext, err);
+        });
+        it('does NOT forward ERROR when minLevel is above ERROR (impossible in practice but tests boundary)', () => {
+            const client = { track: trackMock };
+            const logger = new BaseLogger(requestContext, (LOG_LEVEL.ERROR + 1), [client]);
+            logger.error('silent', new Error('x'));
+            expect(trackMock).not.toHaveBeenCalled();
+        });
+    });
+    describe('broadcast — context handling', () => {
+        it('passes undefined context when getContext() returns undefined', () => {
+            const ctxWithoutData = makeRequestContext(undefined);
+            const client = { track: trackMock };
+            const logger = new BaseLogger(ctxWithoutData, LOG_LEVEL.INFO, [client]);
+            logger.info('no context');
+            expect(trackMock).toHaveBeenCalledWith(LOG_LEVEL.INFO, `[${LOG_LEVEL_NAMES[LOG_LEVEL.INFO]}] no context`, undefined, undefined);
+        });
+    });
+    describe('broadcast — multiple clients', () => {
+        it('forwards the message to every registered client', () => {
+            const trackMock2 = vi.fn();
+            const client1 = { track: trackMock };
+            const client2 = { track: trackMock2 };
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, [client1, client2]);
+            logger.info('broadcast');
+            expect(trackMock).toHaveBeenCalledOnce();
+            expect(trackMock2).toHaveBeenCalledOnce();
+        });
+        it('does nothing when the clients array is empty', () => {
+            const logger = new BaseLogger(requestContext, LOG_LEVEL.INFO, []);
+            expect(() => logger.info('no clients')).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=base.logger.test.js.map

package/dist/application/loggers/__tests__/base.logger.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.logger.test.js","sourceRoot":"","sources":["../../../../src/application/loggers/__tests__/base.logger.test.ts"],"names":[],"mappings":"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"}

package/dist/application/loggers/base.logger.d.ts

@@ -0,0 +1,48 @@
+import type { IContextAccessor, ILogger, ILoggerClient, RequestContext } from '../../domain';
+import type { LogLevel } from '../../shared';
+/**
+ * @description Concrete implementation of the ILogger interface that serves as a central logging service within the application. This class is designed to broadcast log messages to multiple logging clients (implementations of ILoggerClient) that are injected via the constructor. The BaseLogger class provides methods for logging messages at different levels (info, warn, debug, error) and ensures that only messages that meet or exceed the specified minimum log level are forwarded to the registered logging clients. This design allows for flexibility in logging, enabling the use of various logging providers (e.g., Sentry, Pino) without coupling the application code to specific logging frameworks.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+export declare class BaseLogger implements ILogger {
+    private readonly _requestContext;
+    private readonly _minLevel;
+    private readonly _loggers;
+    /**
+     * @description Constructs a new instance of the BaseLogger class, which takes an array of ILoggerClient instances and an optional minimum log level. The ILoggerClient instances represent the various logging providers that will receive log messages from this logger. The minimum log level determines the threshold for logging messages, where messages with a log level below the specified minimum will not be forwarded to the logging clients. This allows for efficient logging by filtering out less critical log messages based on the configured log level.
+     * @param _requestContext The request context that provides contextual information for log messages, such as request-specific data or metadata.
+     * @param config The minimum log level for this logger instance. Only messages with a log level equal to or higher than this level will be processed and forwarded to the logging clients.
+     * @param loggers An array of ILoggerClient instances that will receive log messages from this logger. Each ILoggerClient represents a different logging provider or destination (e.g., console, file, external service).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    constructor(_requestContext: IContextAccessor<RequestContext>, config: LogLevel, loggers: ILoggerClient[]);
+    info(message: string): void;
+    warn(message: string): void;
+    debug(message: string): void;
+    error(message: string, error: unknown): void;
+    /**
+     * @description Private method to broadcast log messages to all registered ILoggerClient instances. This method checks if the log level of the message meets or exceeds the configured minimum log level before forwarding the message to the logging clients. It iterates through the array of ILoggerClient instances and calls their track method with the appropriate parameters (log level, message, context, and error if applicable). This design allows for efficient logging by ensuring that only relevant log messages are processed and forwarded to the logging clients based on the configured log level.
+     * @param level The log level of the message.
+     * @param message The log message.
+     * @param context Optional context information to include with the log message.
+     * @param error Optional error object to include with the log message.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    private broadcast;
+}
+//# sourceMappingURL=base.logger.d.ts.map

package/dist/application/loggers/base.logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.logger.d.ts","sourceRoot":"","sources":["../../../src/application/loggers/base.logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACxF,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,UAAU,CAAA;AAGlD;;;;;;;;KAQK;AACL,qBAAa,UAAW,YAAW,OAAO;IAkBtC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAhBlC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C;;;;;;;;;;;OAWG;gBAEgB,eAAe,EAAE,gBAAgB,CAAC,cAAc,CAAC,EAClE,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,aAAa,EAAE;IAMnB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI3B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAInD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;CASlB"}