GenesisTrace

A comprehensive, production-grade terminal logging and UI library for Deno. Zero external dependencies, pure Deno native APIs, with full TypeScript support and 24-bit true color.

Quick Reference

Task	Code
Basic logging	`logger.info("message", { data })`
Child logger	`logger.child("namespace")`
Configure logger	`new ConfigBuilder().theme(neonTheme).logLevel("info").build()`
Progress bar	`new ProgressBar({ total: 100 }).update(50)`
Spinner	`new Spinner({ message: "Loading..." }).start()`
Table	`TableRenderer.render(data)`
Box	`BoxRenderer.render("Message", { style: "double" })`
Colors	`ColorSystem.rgb(255, 107, 53)` or `ColorSystem.hexToRgb("#FF6B35")`
Theme	`new ConfigBuilder().theme(neonTheme).build()`
Plugin	`.plugin(new FileLoggerPlugin({ filepath: "./logs/app.log" }))`
Shutdown	`await logger.shutdown()`

📚 Detailed Documentation:

Color System - RGB colors, gradients, terminal detection
Theme System - Built-in themes, custom themes, theme registry
Plugins - Plugin architecture, built-in plugins, custom plugins
Visual Components - Tables, boxes, progress bars, charts, prompts
API Reference - Complete API documentation

Why GenesisTrace?

GenesisTrace is a professional logging and terminal UI library that replaces multiple packages with a single, zero-dependency solution.

Traditional Deno/Node.js projects need multiple packages for comprehensive terminal functionality:

// Traditional approach (10+ dependencies)
import pino from "pino"; // Logging
import chalk from "chalk"; // Colors
import ora from "ora"; // Spinners
import inquirer from "inquirer"; // Prompts
import boxen from "boxen"; // Boxes
import gradient from "gradient-string"; // Gradients
// ... plus their transitive dependencies = 50+ packages

// GenesisTrace approach (0 dependencies)
import {
  BoxRenderer,
  ColorSystem, // 24-bit color
  ConfigBuilder,
  InteractivePrompts, // User input
  Logger, // Structured logging
  neonTheme, // Configuration
  ProgressBar, // Progress indicators
  Spinner,
  TableRenderer, // UI components
} from "jsr:@pedromdominguez/genesis-trace";

What Makes GenesisTrace Unique?

True Zero Dependencies: No npm packages, no external code. Only Deno's built-in standard library APIs.
Production-Ready Logging: Enterprise-grade structured logging with metadata, namespaces, filtering, and history.
Rich Terminal UI: Tables, charts, progress bars, spinners, banners, boxes, and interactive prompts.
Advanced Color System: Full support for 16-color (basic ANSI), 256-color (extended), and 16.7M-color (24-bit RGB) modes with automatic terminal capability detection.
Theme System: 5 built-in professional themes with full customization and dynamic loading.
Plugin Architecture: Extensible system with lifecycle hooks for custom logging destinations and transformations.
Type-Safe Everything: Full TypeScript with zero any types, comprehensive exports, and excellent IntelliSense.
One Import: Cohesive API designed to work together seamlessly.

Philosophy & Design

GenesisTrace is built on the UNIX Philosophy and modern software engineering principles:

Core Principles

Zero Dependencies
- Built exclusively with Deno's native APIs (Deno namespace and Web Standards)
- No supply chain vulnerabilities or breaking changes from upstream dependencies
- Faster installation, smaller bundle sizes, and instant startup times
- Complete control over every line of code
Do One Thing Well
- Each module has a single, clear responsibility
- Small, focused functions that compose together
- No feature bloat - every feature earns its place
Composability
- Components work together but remain independent
- Mix and match features as needed
- Standard interfaces for interoperability
Type Safety First
- Full TypeScript support with no any types
- Comprehensive type exports for all public APIs
- IntelliSense-friendly design for excellent DX
Production Ready
- Battle-tested design patterns from real-world applications
- Performance optimized (lazy evaluation, minimal overhead)
- Comprehensive error handling and graceful degradation
- Memory-efficient with configurable limits
Developer Experience
- Beautiful, readable output by default
- Intuitive, discoverable APIs
- Extensive documentation and examples
- Easy to test and mock

What Can You Build?

GenesisTrace enables you to build:

CLI Tools: Rich terminal applications with progress bars, tables, and interactive prompts
Microservices: Production services with structured logging and metric tracking
DevOps Tools: Deployment scripts, CI/CD pipelines, system monitors with beautiful output
Data Pipelines: ETL processes with progress tracking, error logging, and visual reports
Admin Dashboards: Terminal-based dashboards with real-time charts and tables
Testing Tools: Test runners with formatted output and detailed reports
Build Systems: Custom build tools with progress tracking and structured output

Core Architecture

GenesisTrace is organized into six core modules:

1. Core Logging (`core/`)

Logger: Main logging class with structured logging, child loggers, and history
ConfigBuilder: Fluent configuration builder for all logger settings
ColorSystem: Advanced color system with RGB, gradients, and terminal detection
Formatter: Utility formatters for bytes, duration, numbers, currency, dates
ConsoleStyler: High-level console output with sections and request logging

2. Visual Components (`components/`)

TableRenderer: Render data as ASCII tables with custom columns and formatting
BoxRenderer: Create styled message boxes with multiple border styles
ProgressBar: Visual progress tracking with percentage and labels
Spinner: Animated loading indicators with success/failure states
ChartRenderer: Terminal-based bar charts with colors and labels
BannerRenderer: Application banners with ASCII art
InteractivePrompts: User input, confirmations, and selections

3. Theme System (`themes/`)

5 Built-in Themes: default, neon, dracula, minimal, red-alert
Theme Interface: Complete color palette, symbols, and box drawing characters
Theme Registry: Dynamic theme loading via getTheme(name)
Custom Themes: Easy to create and register your own themes

4. Plugin Architecture (`plugins/`)

FileLoggerPlugin: Write logs to file system
JsonLoggerPlugin: Output structured JSON logs
RemoteLoggerPlugin: Send logs to remote HTTP endpoints
SlackLoggerPlugin: Send critical alerts to Slack channels
Plugin Interface: Lifecycle hooks (onInit, onLog, onShutdown)

5. Abstractions (`interfaces/`)

ILogger: Logging abstraction interface for dependency injection
ConsoleStylerLogger: ILogger implementation wrapping ConsoleStyler
defaultLogger: Singleton logger for quick use

6. Utilities (`utils/`)

TerminalDetector: Detect terminal capabilities and color support
Format Helpers: Re-exports of Formatter utilities for convenience
ANSI: Low-level ANSI escape code definitions

Features Overview

Logging Features

✅ 6 Log Levels: debug, info, success, warning, error, critical
✅ Structured Metadata: Attach arbitrary data to log entries
✅ Child Loggers: Namespaced loggers with inheritance
✅ Log History: Built-in history with filtering and export
✅ Lazy Evaluation: Zero overhead when log level is disabled
✅ Plugin System: Extensible with custom destinations

Visual Components

✅ Tables: ASCII tables with custom columns, widths, and alignment
✅ Boxes: Styled message boxes (single, double, rounded, bold borders)
✅ Progress Bars: Configurable width, colors, and labels
✅ Spinners: 10+ animation styles with status messages
✅ Charts: Terminal bar charts with colors and labels
✅ Banners: ASCII art application banners
✅ Interactive Prompts: Input, confirm, select

Color System

✅ 16 Colors: Basic ANSI (universal compatibility)
✅ 256 Colors: Extended palette (modern terminals)
✅ 16.7M Colors: 24-bit RGB true color (latest terminals)
✅ Auto Detection: Automatic terminal capability detection
✅ Hex Support: Convert hex colors to RGB ANSI codes
✅ Gradients: Generate smooth color gradients
✅ Semantic Colors: Business-context color names

Configuration

✅ Fluent Builder: ConfigBuilder with chainable methods
✅ Mode Detection: Auto, enabled, or disabled for colors/emoji/unicode
✅ Timestamp Formats: Customizable date/time formatting
✅ History Control: Enable/disable with size limits
✅ Theme Support: Use built-in or custom themes
✅ Log Level Filtering: Control output verbosity

Quick Start

Installation

// Import from JSR (recommended)
import { Logger } from "jsr:@pedromdominguez/genesis-trace";

// Or import from deno.land/x
import { Logger } from "https://deno.land/x/genesis_trace/mod.ts";

// Or use local mod.ts
import { Logger } from "./mod.ts";

Basic Usage

import { Logger } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger();

// Six log levels
logger.debug("Debug information");
logger.info("General information");
logger.success("Operation completed successfully");
logger.warning("Warning: something needs attention");
logger.error("Error: operation failed");
logger.critical("Critical: system failure");

Configuration

import { ConfigBuilder, Logger, neonTheme } from "jsr:@pedromdominguez/genesis-trace";

const config = new ConfigBuilder()
  .theme(neonTheme)
  .logLevel("info") // Filter out debug logs
  .timestampFormat("YYYY-MM-DD HH:mm:ss")
  .enableHistory(true)
  .maxHistorySize(500)
  .colorMode("auto") // Auto-detect terminal capabilities
  .build();

const logger = new Logger(config);

Structured Logging

Log with Metadata

Attach structured data to log entries for filtering and analysis:

import { Logger } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger();

logger.info("User logged in", {
  userId: "12345",
  username: "alice",
  ip: "192.168.1.100",
  timestamp: new Date().toISOString(),
});

logger.error("Database connection failed", {
  host: "db.example.com",
  port: 5432,
  error: "Connection timeout",
  retryAttempt: 3,
});

Child Loggers (Namespaces)

Create namespaced loggers for different modules:

import { Logger } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger();

// Create child loggers with namespaces
const apiLogger = logger.child("api");
const dbLogger = logger.child("database");
const cacheLogger = logger.child("cache");

// Logs will be prefixed with namespace
apiLogger.info("Handling GET request to /users");
// Output: [api] Handling GET request to /users

dbLogger.info("Executing query: SELECT * FROM users");
// Output: [database] Executing query: SELECT * FROM users

// Child loggers can have their own children
const authLogger = apiLogger.child("auth");
authLogger.info("User authenticated");
// Output: [api:auth] User authenticated

Log History

Access and filter log history:

import { ConfigBuilder, Logger } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger(
  new ConfigBuilder()
    .enableHistory(true)
    .maxHistorySize(1000)
    .build(),
);

logger.info("Log message 1");
logger.warning("Log message 2");
logger.error("Log message 3");

// Get all history
const allLogs = logger.getHistory();
console.log(`Total logs: ${allLogs.length}`);

// Filter by log level
const errors = logger.getHistory({ level: "error" });
console.log(`Total errors: ${errors.length}`);

// Filter by time range
const recent = logger.getHistory({
  since: new Date(Date.now() - 3600000), // Last hour
});

// Export to file
await logger.exportLogs("./logs/export.json");

// Clear history
logger.clearHistory();

Log Level Filtering

Control verbosity with log levels:

import { ConfigBuilder, Logger } from "jsr:@pedromdominguez/genesis-trace";

// Production: only info and above
const prodLogger = new Logger(
  new ConfigBuilder().logLevel("info").build(),
);

// Development: everything including debug
const devLogger = new Logger(
  new ConfigBuilder().logLevel("debug").build(),
);

// Environment-based configuration
const logger = new Logger(
  new ConfigBuilder()
    .logLevel(Deno.env.get("ENV") === "production" ? "info" : "debug")
    .build(),
);

Log Level Hierarchy (from lowest to highest priority):

debug - Detailed debugging information
info - General informational messages
success - Successful operation completion
warning - Warning messages that need attention
error - Error conditions
critical - Critical failures requiring immediate action

When you set a log level, all messages at that level and above will be logged. For example, setting logLevel("warning") will log warning, error, and critical messages, but not debug, info, or success.

Color System & Themes

GenesisTrace provides a sophisticated color system with 16-color, 256-color, and 24-bit RGB true color support, plus 5 built-in professional themes.

Quick Examples

import { ColorSystem, ConfigBuilder, Logger, neonTheme } from "jsr:@pedromdominguez/genesis-trace";

// Use semantic colors
const { codes } = ColorSystem;
console.log(`${codes.success}Success!${codes.reset}`);

// 24-bit RGB colors
const brandColor = ColorSystem.rgb(255, 107, 53);
console.log(`${brandColor}Brand color${codes.reset}`);

// Hex colors
const hexColor = ColorSystem.hexToRgb("#FF6B35");
console.log(`${hexColor}Hex color${codes.reset}`);

// Color gradients
const gradient = ColorSystem.createGradient([255, 0, 0], [0, 0, 255], 50);

// Use themes
const logger = new Logger(
  new ConfigBuilder().theme(neonTheme).build(),
);

Features

16-Color Mode: Universal ANSI colors (works everywhere)
256-Color Mode: Extended palette for modern terminals
True Color: 24-bit RGB (16.7 million colors)
Automatic Detection: Detects terminal capabilities
Gradients: Smooth color transitions
5 Built-in Themes: default, neon, dracula, minimal, red-alert
Custom Themes: Easy to create and register

📚 Learn More:

Visual Components

Tables

Render data as beautiful ASCII tables:

import { TableRenderer } from "jsr:@pedromdominguez/genesis-trace";

const users = [
  { id: 1, name: "Alice", email: "[email protected]", role: "admin" },
  { id: 2, name: "Bob", email: "[email protected]", role: "user" },
  { id: 3, name: "Charlie", email: "[email protected]", role: "moderator" },
];

// Simple table (auto-detects columns)
TableRenderer.render(users);

// Custom columns with widths
TableRenderer.render(users, [
  { key: "id", label: "ID", width: 5, align: "right" },
  { key: "name", label: "Name", width: 20 },
  { key: "email", label: "Email", width: 30 },
  { key: "role", label: "Role", width: 12 },
]);

// Key-value table (for configuration or metadata)
TableRenderer.renderKeyValue([
  { label: "Version", value: "1.0.0" },
  { label: "Environment", value: "production" },
  { label: "Uptime", value: "5d 12h 34m" },
  { label: "Memory", value: "234 MB" },
]);

Boxes

Create styled message boxes:

import { BoxRenderer } from "jsr:@pedromdominguez/genesis-trace";

// Simple message box
BoxRenderer.render("Operation completed successfully!");

// Multi-line box with title
BoxRenderer.render(
  [
    "Server Status",
    "",
    "Port: 8000",
    "Environment: production",
    "Database: Connected",
    "Cache: Connected",
  ],
  {
    title: "System Information",
    style: "double", // single, double, rounded, bold
    padding: 2,
    align: "left",
  },
);

// Predefined message types with semantic colors
BoxRenderer.message("This is an info message", "info");
BoxRenderer.message("Success! Operation completed", "success");
BoxRenderer.message("Warning: Rate limit approaching", "warning");
BoxRenderer.message("Error: Connection failed", "error");

Box Styles:

single: Single-line border (default)
double: Double-line border
rounded: Rounded corners
bold: Bold/thick lines

Progress Indicators

Progress Bar

Visual progress tracking with percentage:

import { ProgressBar } from "jsr:@pedromdominguez/genesis-trace";

const progress = new ProgressBar({
  total: 100,
  width: 40,
  label: "Processing files",
  showPercentage: true,
  showValue: true,
});

for (let i = 0; i <= 100; i += 10) {
  progress.update(i);
  await new Promise((resolve) => setTimeout(resolve, 200));
}

progress.complete("All files processed!");

Spinner

Animated loading indicator:

import { Spinner } from "jsr:@pedromdominguez/genesis-trace";

const spinner = new Spinner({
  message: "Loading data...",
  style: "dots", // dots, line, star, arrow, box, circle, etc.
});

spinner.start();

// Simulate async work
await new Promise((resolve) => setTimeout(resolve, 2000));
spinner.update("Processing data...");

await new Promise((resolve) => setTimeout(resolve, 1000));

// Success or failure
spinner.succeed("Data loaded successfully!");
// Or: spinner.fail("Failed to load data");
// Or: spinner.warn("Loaded with warnings");
// Or: spinner.info("Operation skipped");

Spinner Styles:

dots: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
line: - \ | /
star: ✶ ✸ ✹ ✺ ✹ ✷
arrow: ← ↖ ↑ ↗ → ↘ ↓ ↙
box: ◰ ◳ ◲ ◱
circle: ◐ ◓ ◑ ◒

Charts

Render bar charts in your terminal:

import { ChartRenderer, ColorSystem } from "jsr:@pedromdominguez/genesis-trace";

const salesData = [
  { label: "Jan", value: 120 },
  { label: "Feb", value: 250 },
  { label: "Mar", value: 180 },
  { label: "Apr", value: 300 },
  { label: "May", value: 275 },
  { label: "Jun", value: 420 },
];

ChartRenderer.barChart(salesData, {
  width: 60, // Max bar width
  showValues: true, // Show values at end of bars
  color: ColorSystem.codes.cyan,
  title: "Monthly Sales ($k)",
});

Banners

Create eye-catching application banners:

import { BannerRenderer } from "jsr:@pedromdominguez/genesis-trace";

BannerRenderer.render({
  title: "MY APPLICATION",
  subtitle: "Professional CLI Tool v2.0",
  version: "2.0.0",
  author: "Your Name",
  style: "double", // single, double, bold
});

// Output:
// ╔════════════════════════════════════╗
// ║                                    ║
// ║         MY APPLICATION             ║
// ║    Professional CLI Tool v2.0      ║
// ║                                    ║
// ╚════════════════════════════════════╝
//    Version: 2.0.0
//    Author: Your Name

Enterprise Banners (ConsoleStyler)

For production applications, use ConsoleStyler.renderBanner() for rich startup banners:

import { ConsoleStyler } from "jsr:@pedromdominguez/genesis-trace";

ConsoleStyler.renderBanner({
  title: "DenoGenesis",
  version: "1.0.0",
  buildDate: "2024-01-15",
  environment: "production", // development, staging, testing, production
  port: 8000,
  author: "Your Name",
  repository: "https://github.com/yourusername/yourapp",
  description: "Enterprise Application Framework",
  features: ["REST API", "WebSockets", "GraphQL", "Database"],
  database: "PostgreSQL",
  ai: {
    enabled: true,
    models: ["GPT-4", "Claude-3"],
  },
});

Interactive Prompts

Create interactive CLI experiences:

import { InteractivePrompts } from "jsr:@pedromdominguez/genesis-trace";

// Text input
const name = await InteractivePrompts.input(
  "What is your name?",
  "Anonymous", // Default value
);
console.log(`Hello, ${name}!`);

// Yes/no confirmation
const confirmed = await InteractivePrompts.confirm(
  "Do you want to continue?",
  true, // Default value
);

if (confirmed) {
  console.log("Proceeding...");
} else {
  console.log("Cancelled.");
}

// Selection menu
const choice = await InteractivePrompts.select(
  "Choose your deployment environment:",
  ["Development", "Staging", "Production"],
);
console.log(`Deploying to: ${choice}`);

Theme System

GenesisTrace includes a powerful theme system with 5 built-in professional themes and full customization support.

Using Built-in Themes

import {
  ConfigBuilder,
  defaultTheme,
  draculaTheme,
  Logger,
  minimalTheme,
  neonTheme,
  redAlertTheme,
} from "jsr:@pedromdominguez/genesis-trace";

// Use neon theme (high-contrast, vibrant)
const neonLogger = new Logger(
  new ConfigBuilder().theme(neonTheme).build(),
);

// Use dracula theme (popular dark theme)
const draculaLogger = new Logger(
  new ConfigBuilder().theme(draculaTheme).build(),
);

// Use minimal theme (clean, minimal colors)
const minimalLogger = new Logger(
  new ConfigBuilder().theme(minimalTheme).build(),
);

// Use red-alert theme (high-visibility red theme)
const alertLogger = new Logger(
  new ConfigBuilder().theme(redAlertTheme).build(),
);

Load Theme by Name

import { ConfigBuilder, getTheme, Logger } from "jsr:@pedromdominguez/genesis-trace";

// Load from theme registry
const theme = getTheme("neon");
if (theme) {
  const logger = new Logger(
    new ConfigBuilder().theme(theme).build(),
  );
}

// List all available themes
import { themes } from "jsr:@pedromdominguez/genesis-trace";
console.log("Available themes:", Object.keys(themes));

Theme Anatomy

Each theme defines three key areas:

interface Theme {
  name: string;

  // Color palette for log levels and UI
  colors: {
    primary: string; // Primary brand color
    secondary: string; // Secondary color
    success: string; // Success state (green)
    warning: string; // Warning state (yellow)
    error: string; // Error state (red)
    info: string; // Info state (cyan/blue)
    debug: string; // Debug state (gray)
    critical: string; // Critical state (bright red)
    muted: string; // Muted/dim text
    accent: string; // Accent/highlight color
  };

  // Symbols for log levels and UI
  symbols: {
    success: string; // ✓ or ✔
    error: string; // ✗ or ✖
    warning: string; // ⚠ or !
    info: string; // ℹ or i
    debug: string; // 🔍 or •
    critical: string; // 🚨 or !!
    bullet: string; // • or -
    arrow: string; // → or >
    check: string; // ✓
    cross: string; // ✗
  };

  // Box drawing characters for tables and boxes
  boxDrawing: {
    topLeft: string;
    topRight: string;
    bottomLeft: string;
    bottomRight: string;
    horizontal: string;
    vertical: string;
    cross: string;
    teeLeft: string;
    teeRight: string;
    teeTop: string;
    teeBottom: string;
  };
}

Creating Custom Themes

import { ConfigBuilder, Logger, Theme } from "jsr:@pedromdominguez/genesis-trace";

const myCustomTheme: Theme = {
  name: "my-custom-theme",

  colors: {
    primary: "\x1b[38;2;255;107;53m", // Orange (RGB)
    secondary: "\x1b[38;2;100;200;255m", // Sky blue
    success: "\x1b[32m", // Green
    warning: "\x1b[33m", // Yellow
    error: "\x1b[31m", // Red
    info: "\x1b[36m", // Cyan
    debug: "\x1b[90m", // Gray
    critical: "\x1b[91m", // Bright red
    muted: "\x1b[2m", // Dim
    accent: "\x1b[35m", // Magenta
  },

  symbols: {
    success: "✓",
    error: "✗",
    warning: "⚠",
    info: "ℹ",
    debug: "•",
    critical: "🚨",
    bullet: "→",
    arrow: "▸",
    check: "✔",
    cross: "✖",
  },

  boxDrawing: {
    topLeft: "╔",
    topRight: "╗",
    bottomLeft: "╚",
    bottomRight: "╝",
    horizontal: "═",
    vertical: "║",
    cross: "╬",
    teeLeft: "╠",
    teeRight: "╣",
    teeTop: "╦",
    teeBottom: "╩",
  },
};

// Use custom theme
const logger = new Logger(
  new ConfigBuilder().theme(myCustomTheme).build(),
);

Built-in Theme Descriptions

default - Balanced, professional colors for general use

Blue info, green success, yellow warning, red error
Standard Unicode symbols and box drawing

neon - High-contrast, vibrant cyberpunk aesthetic

Electric cyan, bright magenta, neon green
Perfect for dark terminals and visibility

dracula - Popular dark theme with purple accents

Based on the Dracula color scheme
Purple, pink, and cyan color palette

minimal - Clean, understated design

Minimal use of color, focus on content
Simple ASCII symbols, clean lines

red-alert - High-visibility red theme

Designed for critical systems and alerts
Red-focused palette for urgency

Plugin Architecture

Extend GenesisTrace with a powerful plugin system that provides lifecycle hooks for custom logging destinations, transformations, and integrations.

Plugin Interface

interface Plugin {
  name: string; // Plugin identifier
  version: string; // Plugin version
  onInit?(config: StylerConfig): void | Promise<void>;
  onLog?(entry: LogEntry): void | Promise<void>;
  onShutdown?(): void | Promise<void>;
  extendMethods?(): Record<string, Function>;
}

Lifecycle Hooks:

onInit: Called when logger is created, receives configuration
onLog: Called for every log entry that passes level filter
onShutdown: Called when logger.shutdown() is invoked
extendMethods: Optionally add custom methods to logger instance

Built-in Plugins

FileLoggerPlugin

Write logs to the file system:

import { ConfigBuilder, FileLoggerPlugin, Logger } from "jsr:@pedromdominguez/genesis-trace";

const config = new ConfigBuilder()
  .plugin(
    new FileLoggerPlugin({
      filepath: "./logs/app.log",
      format: "text", // "text" or "json"
      append: true, // Append to existing file
      minLevel: "info", // Only log info and above
    }),
  )
  .build();

const logger = new Logger(config);

// Logs go to console AND file
logger.info("Application started");
logger.error("Something went wrong", { error: "details" });

// Cleanup on shutdown
await logger.shutdown();

JsonLoggerPlugin

Output structured JSON logs:

import { ConfigBuilder, JsonLoggerPlugin, Logger } from "jsr:@pedromdominguez/genesis-trace";

const config = new ConfigBuilder()
  .plugin(
    new JsonLoggerPlugin({
      filepath: "./logs/app.json",
      pretty: false, // Compact JSON (one entry per line)
      includeMetadata: true, // Include all metadata fields
    }),
  )
  .build();

const logger = new Logger(config);

logger.info("User action", {
  userId: "123",
  action: "login",
  ip: "192.168.1.1",
});

// JSON output:
// {"timestamp":"2024-01-15T10:30:00.000Z","level":"info","message":"User action","metadata":{"userId":"123","action":"login","ip":"192.168.1.1"}}

RemoteLoggerPlugin

Send logs to remote HTTP endpoints:

import { ConfigBuilder, Logger, RemoteLoggerPlugin } from "jsr:@pedromdominguez/genesis-trace";

const config = new ConfigBuilder()
  .plugin(
    new RemoteLoggerPlugin({
      endpoint: "https://logs.example.com/api/logs",
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
      },
      batchSize: 10, // Send logs in batches
      flushInterval: 5000, // Flush every 5 seconds
      minLevel: "warning", // Only send warnings and above
    }),
  )
  .build();

const logger = new Logger(config);

// Logs are buffered and sent in batches
logger.warning("High memory usage", { memory: "85%" });
logger.error("Service unavailable", { service: "database" });

// Ensure all logs are sent before exit
await logger.shutdown();

SlackLoggerPlugin

Send critical alerts to Slack:

import { ConfigBuilder, Logger, SlackLoggerPlugin } from "jsr:@pedromdominguez/genesis-trace";

const config = new ConfigBuilder()
  .plugin(
    new SlackLoggerPlugin({
      webhookUrl: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
      channel: "#alerts",
      username: "Production Logger",
      iconEmoji: ":rotating_light:",
      minLevel: "error", // Only send errors and critical
      includeMetadata: true, // Include metadata in Slack message
    }),
  )
  .build();

const logger = new Logger(config);

// This goes to Slack
logger.error("Payment processing failed", {
  orderId: "12345",
  amount: "$299.99",
  error: "Gateway timeout",
});

// This also goes to Slack (critical level)
logger.critical("Database connection lost", {
  database: "production-db",
  retries: 5,
});

Creating Custom Plugins

import {
  ConfigBuilder,
  LogEntry,
  Logger,
  Plugin,
  StylerConfig,
} from "jsr:@pedromdominguez/genesis-trace";

class DiscordLoggerPlugin implements Plugin {
  name = "discord-logger";
  version = "1.0.0";

  private webhookUrl: string;
  private minLevel: string;

  constructor(options: { webhookUrl: string; minLevel?: string }) {
    this.webhookUrl = options.webhookUrl;
    this.minLevel = options.minLevel || "info";
  }

  onInit(config: StylerConfig): void {
    console.log(`[${this.name}] Plugin initialized`);
  }

  async onLog(entry: LogEntry): Promise<void> {
    // Send log to Discord webhook
    const message = {
      content: `**[${entry.level.toUpperCase()}]** ${entry.message}`,
      embeds: entry.metadata
        ? [{
          title: "Metadata",
          description: JSON.stringify(entry.metadata, null, 2),
          color: this.getLevelColor(entry.level),
        }]
        : [],
    };

    try {
      await fetch(this.webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(message),
      });
    } catch (error) {
      console.error("Failed to send log to Discord:", error);
    }
  }

  async onShutdown(): Promise<void> {
    console.log(`[${this.name}] Plugin shutting down`);
  }

  private getLevelColor(level: string): number {
    const colors: Record<string, number> = {
      debug: 0x808080, // Gray
      info: 0x00BFFF, // Blue
      success: 0x00FF00, // Green
      warning: 0xFFFF00, // Yellow
      error: 0xFF0000, // Red
      critical: 0xFF00FF, // Magenta
    };
    return colors[level] || 0xFFFFFF;
  }
}

// Use the custom plugin
const logger = new Logger(
  new ConfigBuilder()
    .plugin(
      new DiscordLoggerPlugin({
        webhookUrl: "https://discord.com/api/webhooks/...",
        minLevel: "error",
      }),
    )
    .build(),
);

logger.error("Critical error occurred", { service: "api" });

Advanced Usage

Environment-Based Configuration

import { ConfigBuilder, getTheme, Logger } from "jsr:@pedromdominguez/genesis-trace";

const env = Deno.env.get("ENV") || "development";

const config = new ConfigBuilder()
  .logLevel(env === "production" ? "info" : "debug")
  .theme(getTheme(env === "production" ? "minimal" : "neon") || defaultTheme)
  .enableHistory(env !== "production")
  .colorMode(env === "production" ? "disabled" : "auto")
  .build();

const logger = new Logger(config);

Dependency Injection with ILogger

For testable, decoupled code:

import { ConsoleStylerLogger, ILogger } from "jsr:@pedromdominguez/genesis-trace";

// Business logic depends on ILogger abstraction
class UserService {
  constructor(private logger: ILogger) {}

  async createUser(userData: unknown) {
    this.logger.logInfo("Creating user", { userData });

    try {
      const user = await this.saveToDatabase(userData);
      this.logger.logSuccess("User created", { userId: user.id });
      return user;
    } catch (error) {
      this.logger.logError("Failed to create user", { error });
      throw error;
    }
  }
}

// Production: Use real logger
const consoleLogger = new ConsoleStylerLogger({
  enableColors: true,
  logLevel: "info",
});
const userService = new UserService(consoleLogger);

// Testing: Use mock logger
class MockLogger implements ILogger {
  logs: Array<{ level: string; message: string }> = [];

  logInfo(message: string, metadata?: Record<string, unknown>) {
    this.logs.push({ level: "info", message });
  }

  logSuccess(message: string, metadata?: Record<string, unknown>) {
    this.logs.push({ level: "success", message });
  }

  logError(message: string, metadata?: Record<string, unknown>) {
    this.logs.push({ level: "error", message });
  }

  // ... implement other methods
}

const mockLogger = new MockLogger();
const testService = new UserService(mockLogger);

ILogger Interface Methods:

logInfo(message, metadata?) - Log informational messages
logSuccess(message, metadata?) - Log success messages
logWarning(message, metadata?) - Log warnings
logError(message, metadata?) - Log errors
logDebug(message, metadata?) - Log debug information
logCritical(message, metadata?) - Log critical failures
logRequest(method, path, status, duration, size?) - Log HTTP requests
logSection(title, colorName?, style?) - Log section headers

Graceful Shutdown

Properly close logger and plugins:

import {
  ConfigBuilder,
  FileLoggerPlugin,
  Logger,
  RemoteLoggerPlugin,
} from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger(
  new ConfigBuilder()
    .plugin(new FileLoggerPlugin({ filepath: "./logs/app.log" }))
    .plugin(
      new RemoteLoggerPlugin({
        endpoint: "https://logs.example.com/api/logs",
        batchSize: 10,
      }),
    )
    .build(),
);

// Use logger throughout app
logger.info("Application started");
logger.info("Processing request");

// On shutdown (SIGINT, SIGTERM, or process exit)
Deno.addSignalListener("SIGINT", async () => {
  logger.info("Shutting down...");
  await logger.shutdown(); // Flushes all plugins
  Deno.exit(0);
});

// Or wrap in try/finally
try {
  // Application logic
} finally {
  await logger.shutdown();
}

Dynamic Plugin Registration

Add plugins at runtime:

import { FileLoggerPlugin, Logger } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger();

// Add plugin dynamically
const filePlugin = new FileLoggerPlugin({ filepath: "./logs/app.log" });
logger.use(filePlugin);

// Plugin will receive logs from this point forward
logger.info("This goes to file");

Runtime Configuration Changes

Modify logger configuration after creation:

import { Logger, neonTheme } from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger();

// Change configuration at runtime
logger.configure({
  logLevel: "debug",
  theme: neonTheme,
  enableHistory: false,
});

API Reference

Core Classes

Logger

Main logging class with structured logging and child loggers.

class Logger {
  constructor(config?: StylerConfig, namespace?: string);

  // Log methods
  debug(message: string, metadata?: Record<string, any>): void;
  info(message: string, metadata?: Record<string, any>): void;
  success(message: string, metadata?: Record<string, any>): void;
  warning(message: string, metadata?: Record<string, any>): void;
  error(message: string, metadata?: Record<string, any>): void;
  critical(message: string, metadata?: Record<string, any>): void;

  // Child loggers
  child(namespace: string, overrides?: Partial<StylerConfig>): Logger;

  // Plugin management
  use(plugin: Plugin): void;

  // Configuration
  configure(config: Partial<StylerConfig>): void;

  // History
  getHistory(filter?: { level?: LogLevel; since?: Date }): LogEntry[];
  clearHistory(): void;
  exportLogs(filepath: string): Promise<void>;

  // Lifecycle
  shutdown(): Promise<void>;
}

ConfigBuilder

Fluent builder for logger configuration.

class ConfigBuilder {
  colorMode(mode: "auto" | "enabled" | "disabled"): this;
  emojiMode(mode: "auto" | "enabled" | "disabled"): this;
  unicodeMode(mode: "auto" | "enabled" | "disabled"): this;
  timestampFormat(format: string): this;
  dateFormat(format: string): this;
  logLevel(level: LogLevel): this;
  enableHistory(enable: boolean): this;
  maxHistorySize(size: number): this;
  theme(theme: Theme): this;
  plugin(plugin: Plugin): this;
  output(output: LogOutput): this;
  build(): StylerConfig;
}

ColorSystem

Advanced color system with RGB, gradients, and terminal detection.

class ColorSystem {
  static codes: {
    // 16 basic ANSI colors
    reset: string;
    black: string;
    red: string;
    green: string;
    yellow: string;
    blue: string;
    magenta: string;
    cyan: string;
    white: string;
    // ... and more
  };

  // 24-bit RGB
  static rgb(r: number, g: number, b: number): string;
  static rgbBg(r: number, g: number, b: number): string;
  static hexToRgb(hex: string): string;

  // 256 colors
  static color256(code: number): string;
  static bgColor256(code: number): string;

  // Gradients
  static createGradient(
    start: [number, number, number],
    end: [number, number, number],
    steps: number,
  ): string[];

  // Terminal detection
  static detectColorSupport(): "none" | "basic" | "256" | "truecolor";
}

Formatter

Utility formatters for common use cases.

class Formatter {
  static bytes(bytes: number, decimals?: number): string;
  static duration(ms: number): string;
  static number(num: number): string;
  static currency(amount: number, currency?: string): string;
  static percentage(value: number, decimals?: number): string;
  static relativeTime(date: Date): string;
}

Visual Components

All visual components are static classes with render methods:

// Tables
TableRenderer.render(data: any[], columns?: TableColumn[]): void;
TableRenderer.renderKeyValue(items: Array<{ label: string; value: string }>): void;

// Boxes
BoxRenderer.render(content: string | string[], options?: BoxOptions): void;
BoxRenderer.message(message: string, type: "info" | "success" | "warning" | "error"): void;

// Progress
const progress = new ProgressBar(options: ProgressBarOptions);
progress.update(current: number): void;
progress.complete(message?: string): void;

const spinner = new Spinner(options: SpinnerOptions);
spinner.start(): void;
spinner.update(message: string): void;
spinner.succeed(message?: string): void;
spinner.fail(message?: string): void;
spinner.stop(): void;

// Charts
ChartRenderer.barChart(data: ChartData[], options?: ChartOptions): void;

// Banners
BannerRenderer.render(options: BannerOptions): void;

// Interactive
InteractivePrompts.input(prompt: string, defaultValue?: string): Promise<string>;
InteractivePrompts.confirm(prompt: string, defaultValue?: boolean): Promise<boolean>;
InteractivePrompts.select(prompt: string, options: string[]): Promise<string>;

Types

type LogLevel = "debug" | "info" | "success" | "warning" | "error" | "critical";

interface LogEntry {
  timestamp: Date;
  level: LogLevel;
  message: string;
  metadata?: Record<string, any>;
  namespace?: string;
}

interface Theme {
  name: string;
  colors: {/* ... */};
  symbols: {/* ... */};
  boxDrawing: {/* ... */};
}

interface Plugin {
  name: string;
  version: string;
  onInit?(config: StylerConfig): void | Promise<void>;
  onLog?(entry: LogEntry): void | Promise<void>;
  onShutdown?(): void | Promise<void>;
}

interface ILogger {
  logInfo(message: string, metadata?: Record<string, unknown>): void;
  logSuccess(message: string, metadata?: Record<string, unknown>): void;
  logWarning(message: string, metadata?: Record<string, unknown>): void;
  logError(message: string, metadata?: Record<string, unknown>): void;
  logDebug(message: string, metadata?: Record<string, unknown>): void;
  logCritical(message: string, metadata?: Record<string, unknown>): void;
  logRequest(method: string, path: string, status: number, duration: number, size?: number): void;
  logSection(title: string, colorName?: string, style?: string): void;
}

Best Practices

1. Use Child Loggers for Modules

Organize logs with namespaces:

// app.ts
const logger = new Logger();

// api.ts
const apiLogger = logger.child("api");

// database.ts
const dbLogger = logger.child("database");

// cache.ts
const cacheLogger = logger.child("cache");

2. Configure Log Levels by Environment

const config = new ConfigBuilder()
  .logLevel(Deno.env.get("ENV") === "production" ? "info" : "debug")
  .enableHistory(Deno.env.get("ENV") !== "production")
  .build();

3. Use Metadata for Structured Logging

// Good - structured metadata
logger.info("User action", {
  userId: "123",
  action: "login",
  ip: "192.168.1.1",
});

// Avoid - string interpolation
logger.info(`User 123 logged in from 192.168.1.1`);

4. Always Shutdown Gracefully

Deno.addSignalListener("SIGINT", async () => {
  await logger.shutdown();
  Deno.exit(0);
});

Deno.addSignalListener("SIGTERM", async () => {
  await logger.shutdown();
  Deno.exit(0);
});

5. Use Progress Indicators for Long Operations

const spinner = new Spinner({ message: "Processing..." });
spinner.start();

try {
  await longRunningOperation();
  spinner.succeed("Operation complete!");
} catch (error) {
  spinner.fail("Operation failed!");
  logger.error("Error details", { error });
}

6. Leverage Themes for Different Contexts

// Development: vibrant colors for visibility
const devLogger = new Logger(
  new ConfigBuilder().theme(neonTheme).build(),
);

// Production: minimal, clean output
const prodLogger = new Logger(
  new ConfigBuilder().theme(minimalTheme).build(),
);

// Alerts: high-visibility red theme
const alertLogger = new Logger(
  new ConfigBuilder().theme(redAlertTheme).build(),
);

7. Use ILogger for Dependency Injection

// Services depend on ILogger interface
class MyService {
  constructor(private logger: ILogger) {}

  async doWork() {
    this.logger.logInfo("Starting work");
    // ...
  }
}

// Easy to mock in tests
class MockLogger implements ILogger {
  logInfo(message: string) {
    // Assert on calls
  }
  // ...
}

Performance

GenesisTrace is optimized for production use with minimal overhead:

Logging Performance

Lazy Evaluation: Log formatting only happens when log level is enabled
Sub-millisecond Overhead: < 0.1ms overhead when logging is disabled
Efficient Colors: ANSI codes cached and reused
Zero Dependencies: No startup penalty from external packages
Smart History: Circular buffer with O(1) insert, configurable size limits

Memory Efficiency

Configurable History: Set maxHistorySize to control memory usage
Efficient Strings: ANSI codes are constants, not dynamic allocations
No Memory Leaks: Proper cleanup in shutdown() method
Plugin Isolation: Plugins run independently, failures don't affect others

Benchmarks

Typical performance on modern hardware (Apple M1, Linux):

Operation	Time	Notes
Logger creation	< 1ms	One-time cost
Log entry (disabled level)	< 0.1ms	Nearly free
Log entry (enabled)	1-5ms	Depends on metadata size
Table rendering (100 rows)	10-20ms	One-time render
Progress bar update	< 1ms	Visual update
Spinner frame	< 0.5ms	Animation frame
History export (1000 entries)	50-100ms	File I/O bound

Optimization Tips

Disable History in Production: Save memory when not needed
```
new ConfigBuilder().enableHistory(false).build();
```

Set Appropriate Log Levels: Filter early to avoid processing

new ConfigBuilder().logLevel("info").build(); // Skip debug logs

Batch Plugin Operations: Use plugins with batching (RemoteLoggerPlugin)

new RemoteLoggerPlugin({ batchSize: 100, flushInterval: 10000 });

Minimize Metadata: Only include necessary data

// Good - essential data only
logger.info("Request", { method: "GET", path: "/api/users" });

// Avoid - unnecessary data
logger.info("Request", { ...req, ...res, ...allHeaders });

Examples

Complete CLI Tool

import {
  BoxRenderer,
  ConfigBuilder,
  InteractivePrompts,
  Logger,
  neonTheme,
  ProgressBar,
  Spinner,
} from "jsr:@pedromdominguez/genesis-trace";

const logger = new Logger(
  new ConfigBuilder().theme(neonTheme).build(),
);

// Banner
logger.info("=".repeat(60));
logger.info("  DATA PROCESSING TOOL v1.0");
logger.info("=".repeat(60));

// Interactive prompt
const confirmed = await InteractivePrompts.confirm(
  "Start processing?",
  true,
);

if (!confirmed) {
  logger.warning("Operation cancelled");
  Deno.exit(0);
}

// Spinner for loading
const spinner = new Spinner({ message: "Loading data..." });
spinner.start();
await new Promise((resolve) => setTimeout(resolve, 2000));
spinner.succeed("Data loaded!");

// Progress bar for processing
const progress = new ProgressBar({
  total: 100,
  width: 50,
  label: "Processing",
});

for (let i = 0; i <= 100; i += 10) {
  progress.update(i);
  await new Promise((resolve) => setTimeout(resolve, 200));
}

progress.complete("Processing complete!");

// Results in box
BoxRenderer.render(
  [
    "✓ 1,234 records processed",
    "✓ 98 duplicates removed",
    "✓ 5 errors corrected",
    "✓ Results saved to output.json",
  ],
  { title: "Summary", style: "double" },
);

logger.success("All operations completed successfully!");

Production Server with Plugins

import {
  ConfigBuilder,
  FileLoggerPlugin,
  Logger,
  minimalTheme,
  RemoteLoggerPlugin,
  SlackLoggerPlugin,
} from "jsr:@pedromdominguez/genesis-trace";

// Production logger with multiple plugins
const logger = new Logger(
  new ConfigBuilder()
    .theme(minimalTheme)
    .logLevel("info")
    .plugin(
      new FileLoggerPlugin({
        filepath: "./logs/app.log",
        format: "text",
        minLevel: "info",
      }),
    )
    .plugin(
      new FileLoggerPlugin({
        filepath: "./logs/errors.log",
        format: "text",
        minLevel: "error",
      }),
    )
    .plugin(
      new RemoteLoggerPlugin({
        endpoint: "https://logs.example.com/api/logs",
        batchSize: 50,
        flushInterval: 10000,
      }),
    )
    .plugin(
      new SlackLoggerPlugin({
        webhookUrl: Deno.env.get("SLACK_WEBHOOK_URL")!,
        minLevel: "critical",
      }),
    )
    .build(),
);

// Graceful shutdown
Deno.addSignalListener("SIGTERM", async () => {
  logger.info("Received SIGTERM, shutting down...");
  await logger.shutdown();
  Deno.exit(0);
});

// Application code
logger.info("Server starting", { port: 8000 });
// ... server logic

More Examples

Check out the examples/ directory for complete working examples:

basic.ts: Quick start guide
comprehensive.ts: Full feature demonstration
denogenesis-banner.ts: ASCII banner examples
mission-control.ts: Real-world monitoring dashboard
incident-response.ts: Error tracking and alerting
cli-tool.ts: Interactive CLI application
data-pipeline.ts: ETL processing with progress
build-pipeline.ts: Build system with logging

Run examples:

# Basic example
deno run --allow-read --allow-write --allow-env examples/basic.ts

# Comprehensive demo
deno run --allow-read --allow-write --allow-env examples/comprehensive.ts

# CLI tool
deno run --allow-read --allow-write --allow-env examples/cli-tool.ts

Introspection Experiments

The introspection/ directory contains advanced demonstrations showcasing GenesisTrace's full capabilities:

llm-introspection.ts: Complete feature showcase
being_an_llm.ts: Color and theming showcase
llm-thought-process.ts: Structured data visualization
llm-inner-life.ts: Animation and real-time updates

deno run --allow-env --allow-read --allow-write introspection/llm-introspection.ts

Testing

# Run all tests
deno test --allow-read --allow-write --allow-env

# Run specific test file
deno test --allow-read --allow-write --allow-env core/logger.test.ts

# Run with coverage
deno test --coverage --allow-read --allow-write --allow-env

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Ensure tests pass (deno test --allow-all)
Format code (deno fmt)
Lint code (deno lint)
Submit a pull request

License

MIT License - see LICENSE file for details

Author

Pedro M. Dominguez (@grenas405)

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
JSR Package: jsr.io/@pedromdominguez/genesis-trace

Changelog

v1.0.1 (Current)

Removed HTTP framework components (moved to separate library)
Improved documentation with technical depth
Enhanced theme system documentation
Added comprehensive API reference
Performance optimizations for logging

v1.0.0

Initial release
Core logging functionality
Visual components (tables, boxes, progress, charts)
Plugin system with 4 built-in plugins
Theme system with 5 built-in themes
256-color and true color support
Interactive prompts
Comprehensive documentation

Made with ❤️ for the Deno community

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.github/workflows		.github/workflows
adapters		adapters
components		components
core		core
docs		docs
examples		examples
interfaces		interfaces
introspection		introspection
plugins		plugins
themes		themes
utils		utils
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
deno.json		deno.json
deno.lock		deno.lock
jsr.json		jsr.json
mod.ts		mod.ts
test.ts		test.ts

License

grenas405/genesis-trace

Folders and files

Latest commit

History

Repository files navigation

GenesisTrace

Quick Reference

Table of Contents

Why GenesisTrace?

What Makes GenesisTrace Unique?

Philosophy & Design

Core Principles

What Can You Build?

Core Architecture

1. Core Logging (core/)

2. Visual Components (components/)

3. Theme System (themes/)

4. Plugin Architecture (plugins/)

5. Abstractions (interfaces/)

6. Utilities (utils/)

Features Overview

Logging Features

Visual Components

Color System

Configuration

Quick Start

Installation

Basic Usage

Configuration

Structured Logging

Log with Metadata

Child Loggers (Namespaces)

Log History

Log Level Filtering

Color System & Themes

Quick Examples

Features

Visual Components

Tables

Boxes

Progress Indicators

Progress Bar

Spinner

Charts

Banners

Enterprise Banners (ConsoleStyler)

Interactive Prompts

Theme System

Using Built-in Themes

Load Theme by Name

Theme Anatomy

Creating Custom Themes

Built-in Theme Descriptions

Plugin Architecture

Plugin Interface

Built-in Plugins

FileLoggerPlugin

JsonLoggerPlugin

RemoteLoggerPlugin

SlackLoggerPlugin

Creating Custom Plugins

Advanced Usage

Environment-Based Configuration

Dependency Injection with ILogger

Graceful Shutdown

Dynamic Plugin Registration

Runtime Configuration Changes

API Reference

Core Classes

Logger

ConfigBuilder

ColorSystem

Formatter

Visual Components

Types

Best Practices

1. Use Child Loggers for Modules

2. Configure Log Levels by Environment

3. Use Metadata for Structured Logging

1. Core Logging (`core/`)

2. Visual Components (`components/`)

3. Theme System (`themes/`)

4. Plugin Architecture (`plugins/`)

5. Abstractions (`interfaces/`)

6. Utilities (`utils/`)

Packages