effective-progress 0.4.2 → 0.5.0

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 progress rendering is active
 - 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
 
@@ -82,111 +82,36 @@ Effect.runPromise(program);
 ### Other examples
 
 - `examples/simpleExample.ts` - low-boilerplate real-world flow
-- `examples/advancedExample.ts` - full API usage with custom config and manual task control
+- `examples/advancedExample.ts` - full API usage 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
 
 ## Configuration
 
-### Log retention
+### Console behavior
 
-- `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.
+- The Ink renderer runs with `patchConsole: true`, so console output is patched by Ink while the app is mounted.
+- `Progress.task`, `Progress.all`, and `Progress.forEach` write through the currently provided Effect `Console` implementation.
+- Formatting is controlled by the API consumer's logger/console implementation.
 
-### Configuring renderer and progress bars
+### Ink renderer behavior
 
-Configure global renderer behavior once, and a global base progress bar style:
-
-Defaults:
-
-- columns: `DescriptionColumn`, `BarColumn`, `AmountColumn`, `ElapsedColumn`, `EtaColumn`
-- total progress width: `80`
-- bar width: `40`
-
-```ts
-import { Effect } from "effect";
-import * as Progress from "effective-progress";
-
-const configured = program.pipe(
-  Effect.provideService(Progress.RendererConfig, {
-    width: 80,
-    maxLogLines: 12,
-    nonTtyUpdateStep: 2,
-  }),
-  Effect.provideService(Progress.ProgressBarConfig, {
-    barWidth: 36,
-  }),
-);
-
-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
-yield *
-  progress.withTask(Effect.sleep("1 second"), {
-    description: "Worker pipeline",
-    progressbar: {
-      barWidth: 20,
-      spinnerFrames: [".", "o", "O", "0"],
-    },
-  });
-```
+- Rendering is powered by [Ink](https://github.com/vadimdemedes/ink).
+- Built-in columns are: description, bar, amount/spinner, elapsed, and ETA.
+- Column widths are shared per frame (widest visible cell wins), so rows stay aligned.
+- Elapsed and ETA reserve stable widths to reduce jitter while tasks transition states.
+- Layout uses a 100-column baseline and grows when content requires more space.
+- On narrow terminals, layout compacts to fit available width and tree prefixes are suppressed when description space is too tight.
 
 ## Manual task control
 
-For manual usage, `task` captures logs implicitly and provides the current `Task` context:
+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 rendered through progress output", { taskId: currentTask });
+    yield* Console.log("This log is handled by the outer Console", { taskId: currentTask });
     yield* Effect.sleep("1 second");
   }),
   { description: "Manual task" },
@@ -195,22 +120,7 @@ const program = Progress.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],
-  },
-});
-```
+Custom column APIs are not part of the first Ink release. The renderer ships with built-in columns only, and old renderer config APIs (`RendererConfig`, `ProgressBarConfig`, custom column definitions) are intentionally removed in this iteration.
 
 ## Terminal service and mocking
 
@@ -241,10 +151,6 @@ const program = Progress.task(Effect.sleep("100 millis"), { description: "work"
 );
 ```
 
-## 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.
-
 ## Notes
 
 - As Effect 4.0 is around the corner with some changes to logging, there may be some adjustments needed to align with the new Effect APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effective-progress",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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,21 @@
     "format:check": "oxfmt --check ."
   },
   "dependencies": {
-    "chalk": "^5.6.2",
-    "effect": "^3.19.17",
+    "@types/react": "^19.2.14",
     "es-toolkit": "^1.44.0",
+    "ink": "^6.8.0",
+    "react": "^19.2.4",
     "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,49 +1,20 @@
 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 { RendererConfig, Task } from "./types";
-import type { AddTaskOptions, RendererConfigShape, TrackOptions } from "./types";
+import { Task } from "./types";
+import type { AddTaskOptions, TrackOptions } from "./types";
 import { inferTotal } from "./utils";
 
-interface RenderOverrideOptions {
-  readonly render?: PartialDeep<RendererConfigShape>;
-}
-
-const provideProgress = <A, E, R>(
-  effect: Effect.Effect<A, E, R>,
-  renderConfig: PartialDeep<RendererConfigShape> | undefined,
-) =>
+const provideProgress = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.gen(function* () {
     const existing = yield* Effect.serviceOption(Progress);
     if (Option.isSome(existing)) {
       return yield* Effect.provideService(effect, Progress, existing.value);
     }
-    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),
-      ),
-    );
+    return yield* Effect.scoped(effect.pipe(Effect.provide(Progress.Default)));
   });
 
-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";
@@ -55,9 +26,7 @@ export interface EffectAllExecutionOptions extends EffectExecutionOptions {
   readonly mode?: "default" | "validate" | "either";
 }
 
-export type AllOptions = Omit<TrackOptions, "total"> &
-  EffectAllExecutionOptions &
-  RenderOverrideOptions;
+export type AllOptions = Omit<TrackOptions, "total"> & EffectAllExecutionOptions;
 export type AllReturn<
   Arg extends
     | ReadonlyArray<Effect.Effect<any, any, any>>
@@ -77,9 +46,9 @@ export interface ForEachExecutionOptions extends EffectExecutionOptions {
   readonly discard?: false | undefined;
 }
 
-export type ForEachOptions = TrackOptions & ForEachExecutionOptions & RenderOverrideOptions;
+export type ForEachOptions = TrackOptions & ForEachExecutionOptions;
 
-export type TaskOptions = AddTaskOptions & RenderOverrideOptions;
+export type TaskOptions = AddTaskOptions;
 
 export const task: {
   <A, E, R>(
@@ -90,14 +59,11 @@ export const task: {
     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: TaskOptions) => {
-  const { render, ...taskOptions } = options;
-
   return provideProgress(
     Effect.gen(function* () {
       const progress = yield* Progress;
-      return yield* progress.withTask(effect, taskOptions);
+      return yield* progress.withTask(effect, options);
     }),
-    render,
   ) as Effect.Effect<A, E, Exclude<R, Progress | Task>>;
 });
 
@@ -119,14 +85,14 @@ const countEffects = (effects: AllArg): number =>
 export const all: {
   <const Arg extends AllArg, O extends EffectAllExecutionOptions>(
     effects: Arg,
-    options: Omit<TrackOptions, "total"> & O & RenderOverrideOptions,
+    options: Omit<TrackOptions, "total"> & O,
   ): AllReturn<Arg, O>;
-  <O extends EffectAllExecutionOptions & RenderOverrideOptions>(
+  <O extends EffectAllExecutionOptions>(
     options: Omit<TrackOptions, "total"> & O,
   ): <const Arg extends AllArg>(effects: Arg) => AllReturn<Arg, O>;
 } = dual(
   2,
-  <const Arg extends AllArg, O extends EffectAllExecutionOptions & RenderOverrideOptions>(
+  <const Arg extends AllArg, O extends EffectAllExecutionOptions>(
     effects: Arg,
     options: Omit<TrackOptions, "total"> & O,
   ) =>
@@ -166,11 +132,9 @@ export const all: {
             description: options.description,
             total: countEffects(effects),
             transient: options.transient,
-            progressbar: options.progressbar,
           },
         );
       }),
-      options.render,
     ) as AllReturn<Arg, O>,
 );
 
@@ -226,10 +190,8 @@ export const forEach: {
             description: options.description,
             total: options.total ?? inferTotal(iterable),
             transient: options.transient,
-            progressbar: options.progressbar,
           },
         );
       }),
-      options.render,
     ) as Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress | Task>>,
 );

package/src/index.ts

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

package/src/ink-renderer/app.tsx

@@ -0,0 +1,31 @@
+import { Box } from "ink";
+import { computeSharedColumnWidths } from "./layout";
+import { TaskRow } from "./task-row";
+import type { TaskRowModel } from "./types";
+
+export interface ProgressAppProps {
+  readonly rows: ReadonlyArray<TaskRowModel>;
+  readonly now: number;
+  readonly tick: number;
+  readonly isTTY: boolean;
+  readonly terminalColumns?: number;
+}
+
+export const ProgressApp = ({ rows, now, tick, isTTY, terminalColumns }: ProgressAppProps) => {
+  const widths = computeSharedColumnWidths(rows, now, tick, terminalColumns);
+
+  return (
+    <Box flexDirection="column">
+      {rows.map((row) => (
+        <TaskRow
+          key={row.task.id as number}
+          row={row}
+          now={now}
+          tick={tick}
+          isTTY={isTTY}
+          widths={widths}
+        />
+      ))}
+    </Box>
+  );
+};

package/src/ink-renderer/columns/amount-column.tsx

@@ -0,0 +1,17 @@
+import { Text } from "ink";
+import { formatAmount } from "../format";
+import type { ColumnProps } from "./types";
+
+export const AmountColumn = ({ task, tick }: ColumnProps) => {
+  const text = formatAmount(task, tick);
+  const color =
+    task.status === "failed"
+      ? "red"
+      : task.status === "done"
+        ? "green"
+        : task.units._tag === "DeterminateTaskUnits"
+          ? "whiteBright"
+          : "yellow";
+
+  return <Text color={color}>{text}</Text>;
+};

package/src/ink-renderer/columns/bar-column.tsx

@@ -0,0 +1,31 @@
+import { Text } from "ink";
+import type { ColumnProps } from "./types";
+
+const clamp = (value: number, minimum: number, maximum: number): number =>
+  Math.min(Math.max(value, minimum), maximum);
+
+export interface BarColumnProps extends ColumnProps {
+  readonly width: number;
+}
+
+export const BarColumn = ({ task, width }: BarColumnProps) => {
+  if (task.units._tag !== "DeterminateTaskUnits") {
+    return <Text />;
+  }
+
+  const barWidth = Math.max(1, Math.floor(width));
+  const safeTotal = Math.max(1, task.units.total);
+  const ratio = task.status === "done" ? 1 : clamp(task.units.completed / safeTotal, 0, 1);
+  const filled = Math.round(barWidth * ratio);
+  const empty = Math.max(0, barWidth - filled);
+  const bar = `${"━".repeat(filled)}${"─".repeat(empty)}`;
+
+  const color =
+    task.status === "failed" ? "red" : task.status === "done" ? "green" : "blue";
+
+  return (
+    <Text wrap="truncate-end" color={color}>
+      {bar}
+    </Text>
+  );
+};

package/src/ink-renderer/columns/description-column.tsx

@@ -0,0 +1,7 @@
+import { Text } from "ink";
+import { renderTreePrefix } from "../tree";
+import type { ColumnProps } from "./types";
+
+export const DescriptionColumn = ({ task, tree, showTree }: ColumnProps) => (
+  <Text wrap="truncate-end">{`${showTree ? renderTreePrefix(tree) : ""}${task.description}`}</Text>
+);

package/src/ink-renderer/columns/elapsed-column.tsx

@@ -0,0 +1,7 @@
+import { Text } from "ink";
+import { formatElapsed } from "../format";
+import type { ColumnProps } from "./types";
+
+export const ElapsedColumn = ({ task, now }: ColumnProps) => (
+  <Text color="gray">{formatElapsed(task, now)}</Text>
+);

package/src/ink-renderer/columns/eta-column.tsx

@@ -0,0 +1,18 @@
+import { Text } from "ink";
+import { formatEta } from "../format";
+import type { ColumnProps } from "./types";
+
+export const EtaColumn = ({ task, now }: ColumnProps) => {
+  if (task.status !== "running" || task.units._tag !== "DeterminateTaskUnits") {
+    return <Text />;
+  }
+
+  const eta = formatEta(task, now);
+  const text = eta.length > 0 ? `ETA: ${eta}` : "ETA: --";
+
+  return (
+    <Text wrap="truncate-end" color="gray">
+      {text}
+    </Text>
+  );
+};

package/src/ink-renderer/columns/index.ts

@@ -0,0 +1,6 @@
+export { AmountColumn } from "./amount-column";
+export { BarColumn } from "./bar-column";
+export { DescriptionColumn } from "./description-column";
+export { ElapsedColumn } from "./elapsed-column";
+export { EtaColumn } from "./eta-column";
+export type { ColumnProps } from "./types";

package/src/ink-renderer/columns/types.ts

@@ -0,0 +1,11 @@
+import type { TaskSnapshot } from "../../types";
+import type { TaskTreeInfo } from "../types";
+
+export interface ColumnProps {
+  readonly task: TaskSnapshot;
+  readonly tree: TaskTreeInfo;
+  readonly now: number;
+  readonly tick: number;
+  readonly isTTY: boolean;
+  readonly showTree: boolean;
+}

package/src/ink-renderer/format.ts

@@ -0,0 +1,55 @@
+import type { TaskSnapshot } from "../types";
+
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export const formatDurationSeconds = (seconds: number): string => {
+  const value = Math.max(0, Math.floor(seconds));
+  if (value < 60) {
+    return `${value}s`;
+  }
+  if (value < 3600) {
+    const mins = Math.floor(value / 60);
+    const secs = value % 60;
+    return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
+  }
+
+  const hours = Math.floor(value / 3600);
+  const mins = Math.floor((value % 3600) / 60);
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+};
+
+export const formatElapsed = (task: TaskSnapshot, now: number): string => {
+  const elapsedMillis = Math.max(0, (task.completedAt ?? now) - task.startedAt);
+  return formatDurationSeconds(elapsedMillis / 1000);
+};
+
+export const formatEta = (task: TaskSnapshot, now: number): string => {
+  if (task.status !== "running" || task.units._tag !== "DeterminateTaskUnits") {
+    return "";
+  }
+
+  const { completed, total } = task.units;
+  const remaining = total - completed;
+  if (completed <= 0 || remaining <= 0) {
+    return "";
+  }
+
+  const elapsedMillis = Math.max(1, now - task.startedAt);
+  const etaMillis = Math.max(0, Math.floor((elapsedMillis / completed) * remaining));
+  return formatDurationSeconds(etaMillis / 1000);
+};
+
+export const formatAmount = (task: TaskSnapshot, tick: number): string => {
+  if (task.units._tag === "DeterminateTaskUnits") {
+    const totalText = `${task.units.total}`;
+    const completedText = `${task.units.completed}`.padStart(totalText.length, " ");
+    return `${completedText}/${totalText}`;
+  }
+
+  if (task.status === "running") {
+    const frameIndex = (task.units.spinnerFrame + tick) % SPINNER_FRAMES.length;
+    return SPINNER_FRAMES[frameIndex] ?? SPINNER_FRAMES[0]!;
+  }
+
+  return task.status === "done" ? "✓" : "✗";
+};

package/src/ink-renderer/index.ts

@@ -0,0 +1 @@
+export { InkRenderer, type InkRendererService } from "./service";