npm package: @precision-ss/core
Description: A utility library created by Precision Software Solutions LLC.
Author: Joel Driver
Latest version: 1.8.0

# Precision Software Solutions - Core Utility Library

A lightweight Node.js utility library providing robust error handling, structured logging, and an easy-to-use
Express-based API server with optional Socket.IO support.

## Overview

PCore Utility Library simplifies common backend needs by offering:

- PCoreError: Consistent, extendable error objects with HTTP status codes and rich context.
- PCoreLogger: Structured, leveled logging built on pino, with dynamic namespace support.
- PCoreServer: A singleton Express.js HTTP server wrapper with optional Socket.IO integration, flexible middleware
  management, and common HTTP parsing & security helpers.

## Installation

```shell
npm install @precision-ss/core
```

## Quick Start

### Importing

```javascript
import pss from '@precision-ss/core';
```

### PCoreError

Create rich, consistent error objects with built-in HTTP status codes and detailed context.

```javascript
import pss from '@precision-ss/core';

// Custom server error
throw pss.error.Server('Something went wrong');

// Validation error wrapping a Zod error
try {
  // validate something
} catch (zErr) {
  throw pss.error.Validation(zErr);
}

// Not found error example
throw pss.error.NotFound('User', userId);

// Unauthorized and Forbidden examples
throw pss.error.Unauthorized();
throw pss.error.Forbidden('user123', '/admin');
```

### PCoreLogger

Built on top of pino with added features:

- Custom log levels including "story" for business-meaningful logs.
- Namespace support for scoped logging.
- Dynamic global log level control.
  - change levels and base bindings at runtime across all loggers
- Redacts sensitive keys (key, secret, password).

```javascript
import pss from '@precision-ss/core';

log.setLevel('info');

const logger = log.create({ app: 'myapp' }, 'module', 'submodule');

logger.debug('Does not print');
logger.info('Application started');
logger.story({ userId: 123 }, 'User logged in');
logger.error(new Error('Something bad'));

log.setLevel('debug');

logger.debug('Prints this time!');
```

### PCoreServer

#### Initialize and Start

```javascript
import pss from '@precision-ss/core';

pss.server.init({
  port: 4000,
  enableSockets: true,
  socketOptions: {
    // Socket.IO options
  }
});

await server.start();
```

#### Register Middleware & Routes

```javascript
import pss from '@precision-ss/core';
import express from 'express';

// Add JSON parsing middleware
pss.server.enableJsonParsing();

// Add custom middleware
pss.server.useMiddleware((req, res, next) => {
  console.log('Request URL:', req.url);
  next();
});

// Add express router
const router = express.Router();

router.get('/hello', (req, res) => {
  res.send('Hello from PCore Server!');
});

pss.server.addRouter('/api', router);
```

#### Stop Server

```javascript
import pss from '@precision-ss/core';

await server.stop();
```

#### Access Express and Socket.IO Instances

```javascript
import pss from '@precision-ss/core';

const app = server.getApp();
const io = server.getIO();
```

## Development & Testing

- The server module provides a reset() method to clear internal state for isolated testing.
- The HTTP server supports starting and stopping as promises for async control.
- Access to the raw HTTP server is gated by PCORE_ALLOW_TEST=true environment variable to avoid accidental misuse.

## License

This library is released under the MIT License. See the LICENSE file in the root of the project for details.

## Contributing

Contributions, issues, and feature requests are welcome! Feel free to fork and submit pull requests.

## Coming Soon

Wiki with details for all options and more detailed usage examples