@genzai/logging

Logging middleware for code generation with progress tracking and file operation visibility.

Installation

npm install @genzai/logging @genzai/core
# or
pnpm add @genzai/logging @genzai/core
# or
yarn add @genzai/logging @genzai/core

Overview

@genzai/logging provides middleware for logging file operations during code generation. It tracks which files are being written, how long operations take, and provides visibility into the generation process.

Features

• 📝 Operation Logging: Log file and folder operations
• ⏱️ Performance Tracking: Measure operation duration
• 🔌 Easy Integration: Drop-in middleware for @genzai/core
• 🎯 Simple API: Just add to middleware pipeline

Quick Start

import { write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";

await write(plan, "./output", [], {
  middlewares: [loggingMiddleware],
});

Output:

Writing: /path/to/output/index.ts
Completed: /path/to/output/index.ts (12ms)
Writing: /path/to/output/config.json
Completed: /path/to/output/config.json (5ms)

API Reference

loggingMiddleware

Middleware that logs file operations and their duration.

import { loggingMiddleware } from "@genzai/logging";
import { write } from "@genzai/core";

await write(nodes, "./output", [], {
  middlewares: [loggingMiddleware],
});

Usage Examples

Basic Usage

import { file, folder, write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";

const generator = folder(
  "my-project",
  file("README.md", () => "# My Project"),
  file("index.ts", () => "export const main = () => {};")
);

const plan = await generator({});

await write(plan, "./output", [], {
  middlewares: [loggingMiddleware],
});

With Multiple Middleware

import { write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";
import { slotMiddleware } from "@genzai/slots";
import { mergeStrategyMiddleware } from "@genzai/merge-strategy";

await write(plan, "./output", [], {
  middlewares: [
    loggingMiddleware,        // Log at the start
    mergeStrategyMiddleware,
    slotMiddleware,
  ],
});

This will log operations as they happen, giving you visibility into the entire pipeline.

How It Works

1. Before Write: Logs the file path and starts a timer
2. Proceed: Calls next() to continue the middleware chain
3. After Write: Logs completion with duration

The middleware wraps the entire operation, so it includes time spent in all downstream middleware and the actual write operation.

Output Format

Writing: <absolute-path>
Completed: <absolute-path> (<duration>ms)

Example:

Writing: /Users/john/project/src/index.ts
Completed: /Users/john/project/src/index.ts (15ms)
Writing: /Users/john/project/src/lib.ts
Completed: /Users/john/project/src/lib.ts (8ms)

Future Enhancements

The current implementation provides basic logging. Future versions may include:

• 🌳 Tree View: Hierarchical display of folder structure
• 📊 Progress Bar: Visual progress indication
• 📈 Statistics: Total files written, total time, etc.
• 🎨 Colored Output: Enhanced terminal formatting
• 🔇 Log Levels: Configurable verbosity
• 📁 Folder Operations: Explicit folder creation logging

See the TODO in the source code for more planned features.

Best Practices

1. Place Early: Put logging middleware early in the chain to capture full duration
2. Development: Great for development to see what's being generated
3. Debugging: Helps identify slow operations or issues in the pipeline
4. CI/CD: Useful in build pipelines to track generation steps

Middleware Order

The order of middleware affects what gets logged. Consider:

// This logs the full operation time including all middleware
middlewares: [
  loggingMiddleware,
  slowMiddleware,        // Time included in log
]

// This only logs the write operation time
middlewares: [
  slowMiddleware,
  loggingMiddleware,     // Doesn't include slowMiddleware time
]

Related Packages

• @genzai/core - Core generation framework (required)
• @genzai/slots - Slot-based content preservation
• @genzai/merge-strategy - File conflict resolution
• @genzai/prettier - Code formatting middleware

License

MIT