effective-progress 0.4.1 → 0.4.2

package/README.md

@@ -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
+
+### Log retention
 
 - `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.
 
-## 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,6 +110,7 @@ import * as Progress from "effective-progress";
 
 const configured = program.pipe(
   Effect.provideService(Progress.RendererConfig, {
+    width: 80,
     maxLogLines: 12,
     nonTtyUpdateStep: 2,
   }),
@@ -120,6 +122,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 +178,40 @@ yield *
   });
 ```
 
+## 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" },
+);
+```
+
+## 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 +241,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.2",
   "description": "Effect-first terminal progress bars with nested multibar support",
   "homepage": "https://github.com/stromseng/effective-progress#readme",
   "bugs": {

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/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";

package/src/renderer/ansi.ts

@@ -0,0 +1,138 @@
+import type { CellWrapMode } from "./types";
+
+const ESC = String.fromCharCode(27);
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]`, "g");
+const RESET_ANSI = "\x1b[0m";
+
+interface AnsiToken {
+  readonly kind: "ansi" | "char";
+  readonly value: string;
+}
+
+const textWidth = (text: string): number => Array.from(text).length;
+
+export const stripAnsi = (text: string): string => text.replace(ANSI_PATTERN, "");
+
+export const visibleWidth = (text: string): number => textWidth(stripAnsi(text));
+
+const tokenizeAnsi = (text: string): ReadonlyArray<AnsiToken> => {
+  const tokens: Array<AnsiToken> = [];
+  let i = 0;
+
+  while (i < text.length) {
+    if (text[i] === "\x1b" && text[i + 1] === "[") {
+      let j = i + 2;
+      while (j < text.length) {
+        const code = text.charCodeAt(j);
+        j += 1;
+        if (code >= 0x40 && code <= 0x7e) {
+          break;
+        }
+      }
+      tokens.push({ kind: "ansi", value: text.slice(i, j) });
+      i = j;
+      continue;
+    }
+
+    const codePoint = text.codePointAt(i);
+    if (codePoint === undefined) {
+      break;
+    }
+
+    const char = String.fromCodePoint(codePoint);
+    tokens.push({ kind: "char", value: char });
+    i += char.length;
+  }
+
+  return tokens;
+};
+
+const fitPlainText = (text: string, width: number, wrapMode: CellWrapMode): string => {
+  const target = Math.max(0, Math.floor(width));
+  if (target <= 0) {
+    return "";
+  }
+
+  const chars = Array.from(text);
+  let result = text;
+
+  if (chars.length > target) {
+    if (wrapMode === "ellipsis") {
+      result = target === 1 ? "…" : `${chars.slice(0, target - 1).join("")}…`;
+    } else {
+      result = chars.slice(0, target).join("");
+    }
+  }
+
+  const currentWidth = textWidth(result);
+  if (currentWidth < target) {
+    result += " ".repeat(target - currentWidth);
+  }
+
+  return result;
+};
+
+const fitAnsiText = (text: string, width: number, wrapMode: CellWrapMode): string => {
+  const target = Math.max(0, Math.floor(width));
+  if (target <= 0) {
+    return "";
+  }
+
+  const tokens = tokenizeAnsi(text);
+  const totalVisible = tokens.reduce((sum, token) => sum + (token.kind === "char" ? 1 : 0), 0);
+
+  if (totalVisible <= target) {
+    const padBy = target - totalVisible;
+    return padBy > 0 ? `${text}${" ".repeat(padBy)}` : text;
+  }
+
+  const keepVisible = wrapMode === "ellipsis" ? Math.max(0, target - 1) : target;
+  let visible = 0;
+  let sawAnsi = false;
+  let output = "";
+
+  for (const token of tokens) {
+    if (token.kind === "ansi") {
+      sawAnsi = true;
+      if (keepVisible > 0 && visible <= keepVisible) {
+        output += token.value;
+      }
+      continue;
+    }
+
+    if (visible >= keepVisible) {
+      break;
+    }
+
+    output += token.value;
+    visible += 1;
+  }
+
+  if (wrapMode === "ellipsis" && target > 0) {
+    output += "…";
+  }
+
+  if (sawAnsi && !output.endsWith(RESET_ANSI)) {
+    output += RESET_ANSI;
+  }
+
+  const padBy = target - visibleWidth(output);
+  if (padBy > 0) {
+    output += " ".repeat(padBy);
+  }
+
+  return output;
+};
+
+export const fitRenderedText = (
+  text: string,
+  width: number,
+  wrapMode: CellWrapMode,
+  isTTY: boolean,
+): string => {
+  const raw = isTTY ? text : stripAnsi(text);
+  if (!isTTY || raw.indexOf("\x1b[") === -1) {
+    return fitPlainText(raw, width, wrapMode);
+  }
+  return fitAnsiText(raw, width, wrapMode);
+};

package/src/renderer/tree.ts

@@ -0,0 +1,68 @@
+import type { TaskSnapshot } from "../types";
+import type { TaskTreeInfo } from "./types";
+
+export interface OrderedTreeTask {
+  readonly snapshot: TaskSnapshot;
+  readonly depth: number;
+}
+
+const treeAncestorPrefix = (tree: TaskTreeInfo): string =>
+  tree.ancestorHasNextSibling
+    .slice(1)
+    .map((hasNext) => (hasNext ? "│  " : "   "))
+    .join("");
+
+export const renderTreePrefix = (tree: TaskTreeInfo): string => {
+  if (tree.depth <= 0) {
+    return "";
+  }
+
+  const ancestor = treeAncestorPrefix(tree);
+  return `${ancestor}${tree.hasNextSibling ? "├─ " : "└─ "}`;
+};
+
+export const computeTreeInfo = (
+  ordered: ReadonlyArray<OrderedTreeTask>,
+): ReadonlyArray<OrderedTreeTask & { readonly tree: TaskTreeInfo }> => {
+  const hasNextSiblingByIndex: Array<boolean> = Array.from({ length: ordered.length }, () => false);
+
+  for (let i = 0; i < ordered.length; i++) {
+    const depth = ordered[i]!.depth;
+    for (let j = i + 1; j < ordered.length; j++) {
+      const candidateDepth = ordered[j]!.depth;
+      if (candidateDepth < depth) {
+        break;
+      }
+      if (candidateDepth === depth) {
+        hasNextSiblingByIndex[i] = true;
+        break;
+      }
+    }
+  }
+
+  const ancestorStateByDepth: Array<boolean> = [];
+
+  return ordered.map((entry, index) => {
+    const depth = entry.depth;
+    ancestorStateByDepth.length = depth;
+
+    const hasChildren =
+      index + 1 < ordered.length &&
+      ordered[index + 1] !== undefined &&
+      ordered[index + 1]!.depth > depth;
+
+    const tree: TaskTreeInfo = {
+      depth,
+      hasNextSibling: hasNextSiblingByIndex[index] ?? false,
+      hasChildren,
+      ancestorHasNextSibling: [...ancestorStateByDepth],
+    };
+
+    ancestorStateByDepth[depth] = hasNextSiblingByIndex[index] ?? false;
+
+    return {
+      ...entry,
+      tree,
+    };
+  });
+};

package/src/renderer/types.ts

@@ -0,0 +1,67 @@
+import type { TaskSnapshot } from "../types";
+
+/**
+ * Defines how a column claims width during the shrink/fit stage.
+ */
+export type ColumnTrack =
+  | {
+      readonly _tag: "Auto";
+    }
+  | {
+      readonly _tag: "Fixed";
+      readonly width: number;
+    }
+  | {
+      readonly _tag: "Fraction";
+      readonly weight: number;
+    };
+
+export const Track = {
+  auto: (): ColumnTrack => ({ _tag: "Auto" }),
+  fixed: (width: number): ColumnTrack => ({
+    _tag: "Fixed",
+    width: Math.max(0, Math.floor(width)),
+  }),
+  fr: (weight = 1): ColumnTrack => ({
+    _tag: "Fraction",
+    weight: Math.max(0.001, weight),
+  }),
+} as const;
+
+/**
+ * Tree relationship metadata for rendering connectors.
+ */
+export interface TaskTreeInfo {
+  readonly depth: number;
+  readonly hasNextSibling: boolean;
+  readonly hasChildren: boolean;
+  readonly ancestorHasNextSibling: ReadonlyArray<boolean>;
+}
+
+export type CellWrapMode = "truncate" | "ellipsis";
+
+export interface ProgressColumnContext {
+  readonly task: TaskSnapshot;
+  readonly depth: number;
+  readonly tree: TaskTreeInfo;
+  readonly now: number;
+  readonly tick: number;
+  readonly isTTY: boolean;
+}
+
+export interface ProgressColumnVariant {
+  readonly measure?: (context: ProgressColumnContext) => number;
+  readonly render: (context: ProgressColumnContext, width: number) => string;
+}
+
+export interface ProgressColumn {
+  readonly id: string;
+  readonly track?: ColumnTrack;
+  readonly minWidth?: number;
+  readonly maxWidth?: number;
+  readonly collapsePriority?: number;
+  readonly wrapMode?: CellWrapMode;
+  readonly measure?: (context: ProgressColumnContext) => number;
+  readonly render: (context: ProgressColumnContext, width: number) => string;
+  readonly variants?: (context: ProgressColumnContext) => ReadonlyArray<ProgressColumnVariant>;
+}