Skip to content
NHCarrigan Logo NHCarrigan Docs

@nhcarrigan/logger

@nhcarrigan/logger (hereinafter the “Application”) is a custom logging utility that provides a wrapper around a custom alert monitoring server, enabling applications to pipe errors and log messages to a centralized alerting system.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Installation

Install the package using your preferred package manager:

Terminal window
npm install @nhcarrigan/logger
Terminal window
pnpm add @nhcarrigan/logger
Terminal window
yarn add @nhcarrigan/logger

Quick Start

import { Logger } from "@nhcarrigan/logger";


// Initialize the logger
const logger = new Logger("my-app", "your-api-token");


// Send log messages
await logger.log("info", "Application started successfully");
await logger.log("warn", "This is a warning message");
await logger.log("debug", "Debug information");


// Send error reports
try {
  // Your code here
} catch (error) {
  await logger.error("functionName", error);
}

API Reference

Constructor

new Logger(application: string, token: string, url?: string)

Parameters:

  • application (string): The name of your application (will appear in logs)
  • token (string): Your API token for the monitoring service
  • url (optional string): Custom URL for your own alerting instance (defaults to “https://alerts.nhcarrigan.com”)

Methods

log(level: Level, message: string): Promise<void>

Sends a log message to the alerting service.

Parameters:

  • level (Level): The log level - one of “debug”, “info”, or “warn”
  • message (string): The message to send
error(context: string, error: Error): Promise<void>

Sends an error to the alerting service with stack trace information.

Parameters:

  • context (string): A brief description of where the error occurred (e.g., function name)
  • error (Error): The Node.js error object

Log Levels

The Application supports three log levels:

  • "debug": Debug information for development purposes
  • "info": General informational messages
  • "warn": Warning messages that don’t halt execution

Custom Alerting Server

By default, the logger sends data to https://alerts.nhcarrigan.com. You can configure it to use your own alerting instance by providing a custom URL in the constructor.

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

Architecture

The Application is built as a TypeScript class that wraps HTTP requests to an alerting server. It provides two main endpoints:

  1. /log - For general log messages
  2. /error - For error reporting with stack traces

API Endpoints

POST /log

Sends structured log data:

{
  "application": "your-app-name",
  "level": "info",
  "message": "Your log message"
}

POST /error

Sends structured error data:

{
  "application": "your-app-name",
  "context": "function-name",
  "message": "Error message",
  "stack": "Stack trace information"
}

Authentication

All requests require an Authorization header with your API token.

Development Setup

  1. Clone the repository:

    Terminal window
    git clone https://git.nhcarrigan.com/nhcarrigan/logger.git

  2. Install dependencies:

    Terminal window
    pnpm install

  3. Build the project:

    Terminal window
    pnpm run build

  4. Run linting:

    Terminal window
    pnpm run lint

Project Structure

src/
├── index.ts          # Main Logger class
└── types/
    └── level.ts      # Log level type definitions

TypeScript Configuration

The project uses:

  • @nhcarrigan/typescript-config for TypeScript configuration
  • @nhcarrigan/eslint-config for ESLint rules
  • ES modules ("type": "module")

This section is for expansions to our legal policies specific to the Application.

License

This software is licensed under Naomi’s Public License. See the LICENSE.md file for complete terms.

Copyright held by Naomi Carrigan.

Privacy

See PRIVACY.md for privacy policy information.

Terms of Service

See TERMS.md for terms of service.

Security

See SECURITY.md for security policy and vulnerability reporting procedures.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

Getting Started

  1. Read our Code of Conduct
  2. Review our Contributing Guidelines
  3. Fork the repository
  4. Create a feature branch
  5. Make your changes
  6. Submit a Pull Request

Development Guidelines

  • Follow the existing code style enforced by ESLint
  • Ensure TypeScript compilation passes without errors
  • Add appropriate JSDoc comments for new public methods
  • Test your changes thoroughly

Issue Reporting

If you encounter bugs or have feature requests:

  1. Check existing issues first
  2. Create a new issue with detailed information
  3. Include reproduction steps for bugs
  4. Tag issues appropriately

Contact

Package Information