better-all

In all(), you can prevent resource waste (like unnecessary API calls) by using this.$signal. This is an AbortSignal that is automatically aborted if any sibling task fails.

Passing this signal to standard web APIs like fetch allows them to cancel immediately when a sibling fails.

Note: allSettled() does not auto-abort on task failure to ensure all tasks finish, but you can still pass an external AbortSignal via the options object to control cancellation manually.

// Automatic cancellation on sibling failure
const result = await all({
  async fetchUser() {
    const res = await fetch('/api/user', { signal: this.$signal })
    return res.json()
  },
  async fetchPosts() {
    // If fetchUser fails, this.$signal will be aborted
    const res = await fetch('/api/posts', { signal: this.$signal })
    return res.json()
  }
})

// Manual cancellation via external signal
const controller = new AbortController()
const result = await all({
  async a() { return fetchData(this.$signal) },
  async b() { return fetchMoreData(this.$signal) }
}, { signal: controller.signal })

The flow() API is optimized for several patterns:

1. Cache Checks: Exit early if data is found in a cache to avoid expensive operations.
2. Racing Operations: Return the result of the first successful operation (e.g., primary vs. backup server).
3. Conditional Computations: Validate input or state early and exit with an error or fallback object if conditions aren't met.

// Example: Early Exit from Cache
import { flow } from 'better-all'

const data = await flow<YourDataType>({
  async checkCache() {
    const cached = await getFromCache('key')
    if (cached) this.$end(cached)  // Exit early with cached data
    return null
  },
  async fetchFromApi() {
    const user = await this.$.checkCache  // Will throw if cache hit
    return await fetchExpensiveData()
  },
  async processData() {
    const apiData = await this.$.fetchFromApi
    this.$end(transform(apiData))
  }
})

The flow<R>(tasks, options?) function allows you to execute tasks in parallel while enabling any task to terminate the entire flow early by calling this.$end(value). The first task to call $end() determines the final return value of the flow.

Key Behaviors:

• Parallelism: All tasks start simultaneously.
• Termination: Once $end(value) is called, subsequent attempts by other tasks to access dependencies via this.$.taskName will fail (these failures are caught silently).
• Return Type: You must provide a type parameter <R> that defines the type of value $end() accepts.
• Undefined Returns: If no task calls $end(), the flow returns undefined. To allow $end(undefined), you must explicitly include undefined in your type parameter (e.g., flow<string | undefined>).

// Example: Racing operations
const result = await flow<ResponseData>({
  async fetchFromPrimary() {
    await sleep(100)
    const data = await fetch('/api/primary')
    this.$end(await data.json())
  },
  async fetchFromBackup() {
    await sleep(500)
    const data = await fetch('/api/backup')
    this.$end(await data.json())
  }
})
// Returns data from whichever endpoint responds first

The all(tasks, options?) function executes tasks with automatic dependency resolution. It returns a promise that resolves to an object containing all task results. If any task fails, the entire call rejects (similar to Promise.all).

Parameters:

• tasks: An object where keys are task names and values are async functions.
• options (optional):
  • debug: Boolean. If true, outputs an ASCII waterfall chart of the execution.
  • signal: An AbortSignal to abort all tasks externally.

Task Context (this): Each task function has access to:

• this.$: An object containing promises for all other task results.
• this.$signal: An AbortSignal that aborts when any sibling task fails.

Returns: A promise resolving to an object of results.

import { all } from 'better-all'

const { user, profile, settings } = await all({
  async user() { return fetchUser(1) },
  async profile() { return fetchProfile((await this.$.user).id) },
  async settings() { return fetchSettings((await this.$.user).id) }
})

The allSettled() method ensures all tasks complete and returns their settled state. It never rejects. Each result object contains a status of either 'fulfilled' or 'rejected'.

• If status is 'fulfilled', the result contains a value.
• If status is 'rejected', the result contains a reason.

Note on Dependencies: If a task depends on a failed task via this.$.taskName, that dependent task will also fail (becoming 'rejected') unless the error is caught locally within the task using a try/catch block.

const result = await allSettled({
  async a() { return 1 },
  async b() { throw new Error('Task b failed') },
  async c() { return 3 }
})

// result.a: { status: 'fulfilled', value: 1 }
// result.b: { status: 'rejected', reason: Error('Task b failed') }
// result.c: { status: 'fulfilled', value: 3 }

if (result.a.status === 'fulfilled') {
  console.log(result.a.value) // 1
}

if (result.b.status === 'rejected') {
  console.error(result.b.reason) // Error: Task b failed
}