Work items

tasks is the task and issue record of Linear, Jira, GitHub issues and monday items: a title, a body, a parent, assignees, a priority, an estimate, start, end and due dates, and a stage on a pipeline. Items can belong to a team, a project and an iteration (a cycle or a sprint). Their identifier is TASK-12, or the format of a work_item entity in numbering.

Reading needs work_items.read, creating, editing and assigning needs work_items.write, and projects, iterations and deleting someone else's item need work_items.manage. Admins get every permission, and members get work_items.read and work_items.write.

better-supabase add tasks

The module needs tenant, access, subjects and pipelines. Installing it binds the work_item type in the pipelines module with one pipeline per team (scope: "team_id") and the categories of Linear's workflow states:

A stage's category sets the item's state, so a list or a policy reads state and never a stage name. Set blocks.pipelines.options.subjects.work_item to rename the stages or start with your own, such as CentraKit's Todo, In progress, On hold and Done; your keys are merged over the defaults.

Installing the block registers work items as the work_item subject, ranked by stage. Set the page a search result links to on the entity:

export default defineConfig({
  blocks: { tasks: { names: { work_item: { url: "/tasks/{id}" } } } },
});

Create, edit and assignCopy Anchor Link

import { createTasks } from "better-supabase/blocks/tasks";

const items = createTasks({ transport });
const epic = await items
  .create(organizationId, { title: "Checkout v2", teamId, priority: 2 })
  .orThrow();
const task = await items
  .create(
    organizationId,
    { title: "Payment API", parentId: epic.id, teamId, dueAt },
    [userId],
  )
  .orThrow();

const { accepted, rejected } = await items
  .update([
    { workItemId: task.id, field: "stageId", value: inProgressStageId },
    { workItemId: task.id, field: "endAt", value: friday },
  ])
  .orThrow();

update(changes) applies grid edits and Gantt drags one by one and returns the refused ones with their hint. The table refuses a parent that would put an item under itself (WORK_ITEM_PARENT_CYCLE) and date changes on a locked item (WORK_ITEM_LOCKED). Moving to a completed or canceled stage stamps closedAt and a close reason (completed, or not_planned for canceled; pass closeReason: "duplicate" with the move to mark a duplicate) and records work_item.closed. Moving back to an open stage clears both and records work_item.reopened.

assign(id, userIds) replaces the assignees. Each one watches the item, and the people newly assigned get a work_item.assigned notification. options.maxAssignees caps the list (WORK_ITEM_ASSIGNEES_LIMIT), and 1 gives the single-assignee shape of Linear and Jira.

Lists, trees, projects and iterationsCopy Anchor Link

list(organizationId, { teamId, projectId, iterationId, parentId, assigneeId, states, open, search }) returns active items, newest first, 50 per page; pass the last item's id as after for the next page. tree(rootId) returns an item and everything under it with its depth; an item without its own progress rolls up the share of its open and completed children that are completed, for a Gantt group.

Dependencies between items are relations: link(design, build, { kind: "blocks" }) is a finish-to-start dependency, and edges("blocks") reads them for the chart.

saveProject(organizationId, { key, name, status, startOn, targetOn }) keeps a project (PAY) with the share of its items that are completed. saveIteration(organizationId, { name, teamId, startsOn, endsOn }) keeps a cycle or a sprint. Turn either table off with tables: { projects: null } or tables: { iterations: null }.

Checklists, files, repeat rules and watchersCopy Anchor Link

const draft = await items
  .saveChecklistItem(task.id, { title: "Draft the copy" })
  .orThrow();
await items.saveChecklistItem(task.id, { done: true }, draft.id).orThrow();
const steps = await items.checklist(task.id).orThrow();

saveChecklistItem(workItemId, input, checklistItemId?) adds a step at the end, or edits the one you name: its title, done (which stamps doneAt and doneBy) or rank. removeChecklistItem(id) deletes one, and checklist(workItemId) lists them in rank order. Every item a read returns carries checklist: { total, done }, and get(id) reads one item. A checklist change records work_item.updated with fields: ["checklist"].

On the work item's own page, the block's checklist section (workItemChecklistSection) loads the steps for the item as the subject ({ type: "work_item", id }, or the renamed type) and reads again on work_item.updated. workItemChecklistOptimistic is its useOptimistic reducer: { type: "save", item } adds or replaces a step in rank order and { type: "remove", id } drops one.

With the attachments block installed, create takes attachmentIds and update takes an attachments change with a list of ids. Upload the files first without a subject, then link them: the block links only files the caller uploaded that have no subject yet (WORK_ITEM_ATTACHMENTS_INVALID). A bucket whose path template uses {subject_type} or {subject_id} can't move a file after upload, so link through attachments.upload with the item as the subject instead (WORK_ITEM_ATTACHMENTS_PATH).

With the reminders block installed, setRecurrence(id, { rrule, tzid }) gives an item a repeat rule, such as FREQ=MONTHLY;BYMONTHDAY=1, and setRecurrence(id, null) removes it. Items carry the rule as recurrence. A repeating item makes its next copy when it is completed, like Asana and Todoist: relay the block's events to workItemRecurrenceSink, built on a service transport.

import {
  createTasks,
  workItemRecurrenceSink,
} from "better-supabase/blocks/tasks";

const serviceItems = createTasks({ transport: serviceTransport });

outbox.relay("tasks", workItemRecurrenceSink(serviceItems));

The sink calls repeat(id, dueAt) with the rule's first occurrence after the completed item's due date. repeat copies the title, body, parent, team, project, priority, estimate, assignees, extra columns and an unchecked checklist, shifts the start and end dates by the same amount, and moves the rule to the copy, so a COUNT keeps counting. The copy's recursFromId names the item it repeats, and a second repeat of the same item returns the same copy, so a redelivered event changes nothing. After entities: { work_item: "task" }, pass { type: "task.closed" }.

With the notifications block installed, watch(id, "all") follows an item, watch(id, "ignore") mutes it, watch(id, null) goes back to the default, and watchers(id) lists who follows it. Assignees already watch their items.

Extra columnsCopy Anchor Link

options.extraColumns adds columns to work_items, such as CentraKit's customer_id. Every item a read returns carries them in fields.

EventsCopy Anchor Link

HooksCopy Anchor Link

The module calls before_work_item_create(tenant, attrs jsonb), after_work_item_create(work_item uuid), before_work_item_update(work_item uuid, field text, value jsonb) and after_work_item_update(work_item uuid, field text). A before_ hook raises to refuse; in update, that refuses only its change.

Wire it to ReUICopy Anchor Link

The ReUI Kanban blocks commit a drag through onValueCommit: call rank.move("work_item", id, { previous, next, group: stageId }). The Gantt blocks commit a move or resize through onEventUpdate: send startAt and endAt through update, and return false when the change comes back in rejected (a locked bar). Read the Gantt rows from tree, and its arrows from the blocks relations.

ErrorsCopy Anchor Link

Your own columnsCopy Anchor Link

Add columns to the work item table with blocks.tasks.options.extraColumns (column name to SQL type), then pass a Standard Schema for them as fields. create, and update with the column name as field validates and writes them, and every method that returns an item return them parsed under fields. The block also takes hooks around its methods; see extending blocks.

import { createTasks } from "better-supabase/blocks/tasks";
import { z } from "zod";

const client = createTasks({
  transport,
  fields: z.object({ priority: z.enum(["low", "high"]) }),
});