@quicore/loggable

A comprehensive, class-based logging library for creating standardized and extensible activity logs in JavaScript.

This package provides a set of classes built around a core Loggable base class, allowing you to easily construct detailed and consistent log objects that can be serialized to JSON.

Features

• Class-Based Design: Use familiar object-oriented patterns to build your logs.
• Reduced Boilerplate: A central Loggable class handles getters, setters, and JSON serialization, keeping your code clean.
• Standardized Structure: Create logs with a consistent schema, making them easier to parse and analyze.
• Extensible: Easily add new fields or custom classes by extending Loggable.

Installation

npm install @quicore/loggable

Usage

You can import all classes from the main entry point of the package.

import {
  ActivityLog,
  Agent,
  Detail,
  EventSource,
  HttpRequest,
  Loggable,
  Network,
  Outcome,
  Process,
  Resource,
  User,
} from '@quicore/loggable';

// Example Usage:
const log = new ActivityLog('authentication', 'login', 'info');
log.description = 'User login attempt';

const user = new User('user123', 'human');
const network = new Network('192.168.1.100', 'client.example.com');
const agent = new Agent(user, network);

log.addAgent(agent);

const resource = new Resource('application', 'login-service');
log.addResource(resource);

const outcome = new Outcome('SUCCESS', 'Login successful');
log.outcome = outcome;

console.log(JSON.stringify(log.toJSON(), null, 2));

/*
Output:
{
  "type": "authentication",
  "action": "login",
  "severity": "info",
  "occurred": {
    "start": "2023-10-27T10:00:00.000Z", // Actual date/time will vary
    "end": "2023-10-27T10:00:00.000Z"
  },
  "recordedAt": "2023-10-27T10:00:00.000Z",
  "subtype": [],
  "tags": [],
  "source": [],
  "detail": [],
  "agent": [
    {
      "user": {
        "uid": "user123",
        "type": "human",
        "roles": [],
        "groups": []
      },
      "network": {
        "ip": "192.168.1.100",
        "host": "client.example.com"
      }
    }
  ],
  "resource": [
    {
      "type": "application",
      "name": "login-service"
    }
  ],
  "outcome": {
    "code": "SUCCESS",
    "detail": "Login successful"
  }
}
*/

API Reference

Core Classes

• Loggable: The base class from which all other classes inherit. Provides core functionality like the toJSON() method.
• ActivityLog: The main class for an activity log event. It aggregates all other classes and is the primary object you will work with.

Supporting Classes

• Outcome: Describes the result of an activity (e.g., SUCCESS, FAILURE).
• Network: Captures network-related information like IP addresses and hostnames.
• EventSource: Defines the source of the event (e.g., an application, system, or vendor).
• Detail: A flexible class for adding custom key-value pairs to a log.
• HttpRequest: Stores details about an HTTP request.
• User: Contains user-specific information.
• Resource: Describes the target of the activity, such as a file or database.
• Process: Holds information about a process or service.
• Agent: Represents the actor that initiated the activity, combining User and Network data.

License

Distributed under the MIT License. See LICENSE for more information.