@baack-software/baack-ts-tasks 0.0.0-stage → 0.0.1

package/src/task-client.ts

@@ -0,0 +1,373 @@
+import {
+  Endpoint,
+  isBaackApiError,
+  type BaackClient,
+  type Company,
+  type IncludeScope,
+  type Search,
+  type SearchItem,
+  type Task,
+  type TaskLog,
+  type TaskPriority,
+  type TaskStatus,
+  type Workflow,
+} from '@baack-software/baack-ts-client';
+import { draft as makeDraft, isEmptyChange, updateBody, validateTask, type DraftInput } from './draft.ts';
+import { changedFields, fieldsChanged, findConflicts, rebaseLists, type TaskField } from './conflicts.ts';
+import { TaskConflictError, TaskSearchTimeoutError, TaskValidationError } from './errors.ts';
+import { ref, urnOf, withRef, withoutRef } from './refs.ts';
+import { TASK_LIST_FIELDS, type RefLike, type TaskDraft, type TaskInput, type TaskListField, type TaskLogPage } from './types.ts';
+
+/** Options for a change: who made it, for the activity log. */
+export interface ChangeOptions {
+  /** The identity the change is attributed to in the activity log. It does not assign the task. */
+  actor?: RefLike;
+}
+
+export interface UpdateOptions extends ChangeOptions {
+  /**
+   * The task as the person saw it when they made the change, usually the copy the editor shows. When given, the update
+   * is checked against it: if someone else changed a field this update also changes, it throws `TaskConflictError`
+   * and saves nothing; list changes are applied as additions and removals to the lists as they are now.
+   */
+  base?: Task | undefined;
+  /** Told which fields someone else changed since `base` that this update leaves as they are. */
+  onChangedElsewhere?: ((fields: (TaskField | TaskListField)[], current: Task) => void) | undefined;
+}
+
+export interface CommentOptions {
+  /** The identity making the comment. */
+  actor?: RefLike;
+  /** The log entry this comment replies to. */
+  replyTo?: RefLike;
+}
+
+export interface PollOptions {
+  /** First wait between reads of a running search. Default 250 ms. */
+  intervalMs?: number;
+  /** Longest wait between reads; waits grow by half each time up to this. Default 2000 ms. */
+  maxIntervalMs?: number;
+  /** Give up with `TaskSearchTimeoutError` after this long. Default 30000 ms. */
+  timeoutMs?: number;
+}
+
+export interface ListOptions {
+  /** The company whose tasks to list. */
+  owner: RefLike;
+  /**
+   * Also return the identities and projects the reader can see, for assignee and project pickers and names.
+   * Default true. Turn off for readers without access to them.
+   */
+  includeRelated?: boolean;
+  /** How many tasks to read at once. Default 6. */
+  concurrency?: number;
+  poll?: PollOptions;
+  /** Stops polling and reading. A request already sent still completes. */
+  signal?: AbortSignal;
+}
+
+export interface TaskListing {
+  /** The tasks, in the search's order. Tasks deleted between the search and the read are left out. */
+  tasks: Task[];
+  /** Identities seen by the search, with their names. Empty when `includeRelated` is false. */
+  identities: SearchItem[];
+  /** Projects seen by the search, with their names. Empty when `includeRelated` is false. */
+  projects: SearchItem[];
+}
+
+/**
+ * Typed access to Baack tasks and their activity logs, on top of a `BaackClient` that holds the base URL and
+ * credentials.
+ *
+ * ```ts
+ * const tasks = new TaskClient(new BaackClient({ baseUrl: 'https://api.baack.co', credentials: 'include' }));
+ * const { tasks: all } = await tasks.list({ owner: companyUrn });
+ * await tasks.setStatus(all[0], 'IN_PROGRESS', { actor: me });
+ * ```
+ */
+export class TaskClient {
+  constructor(readonly client: BaackClient) {}
+
+  // ==========================================
+  // TASKS
+  // ==========================================
+
+  async get(task: RefLike): Promise<Task> {
+    return this.client.read<Task>(Endpoint.TASK, urnOf(task));
+  }
+
+  /** Reads a workflow: its name and its stages, which tasks move through. */
+  async getWorkflow(workflow: RefLike): Promise<Workflow> {
+    return this.client.read<Workflow>(Endpoint.WORKFLOW, urnOf(workflow));
+  }
+
+  /**
+   * Creates a task. Accepts a full `TaskDraft`, or the owner and title plus any other fields, which `draft` fills in.
+   * Throws `TaskValidationError` before sending when the task breaks the API's rules.
+   */
+  async create(input: TaskDraft | DraftInput, options: ChangeOptions = {}): Promise<Task> {
+    const body: TaskInput = withActor(makeDraft(input), options);
+    const issues = validateTask(body, { creating: true });
+    if (issues.length > 0) throw new TaskValidationError(issues);
+    return this.client.create<Task>(Endpoint.TASK, body);
+  }
+
+  /**
+   * Changes the task. The API stores the task as an update sends it, clearing optional fields left out, so this reads
+   * the task, applies `changes` and sends it whole (see `updateBody`). Lists are sent whole and the server applies the
+   * difference. Updates to the same task from this client run one at a time, so each builds on the last.
+   *
+   * `changes` can be a function of the task as just read, for changes built from its current state, such as adding
+   * to a list.
+   *
+   * Throws `TaskValidationError` before sending when the changes break the API's rules. Returns the task as the
+   * server has it after the change.
+   *
+   * The `BaackClient`'s `failureGuard` applies: retrying a failed update before its backoff has passed fails at once
+   * with the same error, sending nothing.
+   */
+  async update(
+    task: RefLike,
+    changes: TaskInput | ((current: Task) => TaskInput),
+    options: UpdateOptions = {},
+  ): Promise<Task> {
+    const urn = urnOf(task);
+    const { base, onChangedElsewhere, ...change } = options;
+    if (typeof changes !== 'function') {
+      check(changes, urn);
+      if (isEmptyChange(changes) && typeof task !== 'string' && isTask(task)) return task;
+    }
+    return this.#inTurn(urn, async () => {
+      const current = await this.get(urn);
+      let changed = typeof changes === 'function' ? changes(current) : changes;
+      if (typeof changes === 'function') check(changed, urn);
+      if (base) {
+        // Reported even when the update then stops on a conflict, since the person sees the task as it is now.
+        const touched = new Set<string>([...fieldsChanged(changed), ...TASK_LIST_FIELDS.filter((f) => changed[f] !== undefined)]);
+        const elsewhere = changedFields(base, current).filter((field) => !touched.has(field));
+        if (elsewhere.length > 0) onChangedElsewhere?.(elsewhere, current);
+        const conflicts = findConflicts(base, current, changed);
+        if (conflicts.length > 0) throw new TaskConflictError(conflicts, current);
+        changed = rebaseLists(base, current, changed);
+      }
+      return this.client.update<Task>(Endpoint.TASK, urn, withActor(updateBody(current, changed), change));
+    });
+  }
+
+  /** Updates waiting or running, by task URN. */
+  readonly #turns = new Map<string, Promise<unknown>>();
+
+  /** Runs `work` after the task's earlier updates settle, whether they succeeded or not. */
+  #inTurn<T>(urn: string, work: () => Promise<T>): Promise<T> {
+    const result = (this.#turns.get(urn) ?? Promise.resolve()).catch(() => undefined).then(work);
+    this.#turns.set(urn, result);
+    const forget = () => {
+      if (this.#turns.get(urn) === result) this.#turns.delete(urn);
+    };
+    result.then(forget, forget);
+    return result;
+  }
+
+  async delete(task: RefLike): Promise<void> {
+    await this.client.delete(Endpoint.TASK, urnOf(task));
+  }
+
+  setStatus(task: RefLike, status: TaskStatus, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { status }, options);
+  }
+
+  setPriority(task: RefLike, priority: TaskPriority, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { priority }, options);
+  }
+
+  /** Assigns the task to `assignee`, or unassigns it with `null`. */
+  assign(task: RefLike, assignee: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { assignee: assignee === null ? null : ref(assignee) }, options);
+  }
+
+  /** Sets the due date (a Baack timestamp, see `toTimestamp`), or removes it with `null`. */
+  setDue(task: RefLike, dueTimestamp: string | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { dueTimestamp }, options);
+  }
+
+  /** Moves the task into `project`, or out of its project with `null`. */
+  setProject(task: RefLike, project: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { project: project === null ? null : ref(project) }, options);
+  }
+
+  /** Moves the task to a workflow stage, or out of its stage with `null`. */
+  setWorkflowStage(task: RefLike, stage: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { workflowStage: stage === null ? null : ref(stage) }, options);
+  }
+
+  /** Marks `blocker` as blocking `task`. */
+  addBlocker(task: RefLike, blocker: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.addTo(task, 'blockedBy', blocker, options);
+  }
+
+  removeBlocker(task: RefLike, blocker: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.removeFrom(task, 'blockedBy', blocker, options);
+  }
+
+  /** Adds a reference to one of the task's lists, as the server has the list when the update is sent. */
+  addTo(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, (current) => ({ [field]: withRef(current[field], value) }), options);
+  }
+
+  /** Removes a reference from one of the task's lists, as the server has the list when the update is sent. */
+  removeFrom(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, (current) => ({ [field]: withoutRef(current[field], value) }), options);
+  }
+
+  // ==========================================
+  // ACTIVITY LOG
+  // ==========================================
+
+  /** One page of the task's activity log, newest first. Pass `pagination.after` from a page to read the next. */
+  async logs(task: RefLike, options: { after?: string } = {}): Promise<TaskLogPage> {
+    const page = await this.client.read<TaskLogPage | undefined>(Endpoint.TASK_LOGS, urnOf(task), {
+      after: options.after,
+    });
+    return { logs: page?.logs ?? [], pagination: page?.pagination ?? null };
+  }
+
+  /** The task's activity log across pages, newest first, stopping after `limit` entries when given. */
+  async allLogs(task: RefLike, options: { limit?: number } = {}): Promise<TaskLog[]> {
+    const { limit = Number.POSITIVE_INFINITY } = options;
+    const logs: TaskLog[] = [];
+    let after: string | undefined;
+    do {
+      const page = await this.logs(task, after === undefined ? {} : { after });
+      logs.push(...page.logs);
+      after = page.pagination?.isMorePages ? (page.pagination.after ?? undefined) : undefined;
+    } while (after !== undefined && logs.length < limit);
+    return logs.slice(0, limit);
+  }
+
+  /** Adds a comment to the task's activity log. */
+  async comment(task: RefLike, comment: string, options: CommentOptions = {}): Promise<TaskLog> {
+    const body: Record<string, unknown> = { task: ref(task), activity: 'COMMENT_ADDED', comment };
+    if (options.actor !== undefined) body['identity'] = ref(options.actor);
+    if (options.replyTo !== undefined) body['replyTo'] = ref(options.replyTo);
+    return this.client.create<TaskLog>(Endpoint.TASK_LOG, body);
+  }
+
+  // ==========================================
+  // LISTING
+  // ==========================================
+
+  /**
+   * Lists a company's tasks. Runs a search, waits for its full result, follows its pages, then
+   * reads each task (search results don't carry the task itself yet).
+   */
+  async list(options: ListOptions): Promise<TaskListing> {
+    const { includeRelated = true, concurrency = 6, signal } = options;
+    const scopes: IncludeScope[] = includeRelated ? ['TASK', 'IDENTITY', 'PROJECT'] : ['TASK'];
+    const items = await this.search(
+      { owner: options.owner, scopes },
+      { ...(options.poll ?? {}), ...(signal ? { signal } : {}) },
+    );
+
+    const taskItems = items.filter((item) => item.type === 'TASK');
+    const tasks = await mapLimit(taskItems, concurrency, signal, async (item) => {
+      if (item.item && isTask(item.item)) return item.item;
+      try {
+        return await this.get(item.urn);
+      } catch (error) {
+        if (isBaackApiError(error) && error.isNotFound) return undefined;
+        throw error;
+      }
+    });
+
+    return {
+      tasks: tasks.filter((task): task is Task => task !== undefined),
+      identities: items.filter((item) => item.type === 'IDENTITY'),
+      projects: items.filter((item) => item.type === 'PROJECT'),
+    };
+  }
+
+  /**
+   * Runs a search and returns every item once the result is full, across pages. Exposed for callers that want other
+   * scopes alongside tasks.
+   */
+  async search(
+    query: { owner: RefLike; scopes: IncludeScope[] },
+    options: PollOptions & { signal?: AbortSignal } = {},
+  ): Promise<SearchItem[]> {
+    const { intervalMs = 250, maxIntervalMs = 2000, timeoutMs = 30000, signal } = options;
+    const deadline = Date.now() + timeoutMs;
+
+    // The API resolves the owner by URN; the client's Company type also wants a url.
+    const body: Search = { owner: ref(query.owner) as Company, includeScopes: query.scopes };
+
+    signal?.throwIfAborted();
+    let search = await this.client.search(body);
+    let wait = intervalMs;
+    while (search.status !== 'FULL_RESULT') {
+      if (!search.urn) throw new Error('The search API returned a search without a URN');
+      if (Date.now() + wait > deadline) throw new TaskSearchTimeoutError(search.urn, timeoutMs);
+      await sleep(wait, signal);
+      search = await this.client.searchResult(search.urn);
+      wait = Math.min(Math.round(wait * 1.5), maxIntervalMs);
+    }
+
+    const items = [...(search.items ?? [])];
+    let pagination = search.pagination;
+    while (pagination?.isMorePages && pagination.after && search.urn) {
+      signal?.throwIfAborted();
+      const page = await this.client.searchResult(search.urn, pagination.after);
+      items.push(...(page.items ?? []));
+      pagination = page.pagination;
+    }
+    return items;
+  }
+}
+
+/** Throws `TaskValidationError` when the changes break the API's rules. */
+function check(changes: TaskInput, urn: string): void {
+  const issues = validateTask(changes, { urn });
+  if (issues.length > 0) throw new TaskValidationError(issues);
+}
+
+function withActor<T extends TaskInput>(input: T, options: ChangeOptions): T {
+  return options.actor === undefined ? input : { ...input, identityForLogs: ref(options.actor) };
+}
+
+function isTask(value: unknown): value is Task {
+  return typeof value === 'object' && value !== null && 'urn' in value && 'title' in value && 'status' in value;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/** Maps `items` with at most `limit` calls running at once, keeping the input order. */
+async function mapLimit<T, R>(
+  items: readonly T[],
+  limit: number,
+  signal: AbortSignal | undefined,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      signal?.throwIfAborted();
+      const index = next++;
+      results[index] = await fn(items[index]!);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker));
+  return results;
+}

package/src/tasks.ts

@@ -0,0 +1,263 @@
+import type { Task, TaskPriority, TaskStatus, Workflow, WorkflowStage } from '@baack-software/baack-ts-client';
+import { urnOf } from './refs.ts';
+import { parseTimestamp } from './time.ts';
+import type { RefLike } from './types.ts';
+
+/** Statuses in board order, from not started to done. */
+export const TASK_STATUSES: readonly TaskStatus[] = [
+  'UNDEFINED',
+  'PENDING',
+  'IN_PROGRESS',
+  'BLOCKED',
+  'COMPLETED',
+  'CLOSED',
+];
+
+/** Priorities from lowest to highest. */
+export const TASK_PRIORITIES: readonly TaskPriority[] = ['NONE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+
+export const STATUS_LABELS: Readonly<Record<TaskStatus, string>> = {
+  UNDEFINED: 'Undefined',
+  PENDING: 'Pending',
+  IN_PROGRESS: 'In progress',
+  BLOCKED: 'Blocked',
+  COMPLETED: 'Completed',
+  CLOSED: 'Closed',
+};
+
+export const PRIORITY_LABELS: Readonly<Record<TaskPriority, string>> = {
+  NONE: 'None',
+  LOW: 'Low',
+  MEDIUM: 'Medium',
+  HIGH: 'High',
+  CRITICAL: 'Critical',
+};
+
+const DONE: ReadonlySet<TaskStatus> = new Set(['COMPLETED', 'CLOSED']);
+
+/** Whether a status means the work is finished: completed or closed. */
+export function isDoneStatus(status: TaskStatus | null | undefined): boolean {
+  return status != null && DONE.has(status);
+}
+
+/** Whether the task still needs work: not completed or closed. */
+export function isOpen(task: Pick<Task, 'status'>): boolean {
+  return !isDoneStatus(task.status);
+}
+
+/** The task's due date, or undefined when it has none. */
+export function dueDate(task: Pick<Task, 'dueTimestamp'>): Date | undefined {
+  return parseTimestamp(task.dueTimestamp);
+}
+
+/** Whether an open task is past its due date. */
+export function isOverdue(task: Pick<Task, 'status' | 'dueTimestamp'>, now: Date = new Date()): boolean {
+  const due = dueDate(task);
+  return isOpen(task) && due !== undefined && due.getTime() < now.getTime();
+}
+
+/** Whether an open task is due within `ms` from now, and not yet overdue. */
+export function isDueWithin(
+  task: Pick<Task, 'status' | 'dueTimestamp'>,
+  ms: number,
+  now: Date = new Date(),
+): boolean {
+  const due = dueDate(task);
+  if (!isOpen(task) || due === undefined) return false;
+  const left = due.getTime() - now.getTime();
+  return left >= 0 && left <= ms;
+}
+
+// ==========================================
+// SORTING
+// ==========================================
+
+export type TaskComparator = (a: Task, b: Task) => number;
+
+/** Highest priority first. */
+export const byPriority: TaskComparator = (a, b) =>
+  TASK_PRIORITIES.indexOf(b.priority) - TASK_PRIORITIES.indexOf(a.priority);
+
+/** Board order of status. */
+export const byStatus: TaskComparator = (a, b) => TASK_STATUSES.indexOf(a.status) - TASK_STATUSES.indexOf(b.status);
+
+/** Soonest due first; tasks without a due date last. */
+export const byDue: TaskComparator = (a, b) => {
+  const [first, second] = [timeOrInfinity(a.dueTimestamp), timeOrInfinity(b.dueTimestamp)];
+  // Two tasks without due dates tie (Infinity - Infinity is NaN, which would stop the next comparator breaking it).
+  return first === second ? 0 : first - second;
+};
+
+/** Most recently updated first. */
+export const byUpdated: TaskComparator = (a, b) =>
+  -(timeOrInfinity(a.updatedTimestamp, 0) - timeOrInfinity(b.updatedTimestamp, 0));
+
+/** Title, alphabetically. */
+export const byTitle: TaskComparator = (a, b) => a.title.localeCompare(b.title);
+
+/** Sorts by each comparator in turn, using the next to break ties. */
+export function compareBy(...comparators: TaskComparator[]): TaskComparator {
+  return (a, b) => {
+    for (const compare of comparators) {
+      const result = compare(a, b);
+      if (result !== 0) return result;
+    }
+    return 0;
+  };
+}
+
+/** Open tasks before completed and closed ones. */
+export const byOpen: TaskComparator = (a, b) => Number(isOpen(b)) - Number(isOpen(a));
+
+/** A sensible default for work lists: open first, then overdue and soonest due, then highest priority. */
+export const byUrgency: TaskComparator = compareBy(byOpen, byDue, byPriority, byTitle);
+
+/** Within a board column: open first, then highest priority, soonest due and title, so ties are stable. */
+export const byPriorityThenDue: TaskComparator = compareBy(byOpen, byPriority, byDue, byTitle);
+
+function timeOrInfinity(timestamp: string | null | undefined, fallback = Number.POSITIVE_INFINITY): number {
+  return parseTimestamp(timestamp)?.getTime() ?? fallback;
+}
+
+// ==========================================
+// FILTERING
+// ==========================================
+
+/**
+ * Criteria for `matchesFilter`. Each criterion left out matches every task; all given criteria must match. For
+ * `assignee`, `project` and `workflowStage`, `null` in the list matches tasks with none set.
+ */
+export interface TaskFilter {
+  status?: readonly TaskStatus[];
+  priority?: readonly TaskPriority[];
+  assignee?: readonly (RefLike | null)[];
+  project?: readonly (RefLike | null)[];
+  workflowStage?: readonly (RefLike | null)[];
+  /** Tasks that block on, are blocking, or are associated with this representation. */
+  relatedTo?: RefLike;
+  /** `true` for open tasks only, `false` for done tasks only. */
+  open?: boolean;
+  /** Only open tasks past their due date. */
+  overdue?: boolean;
+  /** Case-insensitive match against the title and description. */
+  text?: string;
+}
+
+export function matchesFilter(task: Task, filter: TaskFilter, now: Date = new Date()): boolean {
+  if (filter.status && !filter.status.includes(task.status)) return false;
+  if (filter.priority && !filter.priority.includes(task.priority)) return false;
+  if (filter.assignee && !matchesRef(task.assignee, filter.assignee)) return false;
+  if (filter.project && !matchesRef(task.project, filter.project)) return false;
+  if (filter.workflowStage && !matchesRef(task.workflowStage, filter.workflowStage)) return false;
+  if (filter.relatedTo !== undefined && !isRelatedTo(task, filter.relatedTo)) return false;
+  if (filter.open !== undefined && isOpen(task) !== filter.open) return false;
+  if (filter.overdue && !isOverdue(task, now)) return false;
+  if (filter.text) {
+    const needle = filter.text.toLocaleLowerCase();
+    const haystack = `${task.title}\n${task.description}`.toLocaleLowerCase();
+    if (!haystack.includes(needle)) return false;
+  }
+  return true;
+}
+
+export function filterTasks(tasks: readonly Task[], filter: TaskFilter, now: Date = new Date()): Task[] {
+  return tasks.filter((task) => matchesFilter(task, filter, now));
+}
+
+/** Whether the task refers to `target` in its blockers, blocked tasks or associations. */
+export function isRelatedTo(task: Task, target: RefLike): boolean {
+  const urn = urnOf(target);
+  const lists = [
+    task.blockedBy,
+    task.blocking,
+    task.associatedTasks,
+    task.associatedEntities,
+    task.associatedIdentities,
+    task.associatedCompanies,
+  ];
+  return lists.some((list) => list?.some((item) => item.urn === urn));
+}
+
+function matchesRef(value: { urn: string } | null | undefined, wanted: readonly (RefLike | null)[]): boolean {
+  return wanted.some((candidate) => (candidate === null ? value == null : value?.urn === urnOf(candidate)));
+}
+
+// ==========================================
+// GROUPING
+// ==========================================
+
+export type TaskGrouping = 'status' | 'priority' | 'assignee' | 'project' | 'workflow' | 'workflowStage';
+
+/** The key used for tasks without an assignee, project, workflow or workflow stage. */
+export const NONE_KEY = '';
+
+/**
+ * Groups tasks into columns, keyed by status, priority, or the URN of the assignee, project or workflow stage
+ * (`NONE_KEY` when unset). Status and priority groups always contain every value in order, so a board shows empty
+ * columns; priority runs highest first. Other groups appear in order of first use.
+ */
+export function groupTasks(tasks: readonly Task[], by: TaskGrouping): Map<string, Task[]> {
+  const groups = new Map<string, Task[]>();
+  if (by === 'status') TASK_STATUSES.forEach((status) => groups.set(status, []));
+  if (by === 'priority') [...TASK_PRIORITIES].reverse().forEach((priority) => groups.set(priority, []));
+  for (const task of tasks) {
+    const key = groupKey(task, by);
+    const group = groups.get(key);
+    if (group) group.push(task);
+    else groups.set(key, [task]);
+  }
+  return groups;
+}
+
+/** A workflow's stages in order. */
+export function workflowStages(workflow: Workflow): WorkflowStage[] {
+  return [...(workflow.stages ?? [])].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+}
+
+/**
+ * Groups tasks into a workflow's stages, keyed by stage URN, every stage in order even when empty. Tasks in no stage,
+ * or in another workflow's, go under `NONE_KEY`, last, which is left out when empty.
+ */
+export function groupByStage(tasks: readonly Task[], workflow: Workflow): Map<string, Task[]> {
+  const groups = new Map<string, Task[]>(workflowStages(workflow).map((stage) => [stage.urn, []]));
+  const rest: Task[] = [];
+  for (const task of tasks) (groups.get(task.workflowStage?.urn ?? NONE_KEY) ?? rest).push(task);
+  if (rest.length > 0) groups.set(NONE_KEY, rest);
+  return groups;
+}
+
+/** The workflow a task is in: the one its stage belongs to, as a task records only its stage. */
+export function workflowOf(task: Task, workflows: readonly Workflow[]): Workflow | undefined {
+  const stage = task.workflowStage?.urn;
+  return stage ? workflows.find((workflow) => workflow.stages?.some((s) => s.urn === stage)) : undefined;
+}
+
+/**
+ * Groups tasks by workflow, keyed by workflow URN, every workflow in the order given even when empty. Tasks in no
+ * workflow's stage go under `NONE_KEY`, last, which is left out when empty.
+ */
+export function groupByWorkflow(tasks: readonly Task[], workflows: readonly Workflow[]): Map<string, Task[]> {
+  const groups = new Map<string, Task[]>(workflows.map((workflow) => [workflow.urn, []]));
+  const rest: Task[] = [];
+  for (const task of tasks) (groups.get(workflowOf(task, workflows)?.urn ?? NONE_KEY) ?? rest).push(task);
+  if (rest.length > 0) groups.set(NONE_KEY, rest);
+  return groups;
+}
+
+function groupKey(task: Task, by: TaskGrouping): string {
+  switch (by) {
+    case 'status':
+      return task.status;
+    case 'priority':
+      return task.priority;
+    case 'assignee':
+      return task.assignee?.urn ?? NONE_KEY;
+    case 'project':
+      return task.project?.urn ?? NONE_KEY;
+    case 'workflowStage':
+      return task.workflowStage?.urn ?? NONE_KEY;
+    // A task's workflow is found from its stage, which needs the workflows: `groupByWorkflow`.
+    case 'workflow':
+      return NONE_KEY;
+  }
+}

package/src/time.ts

@@ -0,0 +1,35 @@
+/**
+ * Baack timestamps are ISO 8601 in UTC without a zone, for example `2025-09-13T17:08:00` or `2025-09-13T17:08:00.000`.
+ * A plain `new Date(timestamp)` would read them as local time, so use these helpers instead.
+ */
+
+const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+
+/** Reads a Baack timestamp as a `Date`, or undefined when it is empty or not a valid timestamp. */
+export function parseTimestamp(timestamp: string | null | undefined): Date | undefined {
+  if (!timestamp) return undefined;
+  const date = new Date(HAS_ZONE.test(timestamp) ? timestamp : timestamp + 'Z');
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+/** Writes a `Date` as a Baack timestamp: UTC, with milliseconds, without a zone. */
+export function toTimestamp(date: Date): string {
+  return date.toISOString().replace(/Z$/, '');
+}
+
+/**
+ * The value for an `<input type="datetime-local">` showing a Baack timestamp in the viewer's local time, or `''`.
+ */
+export function toLocalInput(timestamp: string | null | undefined): string {
+  const date = parseTimestamp(timestamp);
+  if (!date) return '';
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/** Reads an `<input type="datetime-local">` value (local time) as a Baack timestamp, or undefined when empty. */
+export function fromLocalInput(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : toTimestamp(date);
+}