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

npm install @precision-ss/core

Quick Start

Importing

import pss from '@precision-ss/core';

PCoreError

Create rich, consistent error objects with built-in HTTP status codes and detailed context.

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).

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

import pss from '@precision-ss/core';

pss.server.init({
  port: 4000,
  enableSockets: true,
  socketOptions: {
    // Socket.IO options
  }
});

await server.start();

Register Middleware & Routes

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

import pss from '@precision-ss/core';

await server.stop();

Access Express and Socket.IO Instances

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