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

package/src/store.ts

@@ -0,0 +1,538 @@
+import {
+  isBaackApiError,
+  type SearchItem,
+  type Task,
+  type TaskLog,
+  type TaskPriority,
+  type TaskStatus,
+  type Workflow,
+} from '@baack-software/baack-ts-client';
+import { openBlockers as openBlockersOf } from './blockers.ts';
+import type { TaskField } from './conflicts.ts';
+import { applyChanges, type DraftInput } from './draft.ts';
+import { TaskConflictError } from './errors.ts';
+import { ref, urnOf, withRef, withoutRef } from './refs.ts';
+import type { ChangeOptions, TaskClient } from './task-client.ts';
+import {
+  filterTasks,
+  groupTasks,
+  type TaskComparator,
+  type TaskFilter,
+  type TaskGrouping,
+} from './tasks.ts';
+import type { RefLike, TaskDraft, TaskInput, TaskListField } from './types.ts';
+
+export interface TaskStoreOptions {
+  /** The company whose tasks the store holds. */
+  owner: RefLike;
+  /** The identity changes are attributed to in the activity log, unless a change names another. */
+  actor?: RefLike;
+  /** Load identities and projects for names and pickers. Default true. */
+  includeRelated?: boolean;
+  /**
+   * Workflows whose stages tasks can move through, loaded with the tasks for stage columns and pickers. The API has
+   * no way to list them, so the app names them. One that can't be read is left out.
+   */
+  workflows?: readonly RefLike[];
+  /**
+   * The server can change a task after accepting a write. This long after each write, the store reads the task (and
+   * its log, if loaded) again. Default 500 ms; 0 turns it off.
+   */
+  settleMs?: number;
+}
+
+export type LoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+export interface TaskLogState {
+  status: LoadStatus;
+  /** Newest first. */
+  logs: readonly TaskLog[];
+  /** Set while older pages remain. */
+  after?: string;
+  error?: unknown;
+}
+
+/** A snapshot of the store. Each change replaces it, so it can be compared by reference. */
+export interface TaskStoreState {
+  status: LoadStatus;
+  error?: unknown;
+  /** Tasks as the reader should see them, pending changes applied, in search order with new tasks first. */
+  tasks: readonly Task[];
+  byUrn: ReadonlyMap<string, Task>;
+  identities: ReadonlyMap<string, SearchItem>;
+  projects: ReadonlyMap<string, SearchItem>;
+  /** The workflows named in the options, by URN, in the order named. */
+  workflows: ReadonlyMap<string, Workflow>;
+  /** URNs of tasks with a write in flight. */
+  saving: ReadonlySet<string>;
+  /** Activity logs of the tasks whose logs were loaded. */
+  logs: ReadonlyMap<string, TaskLogState>;
+  /**
+   * Fields someone else changed while this person was editing, found when one of their changes was saved, by task
+   * URN. Kept until `dismissChangedElsewhere`.
+   */
+  changedElsewhere: ReadonlyMap<string, readonly (TaskField | TaskListField)[]>;
+}
+
+type Patch = { id: number; changes: TaskInput } | { id: number; deleted: true };
+
+const EMPTY: TaskStoreState = {
+  status: 'idle',
+  tasks: [],
+  byUrn: new Map(),
+  identities: new Map(),
+  projects: new Map(),
+  workflows: new Map(),
+  saving: new Set(),
+  logs: new Map(),
+  changedElsewhere: new Map(),
+};
+
+/**
+ * Holds a company's tasks for a UI: loads them, applies changes straight away and rolls them back if the server
+ * refuses, and notifies subscribers. `subscribe` and `getState` fit React's `useSyncExternalStore`.
+ *
+ * ```ts
+ * const store = new TaskStore(tasks, { owner: companyUrn, actor: me });
+ * store.subscribe(() => render(selectTasks(store.getState(), { assignee: [me], open: true }, byUrgency)));
+ * await store.load();
+ * await store.setStatus(urn, 'COMPLETED');
+ * ```
+ */
+export class TaskStore {
+  #state: TaskStoreState = EMPTY;
+  readonly #listeners = new Set<() => void>();
+  /** Tasks as the server last returned them. */
+  readonly #confirmed = new Map<string, Task>();
+  #order: string[] = [];
+  readonly #pending = new Map<string, Patch[]>();
+  #nextPatch = 0;
+  readonly #timers = new Set<ReturnType<typeof setTimeout>>();
+  #loading: AbortController | undefined;
+
+  constructor(
+    readonly client: TaskClient,
+    readonly options: TaskStoreOptions,
+  ) {}
+
+  getState = (): TaskStoreState => this.#state;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  };
+
+  /** The task as the reader should see it. */
+  get(task: RefLike): Task | undefined {
+    return this.#state.byUrn.get(urnOf(task));
+  }
+
+  /** Stops pending work and drops subscribers. */
+  dispose(): void {
+    this.#loading?.abort();
+    this.#timers.forEach(clearTimeout);
+    this.#timers.clear();
+    this.#listeners.clear();
+  }
+
+  // ==========================================
+  // LOADING
+  // ==========================================
+
+  /** Loads (or reloads) every task. A load already running is cancelled. Pending changes stay applied. */
+  async load(): Promise<void> {
+    this.#loading?.abort();
+    const controller = new AbortController();
+    this.#loading = controller;
+    this.#publish({ status: 'loading' });
+    try {
+      const [listing, workflows] = await Promise.all([
+        this.client.list({
+          owner: this.options.owner,
+          includeRelated: this.options.includeRelated ?? true,
+          signal: controller.signal,
+        }),
+        Promise.all((this.options.workflows ?? []).map((workflow) => this.client.getWorkflow(workflow).catch(() => undefined))),
+      ]);
+      if (controller.signal.aborted) return;
+      this.#confirmed.clear();
+      for (const task of listing.tasks) this.#confirmed.set(task.urn, task);
+      this.#order = listing.tasks.map((task) => task.urn);
+      this.#publish({
+        status: 'ready',
+        error: undefined,
+        identities: new Map(listing.identities.map((item) => [item.urn, item])),
+        projects: new Map(listing.projects.map((item) => [item.urn, item])),
+        workflows: new Map(workflows.filter((w) => w !== undefined).map((workflow) => [workflow.urn, workflow])),
+      });
+    } catch (error) {
+      if (controller.signal.aborted) return;
+      this.#publish({ status: 'error', error });
+      throw error;
+    } finally {
+      if (this.#loading === controller) this.#loading = undefined;
+    }
+  }
+
+  /** Reads one task again. Removes it when it no longer exists. */
+  async reload(task: RefLike): Promise<Task | undefined> {
+    const urn = urnOf(task);
+    try {
+      const fresh = await this.client.get(urn);
+      this.#confirm(fresh);
+      this.#publish();
+      return fresh;
+    } catch (error) {
+      if (isBaackApiError(error) && error.isNotFound) {
+        this.#forget(urn);
+        this.#publish();
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  // ==========================================
+  // CHANGES
+  // ==========================================
+
+  async create(input: TaskDraft | Omit<DraftInput, 'owner'>, options: ChangeOptions = {}): Promise<Task> {
+    const created = await this.client.create({ owner: this.options.owner, ...input }, this.#changeOptions(options));
+    this.#confirm(created, true);
+    this.#publish();
+    this.#settle([created.urn]);
+    return created;
+  }
+
+  /**
+   * Shows `changes` at once and sends them. On success the server's task replaces the shown one; on failure the
+   * change is rolled back and the error rethrown.
+   *
+   * The change is checked against the task as shown when it was made. If someone else changed one of the same fields
+   * since, it throws `TaskConflictError`, saves nothing and shows the task as it is now; resolve the conflict with
+   * `resolveConflicts` and update again. Other fields they changed are kept and listed in `changedElsewhere`.
+   */
+  async update(task: RefLike, changes: TaskInput, options: ChangeOptions = {}): Promise<Task> {
+    const urn = urnOf(task);
+    const before = this.get(urn);
+    const id = this.#addPatch(urn, { changes });
+    try {
+      const result = (await this.client.update(before ?? urn, changes, {
+        ...this.#changeOptions(options),
+        base: before,
+        onChangedElsewhere: (fields) => this.#noteChangedElsewhere(urn, fields),
+      })) as Task | undefined;
+      const saved = result ?? (await this.client.get(urn));
+      this.#confirm(saved);
+      this.#removePatch(urn, id);
+      this.#settle([urn, ...changedBlockers(before, changes)]);
+      return saved;
+    } catch (error) {
+      if (error instanceof TaskConflictError) this.#confirm(error.current);
+      this.#removePatch(urn, id);
+      throw error;
+    }
+  }
+
+  /** Clears the note of fields someone else changed on the task. */
+  dismissChangedElsewhere(task: RefLike): void {
+    const urn = urnOf(task);
+    if (!this.#state.changedElsewhere.has(urn)) return;
+    const changedElsewhere = new Map(this.#state.changedElsewhere);
+    changedElsewhere.delete(urn);
+    this.#publish({ changedElsewhere });
+  }
+
+  async delete(task: RefLike): Promise<void> {
+    const urn = urnOf(task);
+    const id = this.#addPatch(urn, { deleted: true });
+    try {
+      await this.client.delete(urn);
+      const blockers = changedBlockers(this.#confirmed.get(urn), { blockedBy: [], blocking: [] });
+      this.#forget(urn);
+      this.#removePatch(urn, id);
+      this.#settle(blockers);
+    } catch (error) {
+      this.#removePatch(urn, id);
+      throw error;
+    }
+  }
+
+  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);
+  }
+
+  assign(task: RefLike, assignee: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { assignee: assignee === null ? null : ref(assignee) }, options);
+  }
+
+  setDue(task: RefLike, dueTimestamp: string | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { dueTimestamp }, options);
+  }
+
+  setProject(task: RefLike, project: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { project: project === null ? null : ref(project) }, options);
+  }
+
+  setWorkflowStage(task: RefLike, stage: RefLike | null, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { workflowStage: stage === null ? null : ref(stage) }, options);
+  }
+
+  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, building on pending changes. */
+  addTo(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { [field]: withRef(this.#require(task)[field], value) }, options);
+  }
+
+  /** Removes a reference from one of the task's lists, building on pending changes. */
+  removeFrom(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task> {
+    return this.update(task, { [field]: withoutRef(this.#require(task)[field], value) }, options);
+  }
+
+  // ==========================================
+  // ACTIVITY LOG
+  // ==========================================
+
+  /** Loads the newest page of the task's log, replacing what was loaded. */
+  async loadLogs(task: RefLike): Promise<void> {
+    const urn = urnOf(task);
+    this.#setLogs(urn, { ...this.#logState(urn), status: 'loading' });
+    try {
+      const page = await this.client.logs(urn);
+      this.#setLogs(urn, { status: 'ready', logs: page.logs, ...afterOf(page.pagination) });
+    } catch (error) {
+      this.#setLogs(urn, { ...this.#logState(urn), status: 'error', error });
+      throw error;
+    }
+  }
+
+  /** Loads the next older page of the task's log, if there is one. */
+  async loadMoreLogs(task: RefLike): Promise<void> {
+    const urn = urnOf(task);
+    const current = this.#logState(urn);
+    if (current.after === undefined) return;
+    this.#setLogs(urn, { ...current, status: 'loading' });
+    try {
+      const page = await this.client.logs(urn, { after: current.after });
+      this.#setLogs(urn, {
+        status: 'ready',
+        logs: mergeLogs(current.logs, page.logs),
+        ...afterOf(page.pagination),
+      });
+    } catch (error) {
+      this.#setLogs(urn, { ...current, status: 'error', error });
+      throw error;
+    }
+  }
+
+  /** Adds a comment and shows it at the top of the task's log. */
+  async comment(task: RefLike, text: string, options: { actor?: RefLike; replyTo?: RefLike } = {}): Promise<TaskLog> {
+    const urn = urnOf(task);
+    const actor = options.actor ?? this.options.actor;
+    const log = await this.client.comment(urn, text, {
+      ...(actor === undefined ? {} : { actor }),
+      ...(options.replyTo === undefined ? {} : { replyTo: options.replyTo }),
+    });
+    const current = this.#state.logs.get(urn);
+    if (current) this.#setLogs(urn, { ...current, logs: mergeLogs([log], current.logs) });
+    this.#settle([urn]);
+    return log;
+  }
+
+  // ==========================================
+  // INTERNALS
+  // ==========================================
+
+  #changeOptions(options: ChangeOptions): ChangeOptions {
+    const actor = options.actor ?? this.options.actor;
+    return actor === undefined ? {} : { actor };
+  }
+
+  #require(task: RefLike): Task {
+    const found = this.get(task);
+    if (!found) throw new Error(`Task ${urnOf(task)} is not in the store`);
+    return found;
+  }
+
+  #confirm(task: Task, first = false): void {
+    this.#confirmed.set(task.urn, task);
+    if (!this.#order.includes(task.urn)) this.#order = first ? [task.urn, ...this.#order] : [...this.#order, task.urn];
+  }
+
+  #forget(urn: string): void {
+    this.#confirmed.delete(urn);
+    this.#order = this.#order.filter((candidate) => candidate !== urn);
+    if (this.#state.logs.has(urn)) {
+      const logs = new Map(this.#state.logs);
+      logs.delete(urn);
+      this.#state = { ...this.#state, logs };
+    }
+  }
+
+  #addPatch(urn: string, patch: Omit<Patch, 'id'>): number {
+    const id = this.#nextPatch++;
+    this.#pending.set(urn, [...(this.#pending.get(urn) ?? []), { id, ...patch } as Patch]);
+    this.#publish();
+    return id;
+  }
+
+  #removePatch(urn: string, id: number): void {
+    const remaining = (this.#pending.get(urn) ?? []).filter((patch) => patch.id !== id);
+    if (remaining.length > 0) this.#pending.set(urn, remaining);
+    else this.#pending.delete(urn);
+    this.#publish();
+  }
+
+  #noteChangedElsewhere(urn: string, fields: readonly (TaskField | TaskListField)[]): void {
+    const noted = new Set([...(this.#state.changedElsewhere.get(urn) ?? []), ...fields]);
+    this.#state = { ...this.#state, changedElsewhere: new Map(this.#state.changedElsewhere).set(urn, [...noted]) };
+  }
+
+  #logState(urn: string): TaskLogState {
+    return this.#state.logs.get(urn) ?? { status: 'idle', logs: [] };
+  }
+
+  #setLogs(urn: string, state: TaskLogState): void {
+    this.#publish({ logs: new Map(this.#state.logs).set(urn, state) });
+  }
+
+  /** Reads the given tasks (and their loaded logs) again once the server has had time to settle. */
+  #settle(urns: readonly string[]): void {
+    const settleMs = this.options.settleMs ?? 500;
+    if (settleMs <= 0) return;
+    const timer = setTimeout(() => {
+      this.#timers.delete(timer);
+      for (const urn of new Set(urns)) {
+        if (!this.#confirmed.has(urn)) continue;
+        this.reload(urn).catch(() => undefined);
+        if (this.#state.logs.get(urn)?.status === 'ready') this.#refreshLogs(urn).catch(() => undefined);
+      }
+    }, settleMs);
+    this.#timers.add(timer);
+  }
+
+  /** Reads the newest page of a log and merges it in, keeping older pages already loaded. */
+  async #refreshLogs(urn: string): Promise<void> {
+    const page = await this.client.logs(urn);
+    const current = this.#logState(urn);
+    this.#setLogs(urn, { ...current, logs: mergeLogs(page.logs, current.logs) });
+  }
+
+  #publish(changes: Partial<TaskStoreState> = {}): void {
+    const tasks: Task[] = [];
+    const byUrn = new Map<string, Task>();
+    const saving = new Set<string>();
+    for (const urn of this.#order) {
+      let task = this.#confirmed.get(urn);
+      const patches = this.#pending.get(urn) ?? [];
+      if (patches.length > 0) saving.add(urn);
+      for (const patch of patches) {
+        if (!task) break;
+        task = 'deleted' in patch ? undefined : this.#withNames(applyChanges(task, patch.changes));
+      }
+      if (task) {
+        tasks.push(task);
+        byUrn.set(urn, task);
+      }
+    }
+    for (const urn of this.#pending.keys()) saving.add(urn);
+    this.#state = { ...this.#state, ...changes, tasks, byUrn, saving };
+    this.#listeners.forEach((listener) => listener());
+  }
+
+  /** Fills in names for an assignee or project set by URN, from the identities and projects loaded. */
+  #withNames(task: Task): Task {
+    const result = { ...task };
+    const assignee = task.assignee && this.#state.identities.get(task.assignee.urn);
+    if (task.assignee && assignee && task.assignee.name == null) {
+      result.assignee = { ...task.assignee, name: assignee.name ?? null };
+    }
+    const project = task.project && this.#state.projects.get(task.project.urn);
+    if (task.project && project && task.project.name == null) {
+      result.project = { ...task.project, name: project.name ?? '' };
+    }
+    return result;
+  }
+}
+
+// ==========================================
+// SELECTORS
+// ==========================================
+
+/** Tasks matching `filter`, sorted when a comparator is given. */
+export function selectTasks(state: TaskStoreState, filter: TaskFilter = {}, sort?: TaskComparator): Task[] {
+  const tasks = filterTasks(state.tasks, filter);
+  return sort ? tasks.sort(sort) : tasks;
+}
+
+/** Tasks matching `filter`, grouped for a board, each group sorted when a comparator is given. */
+export function selectGroups(
+  state: TaskStoreState,
+  by: TaskGrouping,
+  filter: TaskFilter = {},
+  sort?: TaskComparator,
+): Map<string, Task[]> {
+  const groups = groupTasks(filterTasks(state.tasks, filter), by);
+  if (sort) groups.forEach((group) => group.sort(sort));
+  return groups;
+}
+
+/** The display name of an identity, project, task or workflow stage, falling back to the end of its URN. */
+export function selectName(state: TaskStoreState, item: RefLike): string {
+  const urn = urnOf(item);
+  return (
+    state.identities.get(urn)?.name ??
+    state.projects.get(urn)?.name ??
+    state.byUrn.get(urn)?.title ??
+    stageName(state.workflows.values(), urn) ??
+    (typeof item === 'object' && 'name' in item && typeof item.name === 'string' ? item.name : undefined) ??
+    urn.slice(-6)
+  );
+}
+
+/** The name of a stage in one of `workflows`. */
+function stageName(workflows: Iterable<Workflow>, urn: string): string | undefined {
+  for (const workflow of workflows) {
+    const stage = workflow.stages?.find((s) => s.urn === urn);
+    if (stage) return stage.name;
+  }
+  return undefined;
+}
+
+/** The URNs of the open tasks blocking `task`, by the store's tasks. */
+export function selectOpenBlockers(state: TaskStoreState, task: Task): string[] {
+  return openBlockersOf(task, (urn) => state.byUrn.get(urn));
+}
+
+function changedBlockers(before: Task | undefined, changes: TaskInput): string[] {
+  const urns: string[] = [];
+  for (const field of ['blockedBy', 'blocking'] as const) {
+    const after = changes[field];
+    if (after === undefined) continue;
+    const old = new Set((before?.[field] ?? []).map(urnOf));
+    const next = new Set(after.map(urnOf));
+    for (const urn of old) if (!next.has(urn)) urns.push(urn);
+    for (const urn of next) if (!old.has(urn)) urns.push(urn);
+  }
+  return urns;
+}
+
+function mergeLogs(newer: readonly TaskLog[], older: readonly TaskLog[]): TaskLog[] {
+  const seen = new Set(newer.map((log) => log.urn));
+  return [...newer, ...older.filter((log) => !seen.has(log.urn))];
+}
+
+function afterOf(pagination: { isMorePages?: boolean; after?: string | null } | null | undefined): { after?: string } {
+  return pagination?.isMorePages && pagination.after ? { after: pagination.after } : {};
+}