effective-progress 0.6.2 → 0.8.0

package/README.md

@@ -83,12 +83,14 @@ Support for `either`/`validate` modes of `Effect.all` and render the amount of s
 - 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.
+- Empty collections are valid inputs for `Progress.all` / `Progress.forEach` and render as `0/0` instead of failing.
 
 ### Other examples
 
 - `examples/simpleExample.ts` - low-boilerplate real-world flow
 - `examples/advancedExample.ts` - full API usage and manual task control
 - `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/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
@@ -107,6 +109,8 @@ Support for `either`/`validate` modes of `Effect.all` and render the amount of s
 - Built-in columns are: description, bar, amount/spinner, elapsed, and ETA.
 - 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 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.
@@ -132,6 +136,12 @@ const program = Progress.task(
 );
 ```
 
+Manual total behavior:
+
+- negative totals on task creation clear the total and switch to indeterminate rendering
+- 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
 
 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.

package/dist/index.d.mts

@@ -10,13 +10,6 @@ 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;
-declare const InvalidTaskTotalError_base: Schema.TaggedErrorClass<InvalidTaskTotalError, "InvalidTaskTotalError", {
-  readonly _tag: Schema.tag<"InvalidTaskTotalError">;
-} & {
-  total: typeof Schema.Number;
-  message: typeof Schema.String;
-}>;
-declare class InvalidTaskTotalError extends InvalidTaskTotalError_base {}
 interface AddTaskOptions {
   readonly description: string;
   readonly total?: number;
@@ -68,8 +61,8 @@ interface TaskStore {
   readonly renderOrder: ReadonlyArray<RenderRow>;
 }
 interface ProgressService {
-  readonly addTask: (options: AddTaskOptions) => Effect.Effect<TaskId, InvalidTaskTotalError>;
-  readonly updateTask: (taskId: TaskId, options: UpdateTaskOptions) => Effect.Effect<void, InvalidTaskTotalError>;
+  readonly addTask: (options: AddTaskOptions) => 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>;
   readonly completeTask: (taskId: TaskId) => Effect.Effect<void>;
@@ -78,12 +71,12 @@ interface ProgressService {
   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 | InvalidTaskTotalError, Exclude<R, Task>>;
-    <A, E, R>(options: AddTaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | InvalidTaskTotalError, Exclude<R, 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>>;
   };
   readonly withTask: {
-    <A, E, R>(effect: Effect.Effect<A, E, R>, options: AddTaskOptions): Effect.Effect<A, E | InvalidTaskTotalError, Exclude<R, Task>>;
-    <A, E, R>(options: AddTaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | InvalidTaskTotalError, Exclude<R, 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>>;
   };
 }
 declare const Task_base: Context.TagClass<Task, "stromseng.dev/effective-progress/Task", number & Brand.Brand<"TaskId">>;
@@ -159,15 +152,15 @@ interface EffectAllExecutionOptions extends EffectExecutionOptions {
   readonly mode?: "default" | "validate" | "either";
 }
 type AllOptions = Omit<TrackOptions, "total" | "countDisplay"> & EffectAllExecutionOptions;
-type AllReturn<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>>] ? Effect.All.ReturnTuple<Arg, Effect.All.IsDiscard<O>, Effect.All.ExtractMode<O>> : [Arg] extends [Record<string, Effect.Effect<any, any, any>>] ? Effect.All.ReturnObject<Arg, Effect.All.IsDiscard<O>, Effect.All.ExtractMode<O>> : never] extends [Effect.Effect<infer A, infer E, infer R>] ? Effect.Effect<A, E | InvalidTaskTotalError, Exclude<R, Progress | Task>> : never;
+type AllReturn<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>>] ? Effect.All.ReturnTuple<Arg, Effect.All.IsDiscard<O>, Effect.All.ExtractMode<O>> : [Arg] extends [Record<string, Effect.Effect<any, any, any>>] ? Effect.All.ReturnObject<Arg, Effect.All.IsDiscard<O>, Effect.All.ExtractMode<O>> : never] extends [Effect.Effect<infer A, infer E, infer R>] ? Effect.Effect<A, E, Exclude<R, Progress | Task>> : never;
 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 | InvalidTaskTotalError, Exclude<R, Progress | Task>>;
-  <A, E, R>(options: TaskOptions): (effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | InvalidTaskTotalError, Exclude<R, Progress | 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 AllArg = ReadonlyArray<Effect.Effect<any, any, any>> | Record<string, Effect.Effect<any, any, any>>;
 declare const all: {
@@ -175,8 +168,8 @@ declare const all: {
   <O extends EffectAllExecutionOptions>(options: Omit<TrackOptions, "total" | "countDisplay"> & O): <const Arg extends AllArg>(effects: Arg) => AllReturn<Arg, O>;
 };
 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 | InvalidTaskTotalError, 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 | InvalidTaskTotalError, Exclude<R, Progress | Task>>;
+  <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/services/stdio.d.ts
@@ -189,4 +182,4 @@ declare class ProgressStdio extends ProgressStdio_base {
   static readonly Default: Layer.Layer<ProgressStdio, never, never>;
 }
 //#endregion
-export { AddTaskOptions, AllOptions, AllReturn, EffectAllExecutionOptions, EffectExecutionOptions, ForEachExecutionOptions, ForEachOptions, InvalidTaskTotalError, Progress, ProgressService, ProgressStdio, ProgressStdioService, ProgressTaskEvent, ProgressTaskEventSchema, RenderRow, Task, TaskAddedEvent, TaskAdvancedEvent, TaskCompletedEvent, TaskCountDisplay, TaskCountDisplaySchema, TaskFailedEvent, TaskId, TaskOptions, TaskRemovedEvent, TaskSnapshot, TaskStatus, TaskStatusSchema, TaskStore, TaskUnits, TaskUnitsSchema, TaskUpdatedEvent, TrackOptions, UpdateTaskOptions, all, decodeProgressTaskEvent, forEach, task };
+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, TaskStatus, TaskStatusSchema, TaskStore, TaskUnits, TaskUnitsSchema, TaskUpdatedEvent, TrackOptions, UpdateTaskOptions, all, decodeProgressTaskEvent, forEach, task };

package/dist/index.mjs

@@ -10,10 +10,6 @@ const TaskIdSchema = Schema.Number.pipe(Schema.brand("TaskId"));
 const TaskId = Brand.nominal();
 const TaskStatusSchema = Schema.Literal("running", "done", "failed");
 const TaskCountDisplaySchema = Schema.Literal("processedOnly", "detailed");
-var InvalidTaskTotalError = class extends Schema.TaggedError()("InvalidTaskTotalError", {
-	total: Schema.Number,
-	message: Schema.String
-}) {};
 const TaskUnitsSchema = Schema.Struct({
 	succeeded: Schema.Number,
 	failed: Schema.Number,
@@ -117,74 +113,46 @@ const toRenderSnapshot = (store) => {
 //#endregion
 //#region src/ink-renderer/store.ts
 const hasExplicitTotal = (options) => Object.prototype.hasOwnProperty.call(options, "total");
-const INVALID_TASK_TOTAL_MESSAGE = "Task total must be greater than 0 when provided.";
-const normalizeTotal = (total) => {
-	if (total <= 0) return Effect.fail(new InvalidTaskTotalError({
-		total,
-		message: INVALID_TASK_TOTAL_MESSAGE
-	}));
-	return Effect.succeed(total);
+const sanitizeTotalOnAdd = (total) => {
+	if (total === void 0) return;
+	return total < 0 ? void 0 : total;
 };
-const normalizeUnits = (counts) => {
-	const total = counts.total;
-	if (total === void 0) {
-		const succeeded = Math.max(0, counts.succeeded);
-		const failed = Math.max(0, counts.failed);
-		return Effect.succeed({
-			succeeded,
-			failed,
-			processed: succeeded + failed
-		});
-	}
-	return Effect.map(normalizeTotal(total), (normalizedTotal) => {
-		const failed = Math.min(normalizedTotal, Math.max(0, counts.failed));
-		const succeeded = Math.min(normalizedTotal - failed, Math.max(0, counts.succeeded));
-		return {
-			succeeded,
-			failed,
-			processed: succeeded + failed,
-			total: normalizedTotal
-		};
-	});
+const sanitizeTotalOnUpdate = (nextTotal) => {
+	if (nextTotal === void 0) return;
+	return nextTotal < 0 ? void 0 : nextTotal;
 };
-const normalizeUnitsUnsafe = (counts) => {
-	const total = counts.total;
-	if (total === void 0) {
-		const succeeded = Math.max(0, counts.succeeded);
-		const failed = Math.max(0, counts.failed);
-		return {
-			succeeded,
-			failed,
-			processed: succeeded + failed
-		};
-	}
-	const failed = Math.min(total, Math.max(0, counts.failed));
-	const succeeded = Math.min(total - failed, Math.max(0, counts.succeeded));
-	return {
+const normalizeUnits = (counts) => {
+	const succeeded = Math.max(0, counts.succeeded);
+	const failed = Math.max(0, counts.failed);
+	return counts.total === void 0 ? {
+		succeeded,
+		failed,
+		processed: succeeded + failed
+	} : {
 		succeeded,
 		failed,
 		processed: succeeded + failed,
-		total
+		total: counts.total
 	};
 };
 const updatedSnapshot = (snapshot, options) => {
 	const currentUnits = snapshot.units;
-	const units = options.succeeded === void 0 && options.failed === void 0 && options.total === void 0 && !hasExplicitTotal(options) ? Effect.succeed(currentUnits) : normalizeUnits({
+	const units = options.succeeded === void 0 && options.failed === void 0 && options.total === void 0 && !hasExplicitTotal(options) ? currentUnits : normalizeUnits({
 		succeeded: options.succeeded ?? currentUnits.succeeded,
 		failed: options.failed ?? currentUnits.failed,
-		total: hasExplicitTotal(options) ? options.total : currentUnits.total
+		total: hasExplicitTotal(options) ? sanitizeTotalOnUpdate(options.total) : currentUnits.total
 	});
-	return Effect.map(units, (resolvedUnits) => new TaskSnapshot({
+	return new TaskSnapshot({
 		id: snapshot.id,
 		parentId: snapshot.parentId,
 		description: options.description ?? snapshot.description,
 		status: snapshot.status,
 		countDisplay: options.countDisplay ?? snapshot.countDisplay,
 		transient: options.transient ?? snapshot.transient,
-		units: resolvedUnits,
+		units,
 		startedAt: snapshot.startedAt,
 		completedAt: snapshot.completedAt
-	}));
+	});
 };
 const withTransient = (snapshot, transient) => new TaskSnapshot({
 	id: snapshot.id,
@@ -291,10 +259,10 @@ const makeProgressRenderStore = () => {
 		},
 		addTask: (options) => Effect.gen(function* () {
 			const taskId = TaskId(++nextTaskId);
-			const units = yield* normalizeUnits({
+			const units = normalizeUnits({
 				succeeded: 0,
 				failed: 0,
-				total: options.total
+				total: sanitizeTotalOnAdd(options.total)
 			});
 			const parentSnapshot = options.parentId === void 0 ? void 0 : state.tasks.get(options.parentId);
 			const now = yield* Clock.currentTimeMillis;
@@ -330,7 +298,7 @@ const makeProgressRenderStore = () => {
 		updateTask: (taskId, options) => Effect.gen(function* () {
 			const currentTask = state.tasks.get(taskId);
 			if (!currentTask) return;
-			const nextTask = yield* updatedSnapshot(currentTask, options);
+			const nextTask = updatedSnapshot(currentTask, options);
 			updateState((current) => {
 				if (!current.tasks.get(taskId)) return current;
 				const nextTasks = new Map(current.tasks);
@@ -366,7 +334,7 @@ const makeProgressRenderStore = () => {
 					status: currentTask.status,
 					countDisplay: currentTask.countDisplay,
 					transient: currentTask.transient,
-					units: normalizeUnitsUnsafe({
+					units: normalizeUnits({
 						succeeded: currentTask.units.succeeded + amount,
 						failed: currentTask.units.failed,
 						total: currentTask.units.total
@@ -392,7 +360,7 @@ const makeProgressRenderStore = () => {
 					status: currentTask.status,
 					countDisplay: currentTask.countDisplay,
 					transient: currentTask.transient,
-					units: normalizeUnitsUnsafe({
+					units: normalizeUnits({
 						succeeded: currentTask.units.succeeded,
 						failed: currentTask.units.failed + amount,
 						total: currentTask.units.total
@@ -426,11 +394,11 @@ const makeProgressRenderStore = () => {
 					status: "done",
 					countDisplay: currentTask.countDisplay,
 					transient: currentTask.transient,
-					units: currentTask.units.total !== void 0 ? normalizeUnitsUnsafe({
-						succeeded: currentTask.units.total - currentTask.units.failed,
+					units: currentTask.units.total !== void 0 ? currentTask.units.processed < currentTask.units.total ? normalizeUnits({
+						succeeded: currentTask.units.succeeded + (currentTask.units.total - currentTask.units.processed),
 						failed: currentTask.units.failed,
 						total: currentTask.units.total
-					}) : currentTask.units.processed > 0 ? normalizeUnitsUnsafe({
+					}) : currentTask.units : currentTask.units.processed > 0 ? normalizeUnits({
 						succeeded: currentTask.units.succeeded,
 						failed: currentTask.units.failed,
 						total: currentTask.units.processed
@@ -814,13 +782,14 @@ const createAmountColumnSpec = (context) => {
 const DEFAULT_BAR_WIDTH = 30;
 const MIN_BAR_WIDTH = 8;
 const segmentLengths = (width, total, succeeded, failed) => {
-	if (total <= 0) return {
-		succeeded: 0,
+	if (total === 0) return {
+		succeeded: width,
 		failed: 0,
-		remaining: width
+		remaining: 0
 	};
-	const succeededEnd = Math.round(succeeded / total * width);
-	const failedEnd = Math.round((succeeded + failed) / total * width);
+	const displayTotal = Math.max(total, succeeded + failed);
+	const succeededEnd = Math.round(succeeded / displayTotal * width);
+	const failedEnd = Math.round((succeeded + failed) / displayTotal * width);
 	const succeededLength = Math.max(0, Math.min(width, succeededEnd));
 	const failedLength = Math.max(0, Math.min(width, failedEnd) - succeededLength);
 	return {
@@ -1651,4 +1620,4 @@ const forEach = dual(3, (iterable, f, options) => provideProgress(Effect.gen(fun
 })));
 
 //#endregion
-export { InvalidTaskTotalError, Progress, ProgressStdio, ProgressTaskEventSchema, Task, TaskAddedEvent, TaskAdvancedEvent, TaskCompletedEvent, TaskCountDisplaySchema, TaskFailedEvent, TaskId, TaskRemovedEvent, TaskSnapshot, TaskStatusSchema, TaskUnitsSchema, TaskUpdatedEvent, all, decodeProgressTaskEvent, forEach, task };
+export { Progress, ProgressStdio, ProgressTaskEventSchema, Task, TaskAddedEvent, TaskAdvancedEvent, TaskCompletedEvent, TaskCountDisplaySchema, TaskFailedEvent, TaskId, TaskRemovedEvent, TaskSnapshot, TaskStatusSchema, TaskUnitsSchema, TaskUpdatedEvent, all, decodeProgressTaskEvent, forEach, task };

package/package.json

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