effective-progress 0.2.4 → 0.4.0

package/README.md

@@ -11,13 +11,13 @@
 
 <img alt="Showcase output" src="docs/images/showcase.gif" width="600" />
 
-`effective-progress` is an [Effect](https://effect.website/)-first terminal progress library with:
+`effective-progress` is an [Effect](https://effect.website/)-first terminal progress-bar library with:
 
-- multiple progress bars
-- nested child progress bars
-- spinner support for indeterminate work
-- 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!
+- 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
+- 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
 
 ## Install
 
@@ -94,6 +94,12 @@ Effect.runPromise(program);
 
 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)
+- bar width: `40`
+
 ```ts
 import { Effect } from "effect";
 import * as Progress from "effective-progress";
@@ -105,10 +111,6 @@ const configured = program.pipe(
   }),
   Effect.provideService(Progress.ProgressBarConfig, {
     barWidth: 36,
-    colors: {
-      fill: { kind: "hex", value: "#00b894" },
-      spinner: { kind: "ansi256", value: 214 },
-    },
   }),
 );
 
@@ -124,9 +126,6 @@ yield *
     progressbar: {
       barWidth: 20,
       spinnerFrames: [".", "o", "O", "0"],
-      colors: {
-        spinner: { kind: "named", value: "magentaBright" },
-      },
     },
   });
 ```
@@ -175,40 +174,46 @@ const program = Progress.task(
 );
 ```
 
-## Progress bar colors
+## Themes and render stages
 
-`progressbar.colors` is configured with typed color tokens that are validated by Effect Schema.
+Coloring is configured through the `Theme` service.
 
 ```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"] },
-  },
-}
-```
+import chalk from "chalk";
+import { Effect } from "effect";
+import * as Progress from "effective-progress";
 
-Supported color styles:
+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),
+    }),
+  ),
+);
+```
 
-- `named` (for example `cyan`, `greenBright`)
-- `hex` (for example `#00b894`)
-- `rgb` (for example `{ r: 0, g: 184, b: 148 }`)
-- `ansi256` (for example `214`)
+Render internals are split into overrideable stages:
 
-Supported modifiers:
+- `BuildStage`: logical rows/cells/segments
+- `ShrinkStage`: width fitting/collapse
+- `ColorStage`: role -> styled terminal strings
 
-- `bold`, `dim`, `italic`, `underline`, `inverse`, `hidden`, `strikethrough`
+You can replace any stage with `Effect.provideService(...)` while keeping defaults for the rest.
 
 ## Dependencies & package size
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effective-progress",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "Effect-first terminal progress bars with nested multibar support",
   "homepage": "https://github.com/stromseng/effective-progress#readme",
   "bugs": {

package/src/api.ts

@@ -1,11 +1,20 @@
-import { Effect, Exit } from "effect";
+import { Effect, Exit, Option } from "effect";
 import { dual } from "effect/Function";
 import type { Concurrency } from "effect/Types";
-import { Progress, provideProgressService } from "./runtime";
+import { Progress } from "./runtime";
 import { Task } from "./types";
 import type { AddTaskOptions, TrackOptions } from "./types";
 import { inferTotal } from "./utils";
 
+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);
+    }
+    return yield* Effect.scoped(effect.pipe(Effect.provide(Progress.Default)));
+  });
+
 export interface EffectExecutionOptions {
   readonly concurrency?: Concurrency;
   readonly batching?: boolean | "inherit";
@@ -19,7 +28,9 @@ export interface EffectAllExecutionOptions extends EffectExecutionOptions {
 
 export type AllOptions = Omit<TrackOptions, "total"> & EffectAllExecutionOptions;
 export type AllReturn<
-  Arg extends ReadonlyArray<Effect.Effect<any, any, any>> | Record<string, Effect.Effect<any, any, any>>,
+  Arg extends
+    | ReadonlyArray<Effect.Effect<any, any, any>>
+    | Record<string, Effect.Effect<any, any, any>>,
   O extends EffectAllExecutionOptions,
 > = [
   [Arg] extends [ReadonlyArray<Effect.Effect<any, any, any>>]
@@ -48,7 +59,7 @@ export const task: {
 } = dual(
   2,
   <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions) =>
-    provideProgressService(
+    provideProgress(
       Effect.gen(function* () {
         const progress = yield* Progress;
         return yield* progress.withTask(effect, options);
@@ -56,7 +67,9 @@ export const task: {
     ) as Effect.Effect<A, E, Exclude<R, Progress | Task>>,
 );
 
-type AllArg = ReadonlyArray<Effect.Effect<any, any, any>> | Record<string, Effect.Effect<any, any, any>>;
+type AllArg =
+  | ReadonlyArray<Effect.Effect<any, any, any>>
+  | Record<string, Effect.Effect<any, any, any>>;
 
 const wrapEffects = (
   effects: AllArg,
@@ -83,7 +96,7 @@ export const all: {
     effects: Arg,
     options: Omit<TrackOptions, "total"> & O,
   ) =>
-    provideProgressService(
+    provideProgress(
       Effect.gen(function* () {
         const progress = yield* Progress;
         return yield* progress.runTask(
@@ -143,7 +156,7 @@ export const forEach: {
     f: (item: A, index: number) => Effect.Effect<B, E, R>,
     options: ForEachOptions,
   ) =>
-    provideProgressService(
+    provideProgress(
       Effect.gen(function* () {
         const progress = yield* Progress;
 

package/src/index.ts

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