npm package: @qpmtx/shared
Description: ![QP MTX Framework](assets/qpmtx-framework.png)
Latest version: 0.1.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# @qpmtx/shared

![QP MTX Framework](assets/qpmtx-framework.png)

Lightweight shared utilities and HTTP exception helpers for the QPMTX framework. This package centralises exception classes, metadata keys, and common type/object utilities so downstream services stay consistent and strongly typed.

## Features

- Fully typed HTTP exception hierarchy with sensible defaults sourced from a single status/message map.
- Type-safe guards (`isNullish`, `isPresent`, `isRecord`, `isThenable`, etc.) and deep merge utility tailored for configuration objects.
- Shared metadata key registry consumed by decorators throughout the framework.
- Bun-powered toolchain with linting, type checking, testing, and build scripts.
- Automated GitHub Action that bumps versions, tags, builds, runs tests, and publishes releases to npm.

## Getting Started

Install dependencies (Bun is required):

```bash
bun install
```

### Available Scripts

| Command | Description |
| --- | --- |
| `bun run lint` | Format + lint sources with Biome. |
| `bun run check:types` | Type-check using the root `tsconfig.json`. |
| `bun test` | Execute Bun test suites (constants, utils, exceptions). |
| `bun run build` | Emit bundled JS (`build:js`) and DTS (`build:types`) into `dist/`. |
| `bun run dev` | Build continuously while watching for file changes. |

### Usage Examples

#### Exceptions

```ts
import { BadRequestException, HttpStatus } from "@qpmtx/shared"

throw new BadRequestException("Invalid payload structure", {
  expected: ["name", "email"],
})
```

Each specialised exception extends `HttpException`, prebinding the correct `HttpStatus` and default message from `ExceptionMessages`. Pass a custom message or details payload when needed.

#### Utilities

```ts
import { deepMerge, isThenable, typedKeys } from "@qpmtx/shared"

const merged = deepMerge(
  { database: { host: "localhost", options: { reconnect: true } } },
  { database: { port: 5432, options: { reconnect: false } } },
)

if (isThenable(merged.database.options)) {
  await merged.database.options
}

typedKeys(merged.database) // -> ["host", "options", "port"]
```

## Tests

Unit tests live under `tests/` and run with Bun:

```bash
bun test
```

CI (GitHub Actions) replays lint, type, and test commands before any publish step, ensuring releases only ship when the suite passes locally and in the workflow.

## Publishing Workflow

1. Configure an `NPM_TOKEN` secret in the repository (publish rights required).
2. Trigger the **Publish Package** workflow via GitHub’s “Run workflow” button.
3. Choose the `release_type` (`patch`, `minor`, or `major`). The action will:
   - Install dependencies.
   - Run lint, type-check, tests, and build.
   - Bump the version with `npm version` (updating `package.json` and tags).
   - Publish to npm (`npm publish --access public`).
   - Push the release commit and tag back to the repository.

## Contributing

1. Fork the repo and create a branch.
2. Run `bun install`.
3. Execute `bun run lint`, `bun run check:types`, and `bun test` before opening a PR.
4. Follow existing code style; use TypeScript and keep utilities framework-agnostic.

## Author

- Hasan Diab — QPMATRIX  
  📧 hasan@qpmatrix.tech

## License

MIT © QPMTX Framework