API Reference

Complete API documentation for LogStack package

🚀 Initialization

init(config)

Initialize LogStack with configuration options.

Signature

async function init(config: LogStackConfig): Promise<void>

Parameters

Parameter Type Required Description
config LogStackConfig ✅ Configuration object for LogStack

Example

const { init } = require('logstack');

const config = {
  dbUri: 'mongodb://localhost:27017/logs',
  uploadProvider: 's3',
  s3: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: 'us-east-1',
    bucket: 'my-logs-bucket'
  }
};

await init(config);

Throws

  • Error - If database connection fails
  • Error - If storage provider configuration is invalid
  • ValidationError - If required configuration is missing

⚙️ Configuration Types

LogStackConfig

Main configuration interface for LogStack initialization.

interface LogStackConfig {
  // Database Configuration
  dbUri: string;
  collections?: {
    jobsCollectionName?: string;
    logsCollectionName?: string;
    apiLogsCollectionName?: string;
  };

  // Storage Provider
  uploadProvider: 'local' | 's3';
  outputDirectory?: string;

  // AWS S3 Configuration
  s3?: {
    accessKeyId: string;
    secretAccessKey: string;
    region: string;
    bucket: string;
    serverSideEncryption?: string;
    storageClass?: string;
  };

  // Folder Structure
  folderStructure?: {
    type: 'daily' | 'monthly' | 'yearly' | 'custom';
    subFolders?: {
      enabled: boolean;
      byHour?: boolean;
      byStatus?: boolean;
      custom?: string[];
    };
    naming?: {
      prefix?: string;
      dateFormat?: string;
      includeTime?: boolean;
    };
  };

  // Data Masking
  dataMasking?: {
    enabled: boolean;
    maskEmails?: boolean;
    maskIPs?: boolean;
    maskPasswords?: boolean;
    showLastChars?: number;
    customFields?: string[];
    maskingChar?: string;
  };

  // Retention Policies
  retention?: {
    enabled: boolean;
    dbRetentionDays: number;
    fileRetentionDays: number;
    cleanupIntervalHours?: number;
  };

  // Compression
  compression?: {
    enabled: boolean;
    format?: 'gzip' | 'zip';
    level?: number;
  };

  // Monitoring
  monitoring?: {
    enabled: boolean;
    logLevel?: 'error' | 'warn' | 'info' | 'debug';
    metricsInterval?: number;
  };
}

🔧 Core Functions

createDailyJobs()

Create 24 hourly jobs for the current day to process logs automatically.

Signature

async function createDailyJobs(): Promise<Job[]>

Returns

Promise<Job[]> - Array of created job objects

Example

const { createDailyJobs } = require('logstack');

const jobs = await createDailyJobs();
console.log(`Created ${jobs.length} jobs for today`);

saveApiLog(logData)

Save a single API log entry to the database.

Signature

async function saveApiLog(logData: ApiLogData): Promise<ApiLog>

Parameters

Parameter Type Required Description
logData ApiLogData ✅ API log data to save

Example

const { saveApiLog } = require('logstack');

const logData = {
  method: 'POST',
  path: '/api/users',
  statusCode: 201,
  responseTime: 150,
  request: {
    body: { name: 'John Doe', email: 'john@example.com' }
  },
  response: {
    body: { id: '12345', name: 'John Doe' }
  },
  timestamp: new Date(),
  userAgent: 'Mozilla/5.0...',
  clientIP: '192.168.1.100'
};

const savedLog = await saveApiLog(logData);

📅 Job Management

createJob(jobData)

Create a custom job for log processing.

Signature

async function createJob(jobData: JobData): Promise<Job>

Parameters

Parameter Type Required Description
jobData JobData ✅ Job configuration data

Example

const { createJob } = require('logstack');

const jobData = {
  startDate: new Date('2025-09-02T10:00:00Z'),
  endDate: new Date('2025-09-02T11:00:00Z'),
  status: 'pending',
  attempts: 0,
  metadata: {
    description: 'Process morning logs',
    priority: 'high'
  }
};

const job = await createJob(jobData);

processJob(jobId)

Process a specific job by ID.

Signature

async function processJob(jobId: string): Promise<ProcessResult>

Returns

Promise<ProcessResult> - Result of job processing

getJobStatus(jobId)

Get the current status of a job.

Signature

async function getJobStatus(jobId: string): Promise<JobStatus>

📊 Log Operations

getApiLogs(filter)

Retrieve API logs with optional filtering.

Signature

async function getApiLogs(filter?: LogFilter): Promise<ApiLog[]>

Parameters

Parameter Type Required Description
filter LogFilter ❌ Optional filter criteria

Example

const { getApiLogs } = require('logstack');

// Get all logs
const allLogs = await getApiLogs();

// Get logs with filter
const errorLogs = await getApiLogs({
  statusCode: { $gte: 400 },
  timestamp: {
    $gte: new Date('2025-09-02T00:00:00Z'),
    $lt: new Date('2025-09-03T00:00:00Z')
  },
  method: 'POST'
});

console.log(`Found ${errorLogs.length} error logs`);

deleteOldLogs(days)

Delete logs older than specified number of days.

Signature

async function deleteOldLogs(days: number): Promise<DeleteResult>

Returns

Promise<DeleteResult> - Number of deleted records and operation status

🛠️ Utility Functions

validateConfig(config)

Validate LogStack configuration before initialization.

Signature

function validateConfig(config: LogStackConfig): ValidationResult

Returns

ValidationResult - Validation status and any errors

maskSensitiveData(data, options)

Manually mask sensitive data in objects.

Signature

function maskSensitiveData(data: any, options?: MaskingOptions): any

Example

const { maskSensitiveData } = require('logstack');

const sensitiveData = {
  email: 'user@example.com',
  password: 'secret123',
  creditCard: '4532-1234-5678-9012'
};

const masked = maskSensitiveData(sensitiveData, {
  maskPasswords: true,
  showLastChars: 4
});

console.log(masked);
// Output: {
//   email: '****@example.com',
//   password: '********',
//   creditCard: '****-****-****-9012'
// }

📝 TypeScript Types

ApiLogData

interface ApiLogData {
  method: string;
  path: string;
  statusCode: number;
  responseTime?: number;
  timestamp?: Date;
  request?: {
    headers?: Record<string, string>;
    body?: any;
    query?: Record<string, any>;
  };
  response?: {
    headers?: Record<string, string>;
    body?: any;
  };
  user?: {
    id?: string;
    email?: string;
    role?: string;
  };
  clientIP?: string;
  userAgent?: string;
  referer?: string;
  metadata?: Record<string, any>;
}

Job

interface Job {
  _id: string;
  startDate: Date;
  endDate: Date;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  attempts: number;
  maxAttempts: number;
  createdAt: Date;
  updatedAt: Date;
  processedAt?: Date;
  error?: string;
  metadata?: Record<string, any>;
}

ProcessResult

interface ProcessResult {
  success: boolean;
  jobId: string;
  recordsProcessed: number;
  filesGenerated: string[];
  uploadResults: UploadResult[];
  processingTime: number;
  errors?: string[];
}

🔔 Events

LogStack emits events during operation that you can listen to for monitoring and debugging.

job:started

Emitted when a job starts processing.

const logstack = require('logstack');

logstack.on('job:started', (job) => {
  console.log(`Job ${job._id} started processing`);
});

job:completed

Emitted when a job completes successfully.

logstack.on('job:completed', (job, result) => {
  console.log(`Job ${job._id} completed: ${result.recordsProcessed} records processed`);
});

job:failed

Emitted when a job fails.

logstack.on('job:failed', (job, error) => {
  console.error(`Job ${job._id} failed:`, error.message);
});

upload:progress

Emitted during file upload progress.

logstack.on('upload:progress', (filename, progress) => {
  console.log(`Upload progress for ${filename}: ${progress}%`);
});
← Previous: Examples Next: Troubleshooting →