Progress Util

A signal-based helper for tracking the lifecycle of asynchronous operations. initializeState returns a WritableSignal<ProgressState>, and markLoading, markSuccess, and markError drive it through loading, success, and error transitions so your UI updates reactively.

Overview

Examples

progress-util manages progress states in Angular applications using Angular Signals. It offers a simple, type-safe way to track the loading, success, and error states of asynchronous work, making it a good fit for form submissions, API calls, data loading, and user feedback.

The utility uses a WritableSignal for reactive state management, so the UI updates automatically when the progress state changes. Import the functions from @js-smart/ng-kit, initialize a state with initializeState(), and call the helpers to move through the lifecycle:

markLoading(state) — an operation is in progress.
markSuccess(state, message?) — the operation completed successfully.
markError(state, message?) — the operation failed.

The state follows a predictable flow: Initial → Loading → Success/Error, and can return to loading for a new operation. It works seamlessly with Angular change detection and the OnPush strategy.

API

Functions

Function	Parameters	Returns	Description
`initializeState`	—	`WritableSignal<ProgressState>`	Initializes and returns a new progress state signal with default values
`markLoading`	`state: WritableSignal<ProgressState>`	`void`	Updates the state to loading, clearing success and error flags
`markSuccess`	`state: WritableSignal<ProgressState>`, `message?: string`	`void`	Updates the state to success with an optional success message
`markError`	`state: WritableSignal<ProgressState>`, `message?: string`	`void`	Updates the state to error with an optional error message

ProgressState

Property	Type	Description
`isLoading`	`boolean`	`true` when an operation is in progress, `false` otherwise
`isSuccess`	`boolean`	`true` when the last operation completed successfully
`isError`	`boolean`	`true` when the last operation failed
`isComplete`	`boolean` (optional)	`true` when the operation has completed (success or error)
`message`	`string`	User-friendly message describing the current state or outcome

The initial state is { isLoading: false, isSuccess: false, isError: false, isComplete: false, message: '' }. Reset for a new operation by calling markLoading() again.