fix(documentation): Update API reference and enhance README with detailed examples and usage instructions
This commit is contained in:
300
API.md
Normal file
300
API.md
Normal file
@ -0,0 +1,300 @@
|
||||
# @push.rocks/smartlog API Reference
|
||||
|
||||
This document provides a detailed reference for all exports and APIs available in the @push.rocks/smartlog package and its submodules.
|
||||
|
||||
## Core Module (`@push.rocks/smartlog`)
|
||||
|
||||
The core module provides the main logging functionality.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `Smartlog`
|
||||
|
||||
Main logger class for creating, managing, and routing logs.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
|
||||
const logger = new Smartlog({
|
||||
logContext: {
|
||||
company: 'MyCompany',
|
||||
environment: 'production',
|
||||
// ...other context properties
|
||||
},
|
||||
minimumLogLevel: 'info' // Optional, defaults to 'silly'
|
||||
});
|
||||
```
|
||||
|
||||
**Constructor Options:**
|
||||
- `logContext`: Object containing context information about the environment
|
||||
- `minimumLogLevel`: Optional minimum log level to process (defaults to 'silly')
|
||||
|
||||
**Methods:**
|
||||
- `log(logLevel, message, data?, correlation?)`: Log a message with optional data and correlation
|
||||
- `increment(logLevel, message, data?, correlation?)`: Log an increment counter
|
||||
- `addLogDestination(destination)`: Add a custom log destination
|
||||
- `enableConsole(options?)`: Enable console logging (with optional stdout/stderr capture)
|
||||
- `createLogGroup(transactionId?)`: Create a log group for related logs
|
||||
- `handleLog(logPackage)`: Handle a pre-formatted log package
|
||||
|
||||
**Static Methods:**
|
||||
- `createForCommitinfo(commitinfo)`: Create a logger with commit information
|
||||
|
||||
#### `LogGroup`
|
||||
|
||||
Groups related logs together for better traceability.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
|
||||
const logger = new Smartlog({/*...*/});
|
||||
const logGroup = logger.createLogGroup('transaction-123');
|
||||
|
||||
logGroup.log('info', 'Starting process');
|
||||
// All logs in this group will share the same transaction ID
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `log(logLevel, message, data?)`: Log a message within this group
|
||||
- `increment(logLevel, message, data?)`: Log an increment within this group
|
||||
|
||||
#### `ConsoleLog`
|
||||
|
||||
Implementation of `ILogDestination` that logs to console.
|
||||
|
||||
## Interfaces Module (`@push.rocks/smartlog/interfaces`)
|
||||
|
||||
This module provides all type definitions and interfaces used by Smartlog.
|
||||
|
||||
### Types
|
||||
|
||||
- `TLogType`: Available log types
|
||||
- `'log' | 'increment' | 'gauge' | 'error' | 'success' | 'value' | 'finance' | 'compliance'`
|
||||
|
||||
- `TLogLevel`: Available log levels
|
||||
- `'silly' | 'info' | 'debug' | 'note' | 'ok' | 'success' | 'warn' | 'error' | 'lifecycle'`
|
||||
|
||||
- `TEnvironment`: Available environments
|
||||
- `'local' | 'test' | 'staging' | 'production'`
|
||||
|
||||
- `TRuntime`: Available runtime environments
|
||||
- `'node' | 'chrome' | 'rust' | 'deno' | 'cloudflare_workers'`
|
||||
|
||||
### Interfaces
|
||||
|
||||
#### `ILogContext`
|
||||
|
||||
Metadata about the environment where logging occurs.
|
||||
|
||||
```typescript
|
||||
interface ILogContext {
|
||||
commitinfo?: ICommitInfo;
|
||||
company?: string;
|
||||
companyunit?: string;
|
||||
containerName?: string;
|
||||
environment?: TEnvironment;
|
||||
runtime?: TRuntime;
|
||||
zone?: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### `ILogCorrelation`
|
||||
|
||||
Information for correlating related logs.
|
||||
|
||||
```typescript
|
||||
interface ILogCorrelation {
|
||||
id: string;
|
||||
type: 'none' | 'service' | 'build' | 'infrastructure' | 'cdn';
|
||||
instance?: string;
|
||||
group?: string;
|
||||
transaction?: string;
|
||||
}
|
||||
```
|
||||
|
||||
#### `ILogPackage<T = unknown>`
|
||||
|
||||
The standard log package format.
|
||||
|
||||
```typescript
|
||||
interface ILogPackage<T = unknown> {
|
||||
timestamp: number;
|
||||
type: TLogType;
|
||||
context: ILogContext;
|
||||
level: TLogLevel;
|
||||
correlation: ILogCorrelation;
|
||||
message: string;
|
||||
data?: T;
|
||||
}
|
||||
```
|
||||
|
||||
#### `ILogDestination`
|
||||
|
||||
Interface for implementing custom log destinations.
|
||||
|
||||
```typescript
|
||||
interface ILogDestination {
|
||||
handleLog: (logPackage: ILogPackage) => Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
## Interactive Console Module (`@push.rocks/smartlog/source-interactive`)
|
||||
|
||||
This module provides interactive console components like spinners and progress bars.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `SmartlogSourceInteractive`
|
||||
|
||||
Creates interactive spinners for CLI applications.
|
||||
|
||||
```typescript
|
||||
import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';
|
||||
|
||||
const spinner = new SmartlogSourceInteractive();
|
||||
spinner.text('Loading data...');
|
||||
// Later
|
||||
spinner.finishSuccess('Data loaded successfully!');
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `text(message)`: Sets the spinner text and starts it if not running
|
||||
- `finishSuccess(message?)`: Completes the spinner with success message
|
||||
- `finishFail(message?)`: Completes the spinner with failure message
|
||||
- `successAndNext(message)`: Marks success and starts a new spinner
|
||||
- `failAndNext(message)`: Marks failure and starts a new spinner
|
||||
- `setSpinnerStyle(style)`: Sets spinner style ('dots', 'line', 'star', 'simple')
|
||||
- `setColor(color)`: Sets the spinner color
|
||||
- `setSpeed(ms)`: Sets the animation speed
|
||||
|
||||
#### `SmartlogProgressBar`
|
||||
|
||||
Creates progress bars for CLI applications.
|
||||
|
||||
```typescript
|
||||
import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';
|
||||
|
||||
const bar = new SmartlogProgressBar({
|
||||
total: 100,
|
||||
width: 40,
|
||||
showEta: true
|
||||
});
|
||||
|
||||
bar.update(50); // Update to 50%
|
||||
bar.increment(10); // Increment by 10 units
|
||||
bar.complete(); // Complete the progress bar
|
||||
```
|
||||
|
||||
**Constructor Options:**
|
||||
- `total`: Total number of items/steps
|
||||
- `width`: Width of the bar in characters
|
||||
- `complete`: Character for completed section
|
||||
- `incomplete`: Character for incomplete section
|
||||
- `renderThrottle`: Minimum time between renders
|
||||
- `clear`: Whether to clear the bar on completion
|
||||
- `showEta`: Show estimated time remaining
|
||||
- `showPercent`: Show percentage completed
|
||||
- `showCount`: Show count of items
|
||||
|
||||
**Methods:**
|
||||
- `update(value)`: Update progress to a specific value
|
||||
- `increment(value?)`: Increment progress by a value (default: 1)
|
||||
- `complete()`: Mark the progress bar as complete
|
||||
- `setColor(color)`: Set the color of the progress bar
|
||||
|
||||
## File Destination Module (`@push.rocks/smartlog/destination-file`)
|
||||
|
||||
This module provides a log destination that writes logs to a file.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `SmartlogDestinationFile`
|
||||
|
||||
Writes logs to a file with timestamps.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';
|
||||
|
||||
const logger = new Smartlog({/*...*/});
|
||||
const fileDestination = new SmartlogDestinationFile('/absolute/path/to/logfile.log');
|
||||
logger.addLogDestination(fileDestination);
|
||||
```
|
||||
|
||||
**Constructor Parameters:**
|
||||
- `filePath`: Absolute path to the log file
|
||||
|
||||
## Local Destination Module (`@push.rocks/smartlog/destination-local`)
|
||||
|
||||
This module provides a log destination with colorful formatting for local development.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `DestinationLocal`
|
||||
|
||||
Formats logs with colors and prefixes for better readability in the console.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
import { DestinationLocal } from '@push.rocks/smartlog/destination-local';
|
||||
|
||||
const logger = new Smartlog({/*...*/});
|
||||
const localDestination = new DestinationLocal();
|
||||
logger.addLogDestination(localDestination);
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `handleLog(logPackage)`: Handles a log package
|
||||
- `newLine(lines?)`: Adds empty lines to the console
|
||||
- `logReduced(text, repeatEveryTimes?)`: Logs only when the message changes
|
||||
|
||||
## DevTools Destination Module (`@push.rocks/smartlog/destination-devtools`)
|
||||
|
||||
This module provides a log destination that formats logs for browser developer tools.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `SmartlogDestinationDevtools`
|
||||
|
||||
Formats logs with colors for browser developer tools.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';
|
||||
|
||||
const logger = new Smartlog({/*...*/});
|
||||
const devtoolsDestination = new SmartlogDestinationDevtools();
|
||||
logger.addLogDestination(devtoolsDestination);
|
||||
```
|
||||
|
||||
## ClickHouse Destination Module (`@push.rocks/smartlog/destination-clickhouse`)
|
||||
|
||||
This module provides a log destination that stores logs in a ClickHouse database.
|
||||
|
||||
### Classes
|
||||
|
||||
#### `SmartlogDestinationClickhouse`
|
||||
|
||||
Stores logs in a ClickHouse database for analytics and querying.
|
||||
|
||||
```typescript
|
||||
import { Smartlog } from '@push.rocks/smartlog';
|
||||
import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';
|
||||
|
||||
const logger = new Smartlog({/*...*/});
|
||||
const clickhouseDestination = await SmartlogDestinationClickhouse.createAndStart({
|
||||
host: 'clickhouse.example.com',
|
||||
port: 8123,
|
||||
user: 'username',
|
||||
password: 'password',
|
||||
database: 'logs_db'
|
||||
});
|
||||
logger.addLogDestination(clickhouseDestination);
|
||||
```
|
||||
|
||||
**Static Methods:**
|
||||
- `createAndStart(options)`: Create and initialize a ClickHouse destination
|
||||
|
||||
**Methods:**
|
||||
- `start()`: Initialize the connection to ClickHouse
|
||||
- `handleLog(logPackage)`: Store a log in ClickHouse
|
||||
Reference in New Issue
Block a user