@santana-org/task

📦 Install

npm install @santana-org/task
pnpm add @santana-org/task

🚀 Quickstart

import { runTasks } from "@santana-org/task"

await runTasks([
  {
    title: "Installing dependencies",
    task: async () => { await installDeps() },
  },
  {
    title: "Building project",
    task: async ({ update }) => {
      update("Compiling TypeScript…")
      await build()
    },
  },
])

Each task shows a live spinner while running and a status line on completion:

✓ Installing dependencies  1.2s
✓ Building project  3.4s

📖 API

runTasks(tasks, options?)

Run an array of tasks, showing a spinner per task.

interface TaskDefinition<T = unknown> {
  title: string
  task: (ctx: TaskContext) => Promise<T>
  skip?: () => boolean | Promise<boolean>
}

interface TaskContext {
  update(message: string): void
}

| Option | Type | Default | Description | |---|---|---|---| | concurrency | number | 1 | Max tasks running in parallel | | exitOnError | boolean | true | Stop remaining tasks if one fails | | colorsEnabled | boolean | auto | Force or disable colorized output |

Returns TaskResult<T>[] — one entry per task in the same order.

runTask(title, fn, options?)

Convenience wrapper for a single task:

const result = await runTask("Fetching config", async ({ update }) => {
  update("Connecting to registry…")
  return await fetchConfig()
})

🧩 Recipes

Parallel tasks

await runTasks(tasks, { concurrency: 4 })

Continue on failure

const results = await runTasks(tasks, { exitOnError: false })

for (const result of results) {
  if (result.status === "error") {
    console.error(`${result.title} failed:`, result.error)
  }
}

Conditional skip

await runTasks([
  {
    title: "Running tests",
    skip: () => process.env.SKIP_TESTS === "1",
    task: async () => { await runTests() },
  },
])

🏗️ Design decisions

• Spinner per task. Uses @santana-org/ui spinners — same visual style across all Santana Org CLIs.
• Duration on completion. Every completed task line includes elapsed time via @santana-org/fmt.
• Parallel by default opt-in. Sequential by default to avoid interleaved spinner output; opt into concurrency explicitly.
• ESM-first. CJS interop included, but the package is written for modern runtimes.

📄 License

MIT © santana-org — contributions are welcome, see CONTRIBUTING.