effective-progress 0.4.1 → 0.4.3

package/README.md

@@ -15,7 +15,7 @@
 
 - multiple nested tree-like progress bars
 - spinner support for “we have no idea how long this takes” work
-- clean log rendering alongside progress output, so you can keep using `Console.log` / `Effect.logInfo` without wrecking the UI
+- keep using `Console.log` / `Effect.logInfo` while raw console calls are buffered and replayed through your existing `Console` / logger between frame renders
 - familiar `.all` and `.forEach` APIs — swap `Effect` for `Progress`, get progress bars basically for free
 - flicker-free rendering (in theory) by drawing everything in a single terminal frame
 
@@ -25,7 +25,9 @@
 bun add effective-progress
 ```
 
-This shows the simplest usage: iterate 100 items with a single progress bar.
+## Usage
+
+This shows the simplest usage: iterate items with a single progress bar.
 
 ```ts
 import { Console, Effect } from "effect";
@@ -46,7 +48,7 @@ Effect.runPromise(program);
 
 <img alt="Basic example output" src="docs/images/basic.gif" width="600" />
 
-## Nested example
+### Nested example
 
 Run:
 
@@ -77,30 +79,29 @@ Effect.runPromise(program);
 
 <img alt="Nested example output" src="docs/images/nesting.gif" width="600" />
 
-## Other examples
+### Other examples
 
 - `examples/simpleExample.ts` - low-boilerplate real-world flow
 - `examples/advancedExample.ts` - full API usage with custom config and manual task control
 - `examples/showcase.ts` - nested concurrent tasks, spinner workloads, and mixed Effect/Console logging
 - `examples/performance.ts` - stress-style run with high log volume and deeply nested progress updates
-- `examples/themeDepthPalette.ts` - depth-aware nested theming via `Theme.depthPalette`
-- `examples/twoLineWidthCap.ts` - two-line determinate layout with `maxTaskWidth` clamping
-- `examples/customColorStage.ts` - override `ColorStage` to emit plain (no ANSI) frame output
 
-## Log retention
+## Configuration
+
+### Console replay
 
-- `maxLogLines` on `RendererConfig` controls in-memory log retention.
-- Omitted or set to `0` means no log history is kept in memory.
-- `maxLogLines > 0` keeps only the latest `N` log lines in memory.
+- `Progress.task`, `Progress.all`, and `Progress.forEach` buffer `Console.log`/`Console.dir` calls and replay them through the outer `Console`.
+- Calls are replayed between progress frame renders to avoid tearing the TTY frame.
+- Formatting is controlled by the API consumer's logger/console implementation.
 
-## Configuring renderer and progress bars
+### Configuring renderer and progress bars
 
 Configure global renderer behavior once, and a global base progress bar style:
 
 Defaults:
 
-- determinate layout: `single-line`
-- max task width cap: unset (uses terminal width)
+- columns: `DescriptionColumn`, `BarColumn`, `AmountColumn`, `ElapsedColumn`, `EtaColumn`
+- total progress width: `80`
 - bar width: `40`
 
 ```ts
@@ -109,7 +110,7 @@ import * as Progress from "effective-progress";
 
 const configured = program.pipe(
   Effect.provideService(Progress.RendererConfig, {
-    maxLogLines: 12,
+    width: 80,
     nonTtyUpdateStep: 2,
   }),
   Effect.provideService(Progress.ProgressBarConfig, {
@@ -120,6 +121,49 @@ const configured = program.pipe(
 Effect.runPromise(configured);
 ```
 
+You can customize column order/content Rich-style by providing a `columns` array:
+
+```ts
+const configured = program.pipe(
+  Effect.provideService(Progress.RendererConfig, {
+    columns: [
+      Progress.DescriptionColumn.Default(),
+      Progress.BarColumn.make({ track: Progress.Track.fr(1) }),
+      Progress.AmountColumn.Default(),
+      "•",
+      Progress.ElapsedColumn.Default(),
+      "•",
+      Progress.EtaColumn.Default(),
+    ],
+  }),
+);
+```
+
+For full terminal width rendering, set:
+
+```ts
+Effect.provideService(Progress.RendererConfig, {
+  width: "fullwidth",
+});
+```
+
+Description-specific caps should be configured on `DescriptionColumn` (for example `DescriptionColumn.make({ maxWidth: 40 })`) rather than globally.
+
+Per top-level call, you can override render config via helper APIs:
+
+```ts
+const run = Progress.task(effect, {
+  description: "work",
+  render: {
+    columns: [Progress.DescriptionColumn.Default(), "|", Progress.AmountColumn.Default()],
+  },
+});
+
+const wrapped = Progress.withRenderConfig(run, {
+  columns: [Progress.DescriptionColumn.Default()],
+});
+```
+
 Task-level `progressbar` config is optional and inherits from its parent task (or from global `ProgressBarConfig` for root tasks):
 
 ```ts
@@ -133,6 +177,40 @@ yield *
   });
 ```
 
+## Manual task control
+
+For manual usage, `task` still provides the current `Task` context, while logs continue through your outer `Console`:
+
+```ts
+const program = Progress.task(
+  Effect.gen(function* () {
+    const currentTask = yield* Progress.Task;
+    yield* Console.log("This log is handled by the outer Console", { taskId: currentTask });
+    yield* Effect.sleep("1 second");
+  }),
+  { description: "Manual task" },
+);
+```
+
+## Column customization
+
+Built-in columns are exported as classes with `Default()` and `make()` helpers.  
+You can also pass your own objects/classes implementing `ProgressColumn`:
+
+```ts
+const CustomColumn: Progress.ProgressColumn = {
+  id: "custom",
+  render: () => "extra",
+};
+
+const program = Progress.task(myEffect, {
+  description: "Work",
+  render: {
+    columns: [Progress.DescriptionColumn.Default(), Progress.BarColumn.Default(), CustomColumn],
+  },
+});
+```
+
 ## Terminal service and mocking
 
 `effective-progress` now exposes a `ProgressTerminal` service that controls terminal detection and I/O:
@@ -162,62 +240,6 @@ const program = Progress.task(Effect.sleep("100 millis"), { description: "work"
 );
 ```
 
-## Manual task control
-
-For manual usage, `task` captures logs implicitly and provides the current `Task` context:
-
-```ts
-const program = Progress.task(
-  Effect.gen(function* () {
-    const currentTask = yield* Progress.Task;
-    yield* Console.log("This log is rendered through progress output", { taskId: currentTask });
-    yield* Effect.sleep("1 second");
-  }),
-  { description: "Manual task" },
-);
-```
-
-## Themes and render stages
-
-Coloring is configured through the `Theme` service.
-
-```ts
-import chalk from "chalk";
-import { Effect } from "effect";
-import * as Progress from "effective-progress";
-
-const program = Progress.task(myEffect, { description: "Work" }).pipe(
-  Effect.provideService(
-    Progress.Theme,
-    Progress.Theme.of({
-      styles: {
-        plain: (text) => text,
-        barFill: chalk.hex("#00b894"),
-        barEmpty: chalk.white.dim,
-        barBracket: chalk.rgb(180, 190, 210),
-        spinner: chalk.ansi256(214),
-        statusDone: chalk.greenBright,
-        statusFailed: chalk.redBright.bold,
-        text: chalk.white,
-        units: chalk.whiteBright.bold,
-        eta: chalk.gray,
-        elapsed: chalk.gray,
-        treeConnector: chalk.gray,
-      },
-      depthPalette: (depth, role) => (role === "text" && depth > 0 ? chalk.cyanBright : undefined),
-    }),
-  ),
-);
-```
-
-Render internals are split into overrideable stages:
-
-- `BuildStage`: logical rows/cells/segments
-- `ShrinkStage`: width fitting/collapse
-- `ColorStage`: role -> styled terminal strings
-
-You can replace any stage with `Effect.provideService(...)` while keeping defaults for the rest.
-
 ## Dependencies & package size
 
 This library is designed for CLI workflows, where package size is typically a lower-priority concern. Alongside `effect` though, I will strive to only rely on other high quality packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effective-progress",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Effect-first terminal progress bars with nested multibar support",
   "homepage": "https://github.com/stromseng/effective-progress#readme",
   "bugs": {
@@ -19,6 +19,9 @@
   ],
   "type": "module",
   "module": "index.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -30,18 +33,18 @@
     "format:check": "oxfmt --check ."
   },
   "dependencies": {
-    "chalk": "^5.6.2",
-    "effect": "^3.19.17",
     "es-toolkit": "^1.44.0",
     "type-fest": "^5.4.4"
   },
   "devDependencies": {
     "@effect/language-service": "^0.73.1",
     "@types/bun": "latest",
+    "effect": "^3.19.17",
     "oxfmt": "^0.32.0",
-    "oxlint": "^1.47.0"
+    "oxlint": "^1.47.0",
+    "typescript": "^5"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "effect": "^3.19.17"
   }
 }

package/src/api.ts

@@ -1,20 +1,49 @@
 import { Effect, Exit, Option } from "effect";
 import { dual } from "effect/Function";
 import type { Concurrency } from "effect/Types";
+import type { PartialDeep } from "type-fest";
 import { Progress } from "./runtime";
-import { Task } from "./types";
-import type { AddTaskOptions, TrackOptions } from "./types";
+import { RendererConfig, Task } from "./types";
+import type { AddTaskOptions, RendererConfigShape, TrackOptions } from "./types";
 import { inferTotal } from "./utils";
 
-const provideProgress = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+interface RenderOverrideOptions {
+  readonly render?: PartialDeep<RendererConfigShape>;
+}
+
+const provideProgress = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+  renderConfig: PartialDeep<RendererConfigShape> | undefined,
+) =>
   Effect.gen(function* () {
     const existing = yield* Effect.serviceOption(Progress);
     if (Option.isSome(existing)) {
       return yield* Effect.provideService(effect, Progress, existing.value);
     }
-    return yield* Effect.scoped(effect.pipe(Effect.provide(Progress.Default)));
+    if (renderConfig === undefined) {
+      return yield* Effect.scoped(effect.pipe(Effect.provide(Progress.Default)));
+    }
+
+    return yield* Effect.scoped(
+      effect.pipe(
+        Effect.provide(Progress.Default),
+        Effect.provideService(RendererConfig, renderConfig),
+      ),
+    );
   });
 
+export const withRenderConfig: {
+  <A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    config: PartialDeep<RendererConfigShape>,
+  ): Effect.Effect<A, E, Exclude<R, RendererConfig>>;
+  (
+    config: PartialDeep<RendererConfigShape>,
+  ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, RendererConfig>>;
+} = dual(2, <A, E, R>(effect: Effect.Effect<A, E, R>, config: PartialDeep<RendererConfigShape>) =>
+  Effect.provideService(effect, RendererConfig, config),
+);
+
 export interface EffectExecutionOptions {
   readonly concurrency?: Concurrency;
   readonly batching?: boolean | "inherit";
@@ -26,7 +55,9 @@ export interface EffectAllExecutionOptions extends EffectExecutionOptions {
   readonly mode?: "default" | "validate" | "either";
 }
 
-export type AllOptions = Omit<TrackOptions, "total"> & EffectAllExecutionOptions;
+export type AllOptions = Omit<TrackOptions, "total"> &
+  EffectAllExecutionOptions &
+  RenderOverrideOptions;
 export type AllReturn<
   Arg extends
     | ReadonlyArray<Effect.Effect<any, any, any>>
@@ -46,26 +77,29 @@ export interface ForEachExecutionOptions extends EffectExecutionOptions {
   readonly discard?: false | undefined;
 }
 
-export type ForEachOptions = TrackOptions & ForEachExecutionOptions;
+export type ForEachOptions = TrackOptions & ForEachExecutionOptions & RenderOverrideOptions;
+
+export type TaskOptions = AddTaskOptions & RenderOverrideOptions;
 
 export const task: {
   <A, E, R>(
     effect: Effect.Effect<A, E, R>,
-    options: AddTaskOptions,
+    options: TaskOptions,
   ): Effect.Effect<A, E, Exclude<R, Progress | Task>>;
   <A, E, R>(
-    options: AddTaskOptions,
+    options: TaskOptions,
   ): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Progress | Task>>;
-} = dual(
-  2,
-  <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions) =>
-    provideProgress(
-      Effect.gen(function* () {
-        const progress = yield* Progress;
-        return yield* progress.withTask(effect, options);
-      }),
-    ) as Effect.Effect<A, E, Exclude<R, Progress | Task>>,
-);
+} = dual(2, <A, E, R>(effect: Effect.Effect<A, E, R>, options: TaskOptions) => {
+  const { render, ...taskOptions } = options;
+
+  return provideProgress(
+    Effect.gen(function* () {
+      const progress = yield* Progress;
+      return yield* progress.withTask(effect, taskOptions);
+    }),
+    render,
+  ) as Effect.Effect<A, E, Exclude<R, Progress | Task>>;
+});
 
 type AllArg =
   | ReadonlyArray<Effect.Effect<any, any, any>>
@@ -85,14 +119,14 @@ const countEffects = (effects: AllArg): number =>
 export const all: {
   <const Arg extends AllArg, O extends EffectAllExecutionOptions>(
     effects: Arg,
-    options: Omit<TrackOptions, "total"> & O,
+    options: Omit<TrackOptions, "total"> & O & RenderOverrideOptions,
   ): AllReturn<Arg, O>;
-  <O extends EffectAllExecutionOptions>(
+  <O extends EffectAllExecutionOptions & RenderOverrideOptions>(
     options: Omit<TrackOptions, "total"> & O,
   ): <const Arg extends AllArg>(effects: Arg) => AllReturn<Arg, O>;
 } = dual(
   2,
-  <const Arg extends AllArg, O extends EffectAllExecutionOptions>(
+  <const Arg extends AllArg, O extends EffectAllExecutionOptions & RenderOverrideOptions>(
     effects: Arg,
     options: Omit<TrackOptions, "total"> & O,
   ) =>
@@ -136,6 +170,7 @@ export const all: {
           },
         );
       }),
+      options.render,
     ) as AllReturn<Arg, O>,
 );
 
@@ -195,5 +230,6 @@ export const forEach: {
           },
         );
       }),
+      options.render,
     ) as Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress | Task>>,
 );

package/src/console.ts

@@ -1,85 +1,177 @@
-import { Console, Effect } from "effect";
-import { formatWithOptions } from "node:util";
+import { Console, Effect, Ref } from "effect";
 
-export const makeProgressConsole = (
-  progressLog: (...args: ReadonlyArray<unknown>) => Effect.Effect<void, never, never>,
+export type BufferedConsoleMethod =
+  | "assert"
+  | "debug"
+  | "dir"
+  | "dirxml"
+  | "error"
+  | "group"
+  | "groupCollapsed"
+  | "groupEnd"
+  | "info"
+  | "log"
+  | "table"
+  | "trace"
+  | "warn";
+
+export interface BufferedConsoleCall {
+  readonly method: BufferedConsoleMethod;
+  readonly args: ReadonlyArray<unknown>;
+  readonly unsafe: boolean;
+}
+
+export interface ConsoleBridge {
+  readonly progressConsole: Console.Console;
+  readonly appendLog: (call: BufferedConsoleCall) => Effect.Effect<void, never, never>;
+  readonly replayLogs: (
+    logs: ReadonlyArray<BufferedConsoleCall>,
+  ) => Effect.Effect<void, never, never>;
+  readonly log: (...args: ReadonlyArray<unknown>) => Effect.Effect<void, never, never>;
+}
+
+const replayBufferedConsoleCall = (
   outerConsole: Console.Console,
+  call: BufferedConsoleCall,
+): Effect.Effect<void, never, never> => {
+  type DirOptions = Parameters<Console.Console["dir"]>[1];
+  type GroupOptions = Parameters<Console.Console["group"]>[0];
+
+  switch (call.method) {
+    case "assert": {
+      const [condition, ...rest] = call.args;
+      return outerConsole.assert(condition as boolean, ...rest);
+    }
+    case "debug":
+      return outerConsole.debug(...call.args);
+    case "dir":
+      return outerConsole.dir(call.args[0], call.args[1] as DirOptions);
+    case "dirxml":
+      return outerConsole.dirxml(...call.args);
+    case "error":
+      return outerConsole.error(...call.args);
+    case "group":
+      return outerConsole.group(call.args[0] as GroupOptions);
+    case "groupCollapsed":
+      return outerConsole.group(call.args[0] as GroupOptions);
+    case "groupEnd":
+      return outerConsole.groupEnd;
+    case "info":
+      return outerConsole.info(...call.args);
+    case "log":
+      return outerConsole.log(...call.args);
+    case "table":
+      return outerConsole.table(call.args[0], call.args[1] as ReadonlyArray<string> | undefined);
+    case "trace":
+      return outerConsole.trace(...call.args);
+    case "warn":
+      return outerConsole.warn(...call.args);
+  }
+};
+
+export const makeProgressConsole = (
+  appendLog: (call: BufferedConsoleCall) => Effect.Effect<void, never, never>,
 ): Console.Console => {
-  const log = (...args: ReadonlyArray<unknown>) => progressLog(...args);
-  const unsafeLog = (...args: ReadonlyArray<unknown>) => {
-    Effect.runFork(progressLog(...args));
+  const log = (method: BufferedConsoleMethod, ...args: ReadonlyArray<unknown>) =>
+    appendLog({ method, args, unsafe: false });
+  const unsafeLog = (method: BufferedConsoleMethod, ...args: ReadonlyArray<unknown>) => {
+    Effect.runSync(appendLog({ method, args, unsafe: true }));
   };
 
-  const delegate = (effect: Effect.Effect<void, never, never>) => effect;
-
   return Console.Console.of({
     [Console.TypeId]: Console.TypeId,
-    assert(condition, ...args) {
-      return condition ? Effect.void : log("Assertion failed:", ...args);
-    },
+    assert: (condition, ...args) => log("assert", condition, ...args),
     clear: Effect.void,
     count: (_label) => Effect.void,
     countReset: (_label) => Effect.void,
-    debug: (...args) => log(...args),
-    dir: (item, options) => log(formatWithOptions(options ?? {}, "%O", item)),
-    dirxml: (...args) => log(...args),
-    error: (...args) => log(...args),
-    group: (...args) => log(...args),
-    groupEnd: Effect.void,
-    info: (...args) => log(...args),
-    log: (...args) => log(...args),
-    table: (tabularData, properties) => log(tabularData, properties),
+    debug: (...args) => log("debug", ...args),
+    dir: (item, options) => log("dir", item, options),
+    dirxml: (...args) => log("dirxml", ...args),
+    error: (...args) => log("error", ...args),
+    group: (...args) => log("group", ...args),
+    groupEnd: log("groupEnd"),
+    info: (...args) => log("info", ...args),
+    log: (...args) => log("log", ...args),
+    table: (tabularData, properties) => log("table", tabularData, properties),
     time: (_label) => Effect.void,
     timeEnd: (_label) => Effect.void,
-    timeLog: (_label, ...args) => log(...args),
-    trace: (...args) => delegate(outerConsole.trace(...args)),
-    warn: (...args) => log(...args),
+    timeLog: (_label, ...args) => log("info", ...args),
+    trace: (...args) => log("trace", ...args),
+    warn: (...args) => log("warn", ...args),
     unsafe: {
       assert(condition, ...args) {
-        if (!condition) unsafeLog("Assertion failed:", ...args);
+        unsafeLog("assert", condition, ...args);
       },
       clear() {},
       count(_label) {},
       countReset(_label) {},
       debug(...args) {
-        unsafeLog(...args);
+        unsafeLog("debug", ...args);
       },
       dir(item, options) {
-        unsafeLog(formatWithOptions(options ?? {}, "%O", item));
+        unsafeLog("dir", item, options);
       },
       dirxml(...args) {
-        unsafeLog(...args);
+        unsafeLog("dirxml", ...args);
       },
       error(...args) {
-        unsafeLog(...args);
+        unsafeLog("error", ...args);
       },
       group(...args) {
-        unsafeLog(...args);
+        unsafeLog("group", ...args);
       },
       groupCollapsed(...args) {
-        unsafeLog(...args);
+        unsafeLog("groupCollapsed", ...args);
+      },
+      groupEnd() {
+        unsafeLog("groupEnd");
       },
-      groupEnd() {},
       info(...args) {
-        unsafeLog(...args);
+        unsafeLog("info", ...args);
       },
       log(...args) {
-        unsafeLog(...args);
+        unsafeLog("log", ...args);
       },
       table(tabularData, properties) {
-        unsafeLog(tabularData, properties);
+        unsafeLog("table", tabularData, properties);
       },
       time(_label) {},
       timeEnd(_label) {},
       timeLog(_label, ...args) {
-        unsafeLog(...args);
+        unsafeLog("info", ...args);
       },
       trace(...args) {
-        outerConsole.unsafe.trace(...args);
+        unsafeLog("trace", ...args);
       },
       warn(...args) {
-        unsafeLog(...args);
+        unsafeLog("warn", ...args);
       },
     },
   });
 };
+
+export const makeConsoleBridge = (
+  outerConsole: Console.Console,
+  pendingLogsRef: Ref.Ref<ReadonlyArray<BufferedConsoleCall>>,
+  markDirty: Effect.Effect<void, never, never>,
+): ConsoleBridge => {
+  const appendLog = (call: BufferedConsoleCall) =>
+    call.args.length === 0
+      ? Effect.void
+      : Ref.update(pendingLogsRef, (logs) => [...logs, call]).pipe(Effect.zipRight(markDirty));
+
+  const replayLogs = (logs: ReadonlyArray<BufferedConsoleCall>) =>
+    Effect.forEach(logs, (call) => replayBufferedConsoleCall(outerConsole, call), {
+      discard: true,
+    });
+
+  const log = (...args: ReadonlyArray<unknown>) =>
+    args.length === 0 ? Effect.void : appendLog({ method: "log", args, unsafe: false });
+
+  return {
+    progressConsole: makeProgressConsole(appendLog),
+    appendLog,
+    replayLogs,
+    log,
+  };
+};

package/src/index.ts

@@ -2,5 +2,4 @@ export * from "./api";
 export * from "./renderer";
 export { Progress } from "./runtime";
 export * from "./terminal";
-export * from "./theme";
 export * from "./types";