effective-progress 0.1.0 → 0.1.3

package/README.md

@@ -1,11 +1,23 @@
 # effective-progress
 
-`effective-progress` is an Effect-first terminal progress library with:
+[![npm version](https://img.shields.io/npm/v/effective-progress)](https://www.npmjs.com/package/effective-progress)
+
+> [!WARNING]
+> Pre-`1.0.0`, breaking changes may happen in any release. SemVer guarantees will begin at `1.0.0`.
+> I recommend using only the `Progress.all` and `Progress.forEach` APIs for now, as they will likely change the least. The lower-level APIs for manual progress bar control are more likely to see breaking changes as I iterate on the design.
+>
+> Please open an issue or reach out if you have any questions or want to contribute!
+> Feedback and contributions are very welcome!
+
+<img alt="Showcase output" src="docs/images/showcase.gif" width="600" />
+
+`effective-progress` is an [Effect](https://effect.website/)-first terminal progress library with:
 
 - multiple progress bars
 - nested child progress bars
 - spinner support for indeterminate work
-- clean log rendering alongside progress output
+- clean log rendering alongside progress output, allowing you to simply use Effects `Console.log` or `Effect.logInfo`.
+- simple to use `.all` and `.forEach` APIs similar to the ones you already know and love from `effect`. Just swap `Effect` for `Progress` and get progress bars for free!
 
 ## Install
 
@@ -26,18 +38,13 @@ const program = Progress.all(
       yield* Console.log(`Completed task ${i + 1}`);
     }),
   ),
-  { description: "Running tasks in parallel", all: { concurrency: 2 } },
+  { description: "Running tasks in parallel", concurrency: 2 },
 );
 
 Effect.runPromise(program);
 ```
 
-```bash
-bun run examples/basic.ts
-Completed task 1
-Completed task 2
-- Running tasks in parallel: ━━━━━━━━━━━━────────────────── 2/5  40%
-```
+<img alt="Basic example output" src="docs/images/basic.gif" width="600" />
 
 ## Nested example
 
@@ -62,25 +69,128 @@ const program = Progress.all(
       ),
     ),
   ),
-  { description: "Running tasks in parallel", all: { concurrency: 2 } },
+  { description: "Running tasks in parallel", concurrency: 2 },
 );
 
 Effect.runPromise(program);
 ```
 
-```bash
-❯ bun run examples/nesting.ts
-- Running tasks in parallel: ━━━━━━━━━━━━────────────────── 2/5  40%
-  - Running subtasks for task 3: ━━━━━━━━────────────────────── 4/15  27%
-  - Running subtasks for task 4: ━━━━━━━━────────────────────── 4/15  27%
-```
+<img alt="Nested example output" src="docs/images/nesting.gif" width="600" />
 
 ## 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
+
+## 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
+
+Configure global renderer behavior once, and a global base progress bar style:
+
+```ts
+import { Effect } from "effect";
+import * as Progress from "effective-progress";
+
+const configured = program.pipe(
+  Effect.provideService(Progress.RendererConfig, {
+    maxLogLines: 12,
+    nonTtyUpdateStep: 2,
+  }),
+  Effect.provideService(Progress.ProgressBarConfig, {
+    barWidth: 36,
+    colors: {
+      fill: { kind: "hex", value: "#00b894" },
+      spinner: { kind: "ansi256", value: 214 },
+    },
+  }),
+);
+
+Effect.runPromise(configured);
+```
+
+Task-level `progressbar` config is optional and inherits from its parent task (or from global `ProgressBarConfig` for root tasks):
+
+```ts
+yield *
+  progress.withTask(
+    {
+      description: "Worker pipeline",
+      progressbar: {
+        barWidth: 20,
+        spinnerFrames: [".", "o", "O", "0"],
+        colors: {
+          spinner: { kind: "named", value: "magentaBright" },
+        },
+      },
+    },
+    () => Effect.sleep("1 second"),
+  );
+```
+
+For manual service usage, capture logs explicitly:
+
+```ts
+const program = Progress.provide(
+  Effect.gen(function* () {
+    const progress = yield* Progress.Progress;
+
+    yield* progress.withTask({ description: "Manual task" }, () =>
+      progress.withCapturedLogs(
+        Effect.gen(function* () {
+          yield* Console.log("This log is rendered through progress output");
+          yield* Effect.sleep("1 second");
+        }),
+      ),
+    );
+  }),
+);
+```
+
+## Progress bar colors
+
+`progressbar.colors` is configured with typed color tokens that are validated by Effect Schema.
+
+```ts
+progressbar: {
+  spinnerFrames: ["-", "\\", "|", "/"],
+  barWidth: 30,
+  fillChar: "━",
+  emptyChar: "─",
+  leftBracket: "",
+  rightBracket: "",
+  colors: {
+    fill: { kind: "named", value: "cyan" },
+    empty: { kind: "hex", value: "#9ca3af", modifiers: ["dim"] },
+    brackets: { kind: "rgb", value: { r: 156, g: 163, b: 175 } },
+    percent: { kind: "named", value: "whiteBright", modifiers: ["bold"] },
+    spinner: { kind: "ansi256", value: 214 },
+    done: { kind: "named", value: "greenBright" },
+    failed: { kind: "named", value: "redBright", modifiers: ["bold"] },
+  },
+}
+```
+
+Supported color styles:
+
+- `named` (for example `cyan`, `greenBright`)
+- `hex` (for example `#00b894`)
+- `rgb` (for example `{ r: 0, g: 184, b: 148 }`)
+- `ansi256` (for example `214`)
+
+Supported modifiers:
+
+- `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+
+## Dependencies & package size
+
+This library is designed for CLI workflows, where package size is typically a lower-priority concern. Alongside `effect`, it relies on two mature runtime dependencies: `chalk` and `es-toolkit`.
 
 ## Notes
 
-- This is a WIP library, so expect breaking changes. Feedback and contributions are very welcome!
 - 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,37 +1,44 @@
 {
   "name": "effective-progress",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Effect-first terminal progress bars with nested multibar support",
+  "homepage": "https://github.com/stromseng/effective-progress#readme",
+  "bugs": {
+    "url": "https://github.com/stromseng/effective-progress/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stromseng/effective-progress.git"
   },
-  "bugs": {
-    "url": "https://github.com/stromseng/effective-progress/issues"
-  },
-  "homepage": "https://github.com/stromseng/effective-progress#readme",
-  "type": "module",
-  "module": "index.ts",
   "files": [
     "index.ts",
     "src",
     "README.md",
     "LICENSE"
   ],
+  "type": "module",
+  "module": "index.ts",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "prepare": "effect-language-service patch"
+    "prepare": "effect-language-service patch",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check ."
   },
   "dependencies": {
-    "@effect/language-service": "^0.73.1",
     "chalk": "^5.6.2",
-    "effect": "^3.19.16"
+    "effect": "^3.19.16",
+    "es-toolkit": "^1.44.0",
+    "type-fest": "^5.4.4"
   },
   "devDependencies": {
+    "@effect/language-service": "^0.73.1",
     "@types/bun": "latest",
+    "oxfmt": "^0.32.0",
     "oxlint": "^1.47.0"
   },
   "peerDependencies": {

package/src/api.ts

@@ -1,134 +1,115 @@
-import { Console, Effect, Option } from "effect";
-import { makeProgressConsole } from "./console";
+import { Effect, Option } from "effect";
+import type { Concurrency } from "effect/Types";
 import { makeProgressService } from "./runtime";
 import { Progress } from "./types";
 import type { TrackOptions } from "./types";
+import { inferTotal } from "./utils";
 
-export interface TrackEffectsOptions {
-  readonly description: string;
-  readonly total?: number;
-  readonly transient?: boolean;
-  readonly all?: {
-    readonly concurrency?: number | "unbounded";
-    readonly batching?: boolean | "inherit";
-    readonly concurrentFinalizers?: boolean;
-  };
+export interface EffectExecutionOptions {
+  readonly concurrency?: Concurrency;
+  readonly batching?: boolean | "inherit";
+  readonly concurrentFinalizers?: boolean;
 }
 
-export interface ForEachOptions extends TrackOptions {
-  readonly forEach?: {
-    readonly concurrency?: number | "unbounded";
-    readonly batching?: boolean | "inherit";
-    readonly concurrentFinalizers?: boolean;
-  };
+export interface EffectAllExecutionOptions extends EffectExecutionOptions {
+  readonly discard?: boolean;
+  readonly mode?: "default" | "validate" | "either";
 }
 
-const inferTotal = (iterable: Iterable<unknown>): number | undefined => {
-  if (Array.isArray(iterable)) {
-    return iterable.length;
-  }
+export type AllOptions = Omit<TrackOptions, "total"> & EffectAllExecutionOptions;
+export type AllReturn<
+  Arg extends ReadonlyArray<Effect.Effect<any, any, any>>,
+  O extends EffectAllExecutionOptions,
+> =
+  [Effect.All.ReturnTuple<Arg, Effect.All.IsDiscard<O>, Effect.All.ExtractMode<O>>] extends
+    [Effect.Effect<infer A, infer E, infer R>] ? Effect.Effect<A, E, Exclude<R, Progress>>
+  : never;
 
-  if (typeof iterable === "string") {
-    return iterable.length;
-  }
-
-  const candidate = iterable as { length?: unknown; size?: unknown };
-  if (typeof candidate.length === "number") {
-    return candidate.length;
-  }
-
-  if (typeof candidate.size === "number") {
-    return candidate.size;
-  }
+export interface ForEachExecutionOptions extends EffectExecutionOptions {
+  readonly discard?: false | undefined;
+}
 
-  return undefined;
-};
+export type ForEachOptions = TrackOptions & ForEachExecutionOptions;
 
-export const withProgressService = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+export const provide = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   Effect.gen(function* () {
-    const outerConsole = yield* Console.consoleWith((console) => Effect.succeed(console));
     const existing = yield* Effect.serviceOption(Progress);
     if (Option.isSome(existing)) {
-      const console = makeProgressConsole(existing.value, outerConsole);
-      return yield* Effect.withConsole(
-        Effect.provideService(effect, Progress, existing.value),
-        console,
-      );
+      return yield* Effect.provideService(effect, Progress, existing.value);
     }
 
     return yield* Effect.scoped(
       Effect.gen(function* () {
         const service = yield* makeProgressService;
-        const console = makeProgressConsole(service, outerConsole);
-        return yield* Effect.withConsole(Effect.provideService(effect, Progress, service), console);
+        return yield* Effect.provideService(effect, Progress, service);
       }),
     );
   });
 
-export const all = <A, E, R>(
-  effects: ReadonlyArray<Effect.Effect<A, E, R>>,
-  options: TrackEffectsOptions,
-): Effect.Effect<ReadonlyArray<A>, E, Exclude<R, Progress>> =>
-  withProgressService(
+export const all = <
+  const Arg extends ReadonlyArray<Effect.Effect<any, any, any>>,
+  O extends EffectAllExecutionOptions,
+>(
+  effects: Arg,
+  options: Omit<TrackOptions, "total"> & O,
+): AllReturn<Arg, O> =>
+  provide(
     Effect.gen(function* () {
       const progress = yield* Progress;
       return yield* progress.withTask(
         {
           description: options.description,
-          total: options.total ?? effects.length,
+          total: effects.length,
           transient: options.transient,
+          progressbar: options.progressbar,
         },
         (taskId) =>
-          Effect.forEach(
-            effects.map((effect) => Effect.tap(effect, () => progress.advanceTask(taskId, 1))),
-            (effect) => effect,
+          Effect.all(
+            effects.map((effect) =>
+              Effect.tap(progress.withCapturedLogs(effect), () => progress.advanceTask(taskId, 1)),
+            ),
             {
-              concurrency: options.all?.concurrency,
-              batching: options.all?.batching,
-              concurrentFinalizers: options.all?.concurrentFinalizers,
+              concurrency: options.concurrency,
+              batching: options.batching,
+              discard: options.discard,
+              mode: options.mode,
+              concurrentFinalizers: options.concurrentFinalizers,
             },
           ),
       );
     }),
-  );
+  ) as AllReturn<Arg, O>;
 
 export const forEach = <A, B, E, R>(
   iterable: Iterable<A>,
   f: (item: A, index: number) => Effect.Effect<B, E, R>,
   options: ForEachOptions,
 ): Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress>> =>
-  withProgressService(
+  provide(
     Effect.gen(function* () {
       const progress = yield* Progress;
 
-      const items = Array.from(iterable);
-      const total = options.total ?? inferTotal(iterable);
-
       return yield* progress.withTask(
         {
           description: options.description,
-          total,
+          total: options.total ?? inferTotal(iterable),
           transient: options.transient,
+          progressbar: options.progressbar,
         },
         (taskId) =>
           Effect.forEach(
-            items,
-            (item, index) => Effect.tap(f(item, index), () => progress.advanceTask(taskId, 1)),
+            iterable,
+            (item, index) =>
+              Effect.tap(progress.withCapturedLogs(f(item, index)), () =>
+                progress.advanceTask(taskId, 1),
+              ),
             {
-              concurrency: options.forEach?.concurrency,
-              batching: options.forEach?.batching,
-              concurrentFinalizers: options.forEach?.concurrentFinalizers,
+              concurrency: options.concurrency,
+              batching: options.batching,
+              discard: options.discard,
+              concurrentFinalizers: options.concurrentFinalizers,
             },
           ),
       );
     }),
   );
-
-export const trackProgress = all;
-
-export const track = <A, B, E, R>(
-  iterable: Iterable<A>,
-  options: TrackOptions,
-  f: (item: A, index: number) => Effect.Effect<B, E, R>,
-): Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress>> =>
-  forEach(iterable, f, options);

package/src/colors.ts

@@ -0,0 +1,206 @@
+import chalk from "chalk";
+import type { ChalkInstance } from "chalk";
+import { Schema } from "effect";
+
+export const StyleModifierSchema = Schema.Literal(
+  "bold",
+  "dim",
+  "italic",
+  "underline",
+  "inverse",
+  "hidden",
+  "strikethrough",
+);
+export type StyleModifier = typeof StyleModifierSchema.Type;
+
+export const NamedColorSchema = Schema.Literal(
+  "black",
+  "red",
+  "green",
+  "yellow",
+  "blue",
+  "magenta",
+  "cyan",
+  "white",
+  "blackBright",
+  "redBright",
+  "greenBright",
+  "yellowBright",
+  "blueBright",
+  "magentaBright",
+  "cyanBright",
+  "whiteBright",
+);
+export type NamedColor = typeof NamedColorSchema.Type;
+
+const HexColorSchema = Schema.String.pipe(Schema.pattern(/^#(?:[A-Fa-f0-9]{3}|[A-Fa-f0-9]{6})$/));
+const ColorChannelSchema = Schema.Number.pipe(
+  Schema.int(),
+  Schema.greaterThanOrEqualTo(0),
+  Schema.lessThanOrEqualTo(255),
+);
+const Ansi256Schema = Schema.Number.pipe(
+  Schema.int(),
+  Schema.greaterThanOrEqualTo(0),
+  Schema.lessThanOrEqualTo(255),
+);
+const ModifiersSchema = Schema.optional(Schema.Array(StyleModifierSchema));
+
+export const NamedColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("named"),
+  value: NamedColorSchema,
+  modifiers: ModifiersSchema,
+});
+
+export const HexColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("hex"),
+  value: HexColorSchema,
+  modifiers: ModifiersSchema,
+});
+
+export const RgbColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("rgb"),
+  value: Schema.Struct({
+    r: ColorChannelSchema,
+    g: ColorChannelSchema,
+    b: ColorChannelSchema,
+  }),
+  modifiers: ModifiersSchema,
+});
+
+export const Ansi256ColorStyleSchema = Schema.Struct({
+  kind: Schema.Literal("ansi256"),
+  value: Ansi256Schema,
+  modifiers: ModifiersSchema,
+});
+
+export const ColorStyleSchema = Schema.Union(
+  NamedColorStyleSchema,
+  HexColorStyleSchema,
+  RgbColorStyleSchema,
+  Ansi256ColorStyleSchema,
+);
+export type ColorStyle = typeof ColorStyleSchema.Type;
+
+export const ProgressBarColorsSchema = Schema.Struct({
+  fill: ColorStyleSchema,
+  empty: ColorStyleSchema,
+  brackets: ColorStyleSchema,
+  percent: ColorStyleSchema,
+  spinner: ColorStyleSchema,
+  done: ColorStyleSchema,
+  failed: ColorStyleSchema,
+});
+export type ProgressBarColors = typeof ProgressBarColorsSchema.Type;
+
+export const defaultProgressBarColors: ProgressBarColors = {
+  fill: { kind: "named", value: "cyan" },
+  empty: { kind: "named", value: "white", modifiers: ["dim"] },
+  brackets: { kind: "named", value: "white", modifiers: ["dim"] },
+  percent: { kind: "named", value: "white", modifiers: ["bold"] },
+  spinner: { kind: "named", value: "yellow" },
+  done: { kind: "named", value: "green" },
+  failed: { kind: "named", value: "red" },
+};
+
+const applyModifier = (instance: ChalkInstance, modifier: StyleModifier): ChalkInstance => {
+  switch (modifier) {
+    case "bold":
+      return instance.bold;
+    case "dim":
+      return instance.dim;
+    case "italic":
+      return instance.italic;
+    case "underline":
+      return instance.underline;
+    case "inverse":
+      return instance.inverse;
+    case "hidden":
+      return instance.hidden;
+    case "strikethrough":
+      return instance.strikethrough;
+  }
+};
+
+const applyNamedColor = (instance: ChalkInstance, color: NamedColor): ChalkInstance => {
+  switch (color) {
+    case "black":
+      return instance.black;
+    case "red":
+      return instance.red;
+    case "green":
+      return instance.green;
+    case "yellow":
+      return instance.yellow;
+    case "blue":
+      return instance.blue;
+    case "magenta":
+      return instance.magenta;
+    case "cyan":
+      return instance.cyan;
+    case "white":
+      return instance.white;
+    case "blackBright":
+      return instance.blackBright;
+    case "redBright":
+      return instance.redBright;
+    case "greenBright":
+      return instance.greenBright;
+    case "yellowBright":
+      return instance.yellowBright;
+    case "blueBright":
+      return instance.blueBright;
+    case "magentaBright":
+      return instance.magentaBright;
+    case "cyanBright":
+      return instance.cyanBright;
+    case "whiteBright":
+      return instance.whiteBright;
+  }
+};
+
+const resolveBaseStyle = (style: ColorStyle): ChalkInstance => {
+  switch (style.kind) {
+    case "named":
+      return applyNamedColor(chalk, style.value);
+    case "hex":
+      return chalk.hex(style.value);
+    case "rgb":
+      return chalk.rgb(style.value.r, style.value.g, style.value.b);
+    case "ansi256":
+      return chalk.ansi256(style.value);
+  }
+};
+
+const applyModifiers = (instance: ChalkInstance, modifiers: ReadonlyArray<StyleModifier>) => {
+  let styled = instance;
+  for (const modifier of modifiers) {
+    styled = applyModifier(styled, modifier);
+  }
+  return styled;
+};
+
+export const applyColorStyle = (style: ColorStyle, text: string): string => {
+  const styled = applyModifiers(resolveBaseStyle(style), style.modifiers ?? []);
+  return styled(text);
+};
+
+export interface CompiledProgressBarColors {
+  readonly fill: (text: string) => string;
+  readonly empty: (text: string) => string;
+  readonly brackets: (text: string) => string;
+  readonly percent: (text: string) => string;
+  readonly spinner: (text: string) => string;
+  readonly done: (text: string) => string;
+  readonly failed: (text: string) => string;
+}
+
+export const compileProgressBarColors = (colors: ProgressBarColors): CompiledProgressBarColors => ({
+  fill: (text) => applyColorStyle(colors.fill, text),
+  empty: (text) => applyColorStyle(colors.empty, text),
+  brackets: (text) => applyColorStyle(colors.brackets, text),
+  percent: (text) => applyColorStyle(colors.percent, text),
+  spinner: (text) => applyColorStyle(colors.spinner, text),
+  done: (text) => applyColorStyle(colors.done, text),
+  failed: (text) => applyColorStyle(colors.failed, text),
+});

package/src/console.ts

@@ -1,14 +1,13 @@
 import { Console, Effect } from "effect";
 import { formatWithOptions } from "node:util";
-import type { ProgressService } from "./types";
 
 export const makeProgressConsole = (
-  progress: ProgressService,
+  progressLog: (...args: ReadonlyArray<unknown>) => Effect.Effect<void, never, never>,
   outerConsole: Console.Console,
 ): Console.Console => {
-  const log = (...args: ReadonlyArray<unknown>) => progress.log(...args);
+  const log = (...args: ReadonlyArray<unknown>) => progressLog(...args);
   const unsafeLog = (...args: ReadonlyArray<unknown>) => {
-    Effect.runFork(progress.log(...args));
+    Effect.runFork(progressLog(...args));
   };
 
   const delegate = (effect: Effect.Effect<void, never, never>) => effect;

package/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./api";
+export * from "./colors";
 export * from "./runtime";
 export * from "./types";