taskAction

Task-based actions for managing queued or concurrent work.

import { taskAction } from 'mates';

const uploadFile = taskAction(async (file: File, signal: AbortSignal) => {
  const form = new FormData();
  form.append('file', file);
  const res = await fetch('/api/upload', { method: 'POST', body: form, signal });
  if (!res.ok) throw new Error('Upload failed');
  return res.json();
});

uploadFile.clearAndStart([fileA, fileB, fileC], 2);
uploadFile.addAndStart(fileD, 2);
uploadFile.pause();
uploadFile.start(2);
uploadFile.stop();

uploadFile.isRunning();
uploadFile.progress();
uploadFile.tasks();
uploadFile.runningTasks();
uploadFile.successTasks();
uploadFile.failedTasks();
uploadFile.cancelledTasks();

Overview

taskAction manages a concurrent task queue. You add items, control concurrency, and track per-task status, progress, and results — all reactively. Ideal for file uploads, imports, offline sync replay, or any workflow where multiple async jobs should be orchestrated together.

Each task receives an AbortSignal as its second argument so cancellation via stop() (or per-task abort) can cleanly unwind in-flight work. Derived getters like runningTasks() and successTasks() let you drive progress UI without manual bookkeeping.

vs asyncAction

Capability	asyncAction	taskAction
Unit of work	Single invocation	Queue of many items with per-task lifecycle.
Concurrency	One in-flight (latest wins / cancel)	Configurable concurrency (serial by default, or N at once).
Progress	isLoading / status	`progress()` 0–100 + filtered task lists by status.
Cancellation	`cancel()` drops result	`stop()` / per-task `AbortSignal` for real abort.

taskAction — queue, concurrency, pause, delete

clearAndStart with concurrency 2. addAndStart appends while running. pause() lets in-flight tasks finish; start() resumes; stop() aborts via the task signal; delete() removes one task.

import { html, taskAction, nothing, renderApp } from 'mates';

const processTask = taskAction(async (item, signal) => {

const ms = 800 + Math.random() * 1200;

await new Promise((resolve, reject) => {

const id = setTimeout(resolve, ms);

signal.addEventListener('abort', () => {

clearTimeout(id);

reject(new Error('cancelled'));

}, { once: true });

});

if (item.name.endsWith('.fail')) throw new Error('failed');

return { processed: item.name, duration: Math.round(ms) };

});

const ITEMS = [

{ id: 1, name: 'document.pdf' },

{ id: 2, name: 'image.png' },

{ id: 3, name: 'video.mp4' },

{ id: 4, name: 'data.csv' },

{ id: 5, name: 'report.xlsx' },

];

let extra = 6;

const statusColor = {

pending: '#64748b', running: '#f59e0b',

success: '#22c55e', failed: '#ef4444', cancelled: '#94a3b8',

};

const App = () => {

return () => html`

<button class="btn-primary"

?disabled=${processTask.isRunning()}

API — taskAction

import { taskAction } from 'mates'

Prop / Option	Type	Default	Description
`taskAction(fn)`*	`TaskActionType`	—	Creates a task queue. fn receives (input, signal) where signal is an AbortSignal wired to the task's abort controller.

Queue control

Prop / Option	Type	Default	Description
`addAndStart(input, concurrency?)`	`void`	—	Append one or more items and start processing if not already running. concurrency defaults to 1 (serial).
`clearAndStart(input, concurrency?)`	`void`	—	Stop the current session, replace the task list, and immediately begin processing. Useful for fresh re-runs.
`add(input)`	`void`	—	Append one or more tasks to the queue without starting. Call start() separately when ready.
`start(concurrency?)`	`void`	—	Begin (or resume) processing. No-op if already running. concurrency defaults to 1.
`stop()`	`void`	—	Immediately cancel all running tasks (aborting their signals) and transition to idle. Pending tasks remain in the list.
`pause()`	`void`	—	Soft pause — lets running tasks finish but prevents new ones from launching. Call start() to resume.

Reactive state

Prop / Option	Type	Default	Description
`isRunning()`	`boolean`	—	Reactive getter — true while the session status is 'running'.
`tasks()`	`Task[]`	—	Reactive atom containing every task in insertion order, regardless of status. Call it inside templates to subscribe.
`progress()`	`number`	—	Reactive 0–100 progress value. Pending = 0 pts, running = 0.5 pts, settled = 1 pt.
`runningTasks()`	`Task[]`	—	Derived reactive getter — tasks currently in 'running' status.
`pendingTasks()`	`Task[]`	—	Derived reactive getter — tasks waiting in 'pending' status.
`successTasks()`	`Task[]`	—	Derived reactive getter — tasks that completed successfully.
`failedTasks() / cancelledTasks()`	`Task[]`	—	Derived reactive getters for failed and cancelled tasks respectively.

Task shape

Prop / Option	Type	Default	Description
`task.id`	`number`	—	Auto-incremented unique identifier assigned on creation.
`task.status`	`"pending" \| "running" \| "success" \| "failed" \| "cancelled"`	—	Current lifecycle state of the task.
`task.input`	`TInput`	—	The original input value passed to add() / addAndStart().
`task.result.data`	`TOutput \| null`	—	Resolved return value of fn on success, null otherwise.
`task.result.error`	`Error \| null`	—	Error thrown by fn on failure, null otherwise.
`task.abortController`	`AbortController`	—	Controller wired to the task's abort signal. Call task.abortController.abort() to cancel a specific running task.