@visulima/pail 4.0.1 → 4.1.0

package/MIGRATION-GUIDE.md

@@ -0,0 +1,459 @@
+# Migration Guide
+
+This guide documents breaking changes and migration steps for the `@visulima/pail` package.
+
+## Version 4.0.0
+
+### Breaking Changes Summary
+
+- **Spinner removed**: `createSpinner()` and `createMultiSpinner()` removed — use `@visulima/spinner`
+- **Progress bar removed**: `createProgressBar()` and `createMultiProgressBar()` removed — use `@visulima/progress-bar`
+- **Interactive manager extracted**: `@visulima/pail/interactive` export removed — use `@visulima/interactive-manager`
+- **Spinner/progress-bar exports removed**: `@visulima/pail/spinner` and `@visulima/pail/progress-bar` no longer exist
+
+### Install New Packages
+
+```bash
+pnpm add @visulima/spinner @visulima/progress-bar
+```
+
+`@visulima/interactive-manager` is automatically installed as a dependency of both packages and of pail itself.
+
+### Spinner Migration
+
+#### Before (v3.x)
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+
+const spinner = logger.createSpinner({ name: "dots" });
+spinner.start("Loading...");
+spinner.succeed("Done!");
+
+const multi = logger.createMultiSpinner({ name: "dots" });
+const s1 = multi.create("Task 1");
+s1.start();
+s1.succeed("Done");
+multi.stop();
+```
+
+#### After (v4.x)
+
+```typescript
+import { createPail } from "@visulima/pail";
+import { MultiSpinner, Spinner } from "@visulima/spinner";
+
+const logger = createPail({ interactive: true });
+const manager = logger.getInteractiveManager();
+
+const spinner = new Spinner({ name: "dots" }, manager);
+spinner.start("Loading...");
+spinner.succeed("Done!");
+
+const multi = new MultiSpinner({ name: "dots" }, manager);
+const s1 = multi.create("Task 1");
+s1.start();
+s1.succeed("Done");
+multi.stop();
+```
+
+### Progress Bar Migration
+
+#### Before (v3.x)
+
+```typescript
+import { createPail } from "@visulima/pail";
+
+const logger = createPail({ interactive: true });
+
+const bar = logger.createProgressBar({
+    total: 100,
+    format: "Downloading [{bar}] {percentage}%",
+});
+bar.start();
+bar.update(50);
+bar.stop();
+
+const multi = logger.createMultiProgressBar();
+const b1 = multi.create(100);
+b1.update(50);
+multi.stop();
+```
+
+#### After (v4.x)
+
+```typescript
+import { createPail } from "@visulima/pail";
+import { MultiProgressBar, ProgressBar } from "@visulima/progress-bar";
+
+const logger = createPail({ interactive: true });
+const manager = logger.getInteractiveManager();
+
+const bar = new ProgressBar(
+    {
+        total: 100,
+        format: "Downloading [{bar}] {percentage}%",
+    },
+    manager,
+);
+bar.start();
+bar.update(50);
+bar.stop();
+
+const multi = new MultiProgressBar({}, manager);
+const b1 = multi.create(100);
+b1.update(50);
+multi.stop();
+```
+
+### Interactive Manager Migration
+
+#### Before (v3.x)
+
+```typescript
+import { InteractiveManager, InteractiveStreamHook } from "@visulima/pail/interactive";
+```
+
+#### After (v4.x)
+
+```typescript
+import { InteractiveManager, InteractiveStreamHook } from "@visulima/interactive-manager";
+```
+
+### Spinner/Progress-Bar Type Imports
+
+#### Before (v3.x)
+
+```typescript
+import type { SpinnerOptions, SpinnerIcons } from "@visulima/pail";
+import type { ProgressBarOptions, MultiBarOptions } from "@visulima/pail";
+```
+
+#### After (v4.x)
+
+```typescript
+import type { SpinnerOptions, SpinnerIcons } from "@visulima/spinner";
+import type { ProgressBarOptions, MultiBarOptions } from "@visulima/progress-bar";
+```
+
+### Spinner API Changes
+
+The new `@visulima/spinner` package has a few API differences from pail's old spinner:
+
+| Old (pail)                          | New (@visulima/spinner)                            | Notes                                                    |
+| ----------------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
+| `logger.createSpinner(opts)`        | `new Spinner(opts, manager)`                       | Pass manager as 2nd arg                                  |
+| `spinner.fail(text)`                | `spinner.failed(text)`                             | Method renamed                                           |
+| `SpinnerStyle` object with colorize | `style: (text) => string` or `SpinnerStyle` object | Style is now a function or uses Node.js `util.styleText` |
+
+### What Stays the Same
+
+- `getInteractiveManager()` — still available on pail, returns the manager instance
+- Interactive mode — still enabled via `{ interactive: true }`
+- All logging methods — unchanged
+- Reporters — unchanged
+- Processors — unchanged
+- Middleware — unchanged
+
+### Why This Change?
+
+Spinners and progress bars are now **independent packages** that can be used without pail:
+
+- **`@visulima/spinner`** — 109 spinner animations, styling, multi-spinner support
+- **`@visulima/progress-bar`** — 7 styles, gradients, multi-bar, composite mode
+- **`@visulima/interactive-manager`** — terminal stream coordination
+
+This reduces pail's bundle size and allows these features to be used in any CLI tool, not just with pail.
+
+---
+
+## Version 3.0.0
+
+### Breaking Changes Summary
+
+- **Minimum Node.js version**: 20.19+ required
+- **Module format**: ESM-only (CommonJS removed)
+- **Reporter imports**: Changed to granular paths
+- **Internal dependencies**: Consolidated with @visulima/string
+
+### Dependency Consolidation
+
+In version 3.0.0, we consolidated external dependencies by replacing them with internal `@visulima/string` package utilities.
+
+#### Replaced Dependencies
+
+| Previous        | New                                 | Reason                                   |
+| --------------- | ----------------------------------- | ---------------------------------------- |
+| `wrap-ansi`     | `@visulima/string` (wordWrap)       | Consolidated text wrapping functionality |
+| `string-length` | `@visulima/string` (getStringWidth) | Consolidated string width calculation    |
+
+#### Benefits
+
+- **Reduced bundle size**: Fewer external dependencies
+- **Better maintenance**: Internal package control
+- **Consistent API**: Unified string utilities across visulima packages
+- **Performance**: Optimized internal implementations
+
+#### Backward Compatibility
+
+The dependency consolidation changes are **backward compatible** for pail users. The internal API changes don't affect the public pail API. The CJS export removal and reporter export structure changes are **breaking changes** that require migration.
+
+### Reporter Export Structure Changes
+
+The reporter export structure has been reorganized to provide more granular access to individual reporter types.
+
+#### Old Export Structure
+
+```javascript
+import { JsonReporter, JsonFileReporter, PrettyReporter, SimpleReporter } from "@visulima/pail/reporter";
+```
+
+#### New Granular Export Structure
+
+```javascript
+import { JsonReporter } from "@visulima/pail/reporter/json";
+import { JsonFileReporter } from "@visulima/pail/reporter/file";
+import { PrettyReporter } from "@visulima/pail/reporter/pretty";
+import { SimpleReporter } from "@visulima/pail/reporter/simple";
+```
+
+#### Benefits
+
+- **Smaller bundle sizes**: Only import the reporters you need
+- **Better tree-shaking**: Unused reporters are excluded from bundles
+- **Clearer dependencies**: Explicit imports make dependencies obvious
+- **Improved performance**: Reduced bundle size and faster loading
+
+### CommonJS (CJS) Export Removed
+
+The CommonJS (CJS) export has been removed in favor of ECMAScript Modules (ESM) only. For CJS compatibility in Node.js 20.19+, use dynamic imports.
+
+#### Before (v2.x)
+
+```javascript
+// This no longer works
+const { createPail, pail } = require("@visulima/pail");
+```
+
+#### After (v3.x) - Node.js 20.19+
+
+```javascript
+// Use dynamic import for ESM modules from CJS
+const { createPail, pail } = await import("@visulima/pail");
+```
+
+#### Alternative: Convert to ESM
+
+For better compatibility and performance, convert your project to use ESM:
+
+```json
+// package.json
+{
+    "name": "your-project",
+    "type": "module"
+}
+```
+
+```typescript
+// Your files can now use ESM imports
+import { createPail, pail } from "@visulima/pail";
+
+const logger = createPail({
+    reporters: [new JsonReporter()],
+});
+
+logger.info("Hello ESM world!");
+```
+
+### Why ESM Only?
+
+#### Benefits of ESM for Pail
+
+- **Standards Compliance**: ESM follows the official JavaScript module specification
+- **Tree Shaking**: Better dead code elimination in bundlers
+- **Static Analysis**: Improved tooling and IDE support
+- **Future-Proof**: ESM is the standard for modern JavaScript
+- **Bundle Optimization**: Smaller bundle sizes with better optimization
+
+### Migration Steps
+
+#### 1. Update Reporter Imports
+
+Replace old reporter imports with new granular imports:
+
+```javascript
+// Before
+import { JsonReporter, JsonFileReporter, PrettyReporter, SimpleReporter } from "@visulima/pail/reporter";
+
+// After
+import { JsonReporter } from "@visulima/pail/reporter/json";
+import { JsonFileReporter } from "@visulima/pail/reporter/file";
+import { PrettyReporter } from "@visulima/pail/reporter/pretty";
+import { SimpleReporter } from "@visulima/pail/reporter/simple";
+```
+
+#### 2. Use Dynamic Imports for CJS
+
+Replace `require()` calls with dynamic `import()`:
+
+```javascript
+// Before
+const { createPail } = require("@visulima/pail");
+
+// After
+const { createPail } = await import("@visulima/pail");
+```
+
+#### 3. Convert to ESM (Recommended)
+
+For the best experience, convert your project to use ESM:
+
+```json
+// package.json
+{
+    "name": "your-project",
+    "type": "module",
+    "scripts": {
+        "start": "node src/index.js"
+    }
+}
+```
+
+```typescript
+// src/index.ts
+import { createPail, pail } from "@visulima/pail";
+import { JsonReporter } from "@visulima/pail/reporter/json";
+
+async function main() {
+    const logger = createPail({
+        reporters: [new JsonReporter()],
+    });
+
+    logger.info("Project started");
+}
+
+main().catch(console.error);
+```
+
+### Migration Issues & Solutions
+
+#### 1. Old Reporter Imports No Longer Work
+
+**Problem**: `import { JsonReporter } from "@visulima/pail/reporter"` throws "module not found" error.
+
+**Solution**: Use new granular reporter imports:
+
+```javascript
+// Before
+import { JsonReporter, JsonFileReporter, PrettyReporter, SimpleReporter } from "@visulima/pail/reporter";
+
+// After
+import { JsonReporter } from "@visulima/pail/reporter/json";
+import { JsonFileReporter } from "@visulima/pail/reporter/file";
+import { PrettyReporter } from "@visulima/pail/reporter/pretty";
+import { SimpleReporter } from "@visulima/pail/reporter/simple";
+```
+
+#### 2. require() Calls No Longer Work
+
+**Problem**: `require('@visulima/pail')` throws "module not found" error.
+
+**Solution**: Use dynamic imports:
+
+```javascript
+// Dynamic import for ESM modules from CJS
+const { createPail, pail } = await import("@visulima/pail");
+```
+
+#### 3. Async Context Required
+
+**Problem**: Functions using pail must be async when using dynamic imports.
+
+**Solution**: Mark functions as async and await the import:
+
+```typescript
+// Before
+function setupLogger() {
+    const { createPail } = require("@visulima/pail");
+
+    return createPail();
+}
+
+// After
+async function setupLogger() {
+    const { createPail } = await import("@visulima/pail");
+
+    return createPail();
+}
+```
+
+### Verification Steps
+
+1. **Test new reporter imports**:
+
+    ```javascript
+    // test-reporters.mjs
+    import { JsonReporter } from "@visulima/pail/reporter/json";
+    import { JsonFileReporter } from "@visulima/pail/reporter/file";
+    import { PrettyReporter } from "@visulima/pail/reporter/pretty";
+    import { SimpleReporter } from "@visulima/pail/reporter/simple";
+    import { createPail } from "@visulima/pail";
+
+    async function test() {
+        const logger = createPail({
+            reporters: [new JsonReporter(), new JsonFileReporter({ filePath: "/tmp/test.log" }), new PrettyReporter(), new SimpleReporter()],
+        });
+
+        logger.info("All reporter imports successful");
+    }
+
+    test().catch(console.error);
+    ```
+
+2. **Test ESM imports**:
+
+    ```javascript
+    // test.mjs
+    import { createPail } from "@visulima/pail";
+
+    async function test() {
+        const logger = createPail();
+
+        logger.info("ESM import successful");
+    }
+
+    test().catch(console.error);
+    ```
+
+3. **Test dynamic imports from CJS**:
+
+    ```javascript
+    // test.cjs
+    async function test() {
+        const { createPail } = await import("@visulima/pail");
+        const logger = createPail();
+
+        logger.info("Dynamic import successful");
+    }
+
+    test().catch(console.error);
+    ```
+
+### Migration Benefits
+
+#### Reporter Import Benefits
+
+- **Smaller bundle sizes**: Only import the reporters you need
+- **Better tree-shaking**: Unused reporters are excluded from bundles
+- **Clearer dependencies**: Explicit imports make dependencies obvious
+- **Improved performance**: Reduced bundle size and faster loading
+
+#### ESM Migration Benefits
+
+- **Better Performance**: ESM's improved module caching in Node.js 20.19+
+- **Modern JavaScript**: Consistent module syntax across environments
+- **Bundle Optimization**: Better tree-shaking and dead code elimination
+- **Developer Experience**: Improved IDE support and error messages
+- **Future-Proof**: Aligned with JavaScript ecosystem direction

package/README.md

@@ -180,6 +180,23 @@ pail.complete({
 
 ![usage](./__assets__/usage.png)
 
+### Which build `@visulima/pail` resolves to
+
+The `.` entry point picks a build from the export conditions your runtime or bundler sets:
+
+| Runtime                                     | Condition matched        | Build                   | Default reporter       |
+| ------------------------------------------- | ------------------------ | ----------------------- | ---------------------- |
+| Node.js, Bun, Deno (Node compat)            | `import`                 | `dist/index.server.js`  | Pretty (stdout/stderr) |
+| Browsers and bundlers targeting the browser | `browser`                | `dist/index.browser.js` | JSON (console)         |
+| Cloudflare Workers, Vercel Edge             | `workerd` / `edge-light` | `dist/index.browser.js` | JSON (console)         |
+
+The server build writes to `process.stdout` / `process.stderr` and measures the terminal, so it needs
+Node's core modules. Edge runtimes get the console-based build instead, which keeps `.` importable on
+Cloudflare Workers **without** the `nodejs_compat` flag and on Vercel Edge.
+
+Importing `@visulima/pail/server` always gives you the server build, on every runtime — use it only
+where Node core is available (on Cloudflare Workers that means enabling `nodejs_compat`).
+
 ### Custom Loggers
 
 To create a custom logger define an `options` object yielding a types field with the logger data and pass it as argument to the createPail function.

package/dist/error.d.ts

@@ -1,10 +1,10 @@
 /**
-* Options for creating a PailError.
-*
-* Extends standard error properties with self-documenting fields
-* that provide actionable context for debugging, particularly useful
-* for AI-assisted log analysis.
-*/
+ * Options for creating a PailError.
+ *
+ * Extends standard error properties with self-documenting fields
+ * that provide actionable context for debugging, particularly useful
+ * for AI-assisted log analysis.
+ */
 interface PailErrorOptions {
   /** The root cause of this error */
   cause?: unknown;
@@ -20,41 +20,41 @@ interface PailErrorOptions {
   why?: string;
 }
 /**
-* Self-documenting error class for structured logging.
-*
-* Inspired by evlog's structured error approach, PailError extends the native
-* Error class with additional fields that make log entries immediately actionable:
-* - `why`: Explains what caused the failure
-* - `fix`: Suggests how to resolve the issue
-* - `link`: Points to relevant documentation
-* - `status`: HTTP status code for request-related errors
-*
-* These fields are preserved through the logging pipeline and displayed by reporters,
-* making it easier for both humans and AI agents to understand and resolve issues.
-* @example
-* ```typescript
-* import { PailError, createPailError } from "@visulima/pail/error";
-*
-* // Using the class directly
-* throw new PailError({
-*   message: "Payment processing failed",
-*   status: 402,
-*   why: "The customer's card was declined by the payment provider",
-*   fix: "Retry with a different payment method or contact the card issuer",
-*   link: "https://docs.example.com/payments/declined",
-* });
-*
-* // Using the factory function
-* throw createPailError("Connection timeout");
-*
-* // With full options
-* throw createPailError({
-*   message: "Database connection failed",
-*   why: "Connection pool exhausted after 30s timeout",
-*   fix: "Increase pool size or check for connection leaks",
-* });
-* ```
-*/
+ * Self-documenting error class for structured logging.
+ *
+ * Inspired by evlog's structured error approach, PailError extends the native
+ * Error class with additional fields that make log entries immediately actionable:
+ * - `why`: Explains what caused the failure
+ * - `fix`: Suggests how to resolve the issue
+ * - `link`: Points to relevant documentation
+ * - `status`: HTTP status code for request-related errors
+ *
+ * These fields are preserved through the logging pipeline and displayed by reporters,
+ * making it easier for both humans and AI agents to understand and resolve issues.
+ * @example
+ * ```typescript
+ * import { PailError, createPailError } from "@visulima/pail/error";
+ *
+ * // Using the class directly
+ * throw new PailError({
+ *   message: "Payment processing failed",
+ *   status: 402,
+ *   why: "The customer's card was declined by the payment provider",
+ *   fix: "Retry with a different payment method or contact the card issuer",
+ *   link: "https://docs.example.com/payments/declined",
+ * });
+ *
+ * // Using the factory function
+ * throw createPailError("Connection timeout");
+ *
+ * // With full options
+ * throw createPailError({
+ *   message: "Database connection failed",
+ *   why: "Connection pool exhausted after 30s timeout",
+ *   fix: "Increase pool size or check for connection leaks",
+ * });
+ * ```
+ */
 declare class PailError extends Error {
   /** HTTP status code (defaults to 500) */
   readonly status: number;
@@ -66,38 +66,38 @@ declare class PailError extends Error {
   readonly link: string | undefined;
   constructor(options: PailErrorOptions | string);
   /**
-  * Converts the error to a JSON-serializable object.
-  *
-  * Includes all self-documenting fields in the output for structured logging.
-  * @returns A plain object representation of the error
-  */
+   * Converts the error to a JSON-serializable object.
+   *
+   * Includes all self-documenting fields in the output for structured logging.
+   * @returns A plain object representation of the error
+   */
   toJSON(): Record<string, unknown>;
   /**
-  * Returns a formatted string representation including self-documenting fields.
-  * @returns Formatted error string with why/fix/link context
-  */
+   * Returns a formatted string representation including self-documenting fields.
+   * @returns Formatted error string with why/fix/link context
+   */
   override toString(): string;
 }
 /**
-* Factory function for creating PailError instances.
-*
-* A convenient shorthand for creating PailError objects. Accepts either
-* a string message or a full PailErrorOptions object.
-* @param options Error message string or PailErrorOptions object
-* @returns A new PailError instance
-* @example
-* ```typescript
-* import { createPailError } from "@visulima/pail/error";
-*
-* throw createPailError("Something went wrong");
-*
-* throw createPailError({
-*   message: "Auth failed",
-*   status: 401,
-*   why: "Token expired",
-*   fix: "Refresh the authentication token",
-* });
-* ```
-*/
+ * Factory function for creating PailError instances.
+ *
+ * A convenient shorthand for creating PailError objects. Accepts either
+ * a string message or a full PailErrorOptions object.
+ * @param options Error message string or PailErrorOptions object
+ * @returns A new PailError instance
+ * @example
+ * ```typescript
+ * import { createPailError } from "@visulima/pail/error";
+ *
+ * throw createPailError("Something went wrong");
+ *
+ * throw createPailError({
+ *   message: "Auth failed",
+ *   status: 401,
+ *   why: "Token expired",
+ *   fix: "Refresh the authentication token",
+ * });
+ * ```
+ */
 declare const createPailError: (options: PailErrorOptions | string) => PailError;
 export { PailError, type PailErrorOptions, createPailError };