effective-progress 0.10.0 → 0.11.0

package/README.md

@@ -75,23 +75,59 @@ Effect.runPromise(program);
 
 ### Effect.all modes
 
-Support for `either`/`validate` modes of `Effect.all` and render the amount of sucesses/failures.
+Support for `either`/`validate` modes of `Effect.all` and render the amount of successes/failures.
 
 <img alt="Mixed outcomes modes output" src="docs/images/mixedOutcomes.gif" width="600" />
 
 - `Progress.all` in default mode (`mode: "default"`) remains fail-fast.
 - In fail-fast runs, unresolved units remain unprocessed.
 - `mode: "either"` and `mode: "validate"` run all effects and keep mixed outcomes in the task counters.
-- Mixed outcomes can still finalize as `done` when all units are accounted for.
+- Mixed outcomes can finalize as `done` when all units are accounted for.
 - Empty collections are valid inputs for `Progress.all` / `Progress.forEach` and render as `0/0` instead of failing.
 
+### Single task with a typed handle
+
+Use `Progress.task(...)` when you want one progress bar around a custom effect. The callback form gives you a task-local handle, so you can update counts, descriptions, and metadata without fetching the current task ID first.
+
+```ts
+import { Console, Effect } from "effect";
+import * as Progress from "effective-progress";
+
+const program = Progress.task(
+  (task) =>
+    Effect.gen(function* () {
+      yield* Console.log("Starting deployment");
+      yield* task.incrementSucceeded();
+      yield* task.update({
+        description: "Uploading release bundle",
+      });
+      yield* Effect.sleep("1 second");
+      yield* task.incrementSucceeded(2);
+    }),
+  {
+    description: "Deploy release",
+    total: 3,
+  },
+);
+
+Effect.runPromise(program);
+```
+
+- The plain `Progress.task(effect, options)` form auto-finalizes from the effect exit.
+- The callback form also auto-finalizes from the callback exit unless you explicitly `yield* task.complete` or `yield* task.fail` first.
+- `yield* Progress.Task` exposes the current task ID when you need it.
+
 ### Other examples
 
 - `examples/simpleExample.ts` - low-boilerplate real-world flow
-- `examples/advancedExample.ts` - full API usage and manual task control
+- `examples/advancedExample.ts` - mixed high-level and low-level Progress service usage
+- `examples/basic.ts` - minimal `Progress.all` usage
+- `examples/nesting.ts` - nested tree rendering with parent and child tasks
 - `examples/mixedOutcomes.ts` - fail-fast vs `either`/`validate` with mixed success/failure counters
 - `examples/cliProgressSemantics.ts` - zero totals, negative totals clearing to unknown totals, overflow counts, and empty `all` / `forEach`
 - `examples/unknownTotalCounting.ts` - count successes/failures without a known total and render `processed/?`
+- `examples/typedMetadata.ts` - typed task metadata rendered through custom columns
+- `examples/mixedNestedColumns.ts` - different column sets aligned across mixed task types
 - `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/performanceLong.ts` - longer-running stress run with roughly 10x the work of `performance.ts`
@@ -109,21 +145,40 @@ Support for `either`/`validate` modes of `Effect.all` and render the amount of s
 ### Ink renderer behavior
 
 - Rendering is powered by [Ink](https://github.com/vadimdemedes/ink).
-- Built-in columns are: description, bar, amount/spinner, elapsed, and ETA.
+- Built-in columns are exposed as `Progress.Columns.description()`, `bar()`, `amount()`, `elapsed()`, `eta()`, `spacer()`, and `defaults()`.
 - Determinate bars are segmented by outcome: succeeded (green), failed (red), and remaining (neutral).
 - Determinate amount text shows counters without prefixes: `<succeeded> <failed> <processed>/<total>`.
 - Counts can exceed `total`; the amount text keeps those raw values (for example `12/10`) while the bar stays visually clamped at full.
 - `total: 0` is valid for determinate tasks and renders as a full bar by default.
-- Column widths are measured and allocated per frame from a shared column tree, so rows stay aligned.
-- Elapsed and ETA reserve stable widths to reduce jitter while tasks transition states.
-- Sticky width can keep selected columns stable until the frame empties.
+- Column widths are resolved per visual column index, so rows with different column definitions can still align with each other.
+- Column `prepare(...)` functions can compute shared layout data once for all rows using the same column definition at a given index.
 - On narrow terminals, layout compacts to fit available width and tree prefixes are suppressed when description space is too tight.
 
-## Manual task control
+## Task API
+
+`Progress.task(...)` supports two styles:
+
+- `Progress.task(effect, options)` for the simple "wrap this effect in a task" case.
+- `Progress.task((task) => effect, options)` when you want a typed handle for task-local control.
+
+The handle exposes:
+
+- `incrementSucceeded(amount?)`
+- `incrementFailed(amount?)`
+- `update({ description, total, countDisplay, transient, succeeded, failed })`
+- `getMetadata`, `setMetadata`, `updateMetadata`
+- `getSnapshot`
+- `complete`
+- `fail`
 
-For manual usage, `task` still provides the current `Task` context, while logs continue through your outer `Console`:
+When you need lower-level control, the `Progress` service is available inside the effect and exposes APIs like `addTask`, `updateTask`, `incrementSucceeded(taskId, amount)`, and `completeTask(taskId)`.
+
+Example using the lower-level service API:
 
 ```ts
+import { Console, Effect } from "effect";
+import * as Progress from "effective-progress";
+
 const program = Progress.task(
   Effect.gen(function* () {
     const progress = yield* Progress.Progress;
@@ -145,9 +200,59 @@ Manual total behavior:
 - negative totals on later `updateTask` calls also clear the total
 - explicit `total: undefined` on `updateTask` clears the total and switches back to indeterminate rendering
 
-## Column customization
+## Typed metadata and custom columns
+
+Tasks can carry typed metadata, and that metadata type flows into custom column renderers.
+
+```ts
+import { Effect } from "effect";
+import * as Progress from "effective-progress";
+
+interface EvalMeta {
+  readonly model: string;
+  readonly score: number;
+}
+
+const scoreColumn = (): Progress.ColumnDef<EvalMeta> => ({
+  align: "right",
+  flexShrink: 0,
+  minWidth: 5,
+  render: ({ task }) => `${task.metadata.score}%`,
+});
+
+const program = Progress.task(
+  (task) =>
+    Effect.gen(function* () {
+      yield* task.setMetadata({ model: "gpt-5.4", score: 91 });
+      yield* task.incrementSucceeded();
+    }),
+  {
+    description: "Run evaluation",
+    total: 1,
+    metadata: { model: "gpt-5.4", score: 0 },
+    columns: [
+      Progress.Columns.description(),
+      Progress.Columns.bar(),
+      {
+        flexShrink: 0,
+        minWidth: 10,
+        render: ({ task }) => task.metadata.model,
+      },
+      scoreColumn(),
+      Progress.Columns.elapsed(),
+    ],
+  },
+);
+```
+
+`ColumnDef<M, P>` supports:
+
+- `prepare(rows)` to derive shared data for all matching rows at that column index
+- `render(cell, ctx)` to render the cell
+- sizing hints with `flexGrow`, `flexShrink`, `flexBasis`, and `minWidth`
+- `align` with `"left"`, `"center"`, or `"right"`
 
-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.
+If a task does not provide `columns`, the renderer falls back to `Progress.Columns.defaults()`.
 
 ## Notes
 

package/dist/chunk-DQk6qfdC.mjs

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };

package/dist/index.d.mts

@@ -1,4 +1,7 @@
 import { Brand, Context, Effect, Layer, Option, Schema } from "effect";
+import { ReactNode } from "react";
+import "react/jsx-runtime";
+import "cli-spinners";
 import { Concurrency } from "effect/Types";
 import * as effect_SchemaAST0 from "effect/SchemaAST";
 
@@ -10,12 +13,84 @@ declare const TaskStatusSchema: Schema.Literal<["running", "done", "failed"]>;
 type TaskStatus = typeof TaskStatusSchema.Type;
 declare const TaskCountDisplaySchema: Schema.Literal<["processedOnly", "detailed"]>;
 type TaskCountDisplay = typeof TaskCountDisplaySchema.Type;
-interface AddTaskOptions {
+type ColumnAlign = "left" | "center" | "right";
+interface TaskTreeInfo {
+  readonly depth: number;
+  readonly hasNextSibling: boolean;
+  readonly hasChildren: boolean;
+  readonly ancestorHasNextSibling: ReadonlyArray<boolean>;
+}
+interface TaskRowDerived {
+  readonly treePrefix: string;
+  readonly treePrefixWidth: number;
+  readonly descriptionWidth: number;
+  readonly treePrefixedDescriptionWidth: number;
+  readonly hasRenderableProgress: boolean;
+  readonly isDeterminate: boolean;
+}
+/** All data available to a column cell. */
+interface CellInfo<M = unknown> {
+  readonly task: TaskSnapshot & {
+    readonly metadata: M;
+  };
+  readonly tree: TaskTreeInfo;
+  readonly derived: TaskRowDerived;
+}
+interface ColumnRenderContext<P = void> {
+  readonly width?: number;
+  readonly now: number;
+  readonly spinnerTick: number;
+  readonly prepared: P;
+}
+type ColumnSizeValue<P = void> = number | ((prepared: P) => number | undefined);
+type BivariantCallback<Args extends ReadonlyArray<unknown>, R> = {
+  bivarianceHack: (...args: Args) => R;
+}["bivarianceHack"];
+interface ColumnDef<M = unknown, P = void> {
+  readonly prepare?: BivariantCallback<[rows: ReadonlyArray<CellInfo<M>>], P>;
+  readonly render: BivariantCallback<[cell: CellInfo<M>, ctx: ColumnRenderContext<P>], ReactNode>;
+  readonly align?: ColumnAlign;
+  readonly flexGrow?: ColumnSizeValue<P>;
+  readonly flexShrink?: ColumnSizeValue<P>;
+  readonly flexBasis?: ColumnSizeValue<P>;
+  readonly minWidth?: ColumnSizeValue<P>;
+}
+/**
+ * A typed facade over a single task created through the callback form of `task(...)`.
+ *
+ * Use this handle to update counts, metadata, description, or to explicitly finalize the task
+ * before the callback exits. If the callback returns or fails while the task is still `running`,
+ * the library auto-finalizes it from the callback exit status instead.
+ */
+interface TaskHandle<M> {
+  readonly id: TaskId;
+  /** Reads the current metadata value for the task using the metadata type inferred at creation. */
+  readonly getMetadata: Effect.Effect<M>;
+  /** Replaces the task metadata. */
+  readonly setMetadata: (metadata: M) => Effect.Effect<void>;
+  /** Updates the current metadata value atomically. */
+  readonly updateMetadata: (f: (m: M) => M) => Effect.Effect<void>;
+  /** Increments the succeeded counter for the task. */
+  readonly incrementSucceeded: (amount?: number) => Effect.Effect<void>;
+  /** Increments the failed counter for the task. */
+  readonly incrementFailed: (amount?: number) => Effect.Effect<void>;
+  /** Updates mutable task fields such as description, totals, and count display. */
+  readonly update: (options: UpdateTaskOptions) => Effect.Effect<void>;
+  /** Marks the task as done immediately. Finalization is terminal once the task leaves `running`. */
+  readonly complete: Effect.Effect<void>;
+  /** Marks the task as failed immediately. Finalization is terminal once the task leaves `running`. */
+  readonly fail: Effect.Effect<void>;
+  /** Reads the latest task snapshot. */
+  readonly getSnapshot: Effect.Effect<TaskSnapshot>;
+}
+interface AddTaskOptions<M = void> {
   readonly description: string;
   readonly total?: number;
   readonly transient?: boolean;
   readonly parentId?: TaskId;
   readonly countDisplay?: TaskCountDisplay;
+  readonly metadata?: M;
+  readonly columns?: ReadonlyArray<ColumnDef<M, any>>;
 }
 interface UpdateTaskOptions {
   readonly description?: string;
@@ -25,7 +100,7 @@ interface UpdateTaskOptions {
   readonly transient?: boolean;
   readonly countDisplay?: TaskCountDisplay;
 }
-type TrackOptions = Exclude<AddTaskOptions, "parentId">;
+type TrackOptions = Omit<AddTaskOptions, "parentId">;
 declare const TaskUnitsSchema: Schema.Struct<{
   succeeded: typeof Schema.Number;
   failed: typeof Schema.Number;
@@ -48,6 +123,7 @@ declare const TaskSnapshotSchema: Schema.Struct<{
   }>;
   startedAt: typeof Schema.Number;
   completedAt: Schema.NullOr<typeof Schema.Number>;
+  metadata: typeof Schema.Unknown;
 }>;
 type TaskSnapshot = typeof TaskSnapshotSchema.Type;
 declare const TaskSnapshot: (snapshot: TaskSnapshot) => TaskSnapshot;
@@ -58,9 +134,10 @@ interface RenderRow {
 interface TaskStore {
   readonly tasks: Map<TaskId, TaskSnapshot>;
   readonly renderOrder: ReadonlyArray<RenderRow>;
+  readonly columns: Map<TaskId, ReadonlyArray<ColumnDef<any, any>>>;
 }
 interface ProgressService {
-  readonly addTask: (options: AddTaskOptions) => Effect.Effect<TaskId>;
+  readonly addTask: (options: AddTaskOptions<any>) => Effect.Effect<TaskId>;
   readonly updateTask: (taskId: TaskId, options: UpdateTaskOptions) => Effect.Effect<void>;
   readonly incrementSucceeded: (taskId: TaskId, amount?: number) => Effect.Effect<void>;
   readonly incrementFailed: (taskId: TaskId, amount?: number) => Effect.Effect<void>;
@@ -69,13 +146,24 @@ interface ProgressService {
   readonly log: (...args: ReadonlyArray<unknown>) => Effect.Effect<void>;
   readonly getTask: (taskId: TaskId) => Effect.Effect<Option.Option<TaskSnapshot>>;
   readonly listTasks: Effect.Effect<ReadonlyArray<TaskSnapshot>>;
-  readonly runTask: {
-    <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions): Effect.Effect<A, E, Exclude<R, Task>>;
-    <A, E, R>(options: AddTaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Task>>;
-  };
-  readonly withTask: {
+  readonly setMetadata: (taskId: TaskId, metadata: unknown) => Effect.Effect<void>;
+  readonly getMetadata: (taskId: TaskId) => Effect.Effect<unknown>;
+  /**
+   * Runs an effect inside a newly created task scope.
+   *
+   * The plain effect form auto-finalizes from the effect exit if the task is still `running`.
+   * The callback form exposes a typed `TaskHandle` for metadata and explicit lifecycle control, and
+   * also auto-finalizes from the callback exit if the handle did not already finalize the task.
+   *
+   * Use `Progress.task(...)` from `src/api.ts` when you want the service to be created automatically if needed.
+   */
+  readonly task: {
     <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions): Effect.Effect<A, E, Exclude<R, Task>>;
     <A, E, R>(options: AddTaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Task>>;
+    <A, E, R>(f: (handle: TaskHandle<void>) => Effect.Effect<A, E, R>, options: AddTaskOptions<void>): Effect.Effect<A, E, Exclude<R, Task>>;
+    <M, A, E, R>(f: (handle: TaskHandle<M>) => Effect.Effect<A, E, R>, options: AddTaskOptions<M> & {
+      readonly metadata: M;
+    }): Effect.Effect<A, E, Exclude<R, Task>>;
   };
 }
 declare const Task_base: Context.TagClass<Task, "stromseng.dev/effective-progress/Task", number & Brand.Brand<"TaskId">>;
@@ -141,6 +229,14 @@ declare class Progress extends Progress_base {
 }
 //#endregion
 //#region src/api.d.ts
+interface PublicTaskApi {
+  <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions): Effect.Effect<A, E, Exclude<R, Progress | Task>>;
+  <A, E, R>(options: AddTaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Progress | Task>>;
+  <A, E, R>(f: (handle: TaskHandle<void>) => Effect.Effect<A, E, R>, options: AddTaskOptions<void>): Effect.Effect<A, E, Exclude<R, Progress | Task>>;
+  <M, A, E, R>(f: (handle: TaskHandle<M>) => Effect.Effect<A, E, R>, options: AddTaskOptions<M> & {
+    readonly metadata: M;
+  }): Effect.Effect<A, E, Exclude<R, Progress | Task>>;
+}
 interface EffectExecutionOptions {
   readonly concurrency?: Concurrency;
   readonly batching?: boolean | "inherit";
@@ -156,21 +252,74 @@ interface ForEachExecutionOptions extends EffectExecutionOptions {
   readonly discard?: false | undefined;
 }
 type ForEachOptions = Omit<TrackOptions, "countDisplay"> & ForEachExecutionOptions;
-type TaskOptions = AddTaskOptions;
-declare const task: {
-  <A, E, R>(effect: Effect.Effect<A, E, R>, options: TaskOptions): Effect.Effect<A, E, Exclude<R, Progress | Task>>;
-  <A, E, R>(options: TaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Progress | Task>>;
-};
+type TaskOptions<M = void> = AddTaskOptions<M>;
+/**
+ * Runs an effect inside a task, creating and providing a `Progress` service automatically when one
+ * is not already present in the environment.
+ *
+ * The effect form tracks success and failure from the effect exit. The callback form exposes a
+ * typed `TaskHandle` for task-local updates, typed metadata, and explicit completion or failure,
+ * and otherwise auto-finalizes from the callback exit if the task is still `running`.
+ */
+declare const task$1: PublicTaskApi;
 type AllArg = ReadonlyArray<Effect.Effect<any, any, any>> | Record<string, Effect.Effect<any, any, any>>;
+/**
+ * Runs multiple effects under a single parent task and keeps the task counters in sync with the
+ * child effect outcomes.
+ */
 declare const all: {
   <const Arg extends AllArg, O extends EffectAllExecutionOptions>(effects: Arg, options: Omit<TrackOptions, "total" | "countDisplay"> & O): AllReturn<Arg, O>;
   <O extends EffectAllExecutionOptions>(options: Omit<TrackOptions, "total" | "countDisplay"> & O): <const Arg extends AllArg>(effects: Arg) => AllReturn<Arg, O>;
 };
+/**
+ * Runs `Effect.forEach` under a single parent task and advances the task counters as items finish.
+ */
 declare 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 | Task>>;
   <A, B, E, R>(f: (item: A, index: number) => Effect.Effect<B, E, R>, options: ForEachOptions): (iterable: Iterable<A>) => Effect.Effect<ReadonlyArray<B>, E, Exclude<R, Progress | Task>>;
 };
 //#endregion
+//#region src/renderer/columns/amount-column.d.ts
+interface AmountLayout {
+  readonly hasDetailedRows: boolean;
+  readonly countWidth: number;
+  readonly processedWidth: number;
+  readonly totalWidth: number;
+  readonly preferredWidth: number;
+}
+//#endregion
+//#region src/renderer/columns/bar-column.d.ts
+interface BarPrepared {
+  readonly hasDeterminateRows: boolean;
+}
+//#endregion
+//#region src/renderer/columns/description-column.d.ts
+interface DescriptionPrepared {
+  readonly minTreeWidth: number;
+}
+declare namespace columns_d_exports {
+  export { AmountLayout, BarPrepared, DescriptionPrepared, SpacerOptions, amount, bar, defaults, description, elapsed, eta, resolveColumnSizeValue, spacer };
+}
+interface SpacerOptions {
+  readonly flexGrow?: number;
+  readonly flexShrink?: number;
+  readonly flexBasis?: number;
+  readonly minWidth?: number;
+}
+declare const spacer: <M = unknown>({
+  flexGrow,
+  flexShrink,
+  flexBasis,
+  minWidth
+}?: SpacerOptions) => ColumnDef<M>;
+declare const description: () => ColumnDef<any, DescriptionPrepared>;
+declare const bar: () => ColumnDef<any, BarPrepared>;
+declare const amount: () => ColumnDef<any, AmountLayout>;
+declare const elapsed: () => ColumnDef<any>;
+declare const eta: () => ColumnDef<any>;
+declare const defaults: () => ReadonlyArray<ColumnDef<any, any>>;
+declare const resolveColumnSizeValue: <P>(value: ColumnSizeValue<P> | undefined, prepared: P) => number | undefined;
+//#endregion
 //#region src/services/stdio.d.ts
 interface ProgressStdioService {
   readonly stdout: NodeJS.WriteStream;
@@ -181,4 +330,4 @@ declare class ProgressStdio extends ProgressStdio_base {
   static readonly Default: Layer.Layer<ProgressStdio, never, never>;
 }
 //#endregion
-export { AddTaskOptions, AllOptions, AllReturn, EffectAllExecutionOptions, EffectExecutionOptions, ForEachExecutionOptions, ForEachOptions, Progress, ProgressService, ProgressStdio, ProgressStdioService, ProgressTaskEvent, ProgressTaskEventSchema, RenderRow, Task, TaskAddedEvent, TaskAdvancedEvent, TaskCompletedEvent, TaskCountDisplay, TaskCountDisplaySchema, TaskFailedEvent, TaskId, TaskOptions, TaskRemovedEvent, TaskSnapshot, TaskSnapshotSchema, TaskStatus, TaskStatusSchema, TaskStore, TaskUnits, TaskUnitsSchema, TaskUpdatedEvent, TrackOptions, UpdateTaskOptions, all, decodeProgressTaskEvent, forEach, task };
+export { AddTaskOptions, AllOptions, AllReturn, CellInfo, ColumnAlign, ColumnDef, ColumnRenderContext, ColumnSizeValue, columns_d_exports as Columns, EffectAllExecutionOptions, EffectExecutionOptions, ForEachExecutionOptions, ForEachOptions, Progress, ProgressService, ProgressStdio, ProgressStdioService, ProgressTaskEvent, ProgressTaskEventSchema, RenderRow, Task, TaskAddedEvent, TaskAdvancedEvent, TaskCompletedEvent, TaskCountDisplay, TaskCountDisplaySchema, TaskFailedEvent, TaskHandle, TaskId, TaskOptions, TaskRemovedEvent, TaskRowDerived, TaskSnapshot, TaskSnapshotSchema, TaskStatus, TaskStatusSchema, TaskStore, TaskTreeInfo, TaskUnits, TaskUnitsSchema, TaskUpdatedEvent, TrackOptions, UpdateTaskOptions, all, decodeProgressTaskEvent, forEach, task$1 as task };