Relations

relations links two records of any subject type: a task that blocks another, an issue under an epic, a person who reports to a manager. Each kind of link is declared once, with its inverse name, whether it may form a cycle, and whether a record can have more than one target. Links carry a small data object, such as a Gantt dependency's type and lag.

better-supabase sql add relations

import {
  createRelations,
  toGanttTasks,
  toTreeItems,
} from "better-supabase/blocks/relations";

KindsCopy Anchor Link

Without kinds, the module declares three:

sql: {
  modules: {
    relations: {
      options: {
        kinds: {
          blocks: { inverse: "blocked_by", acyclic: true },
          parent: { inverse: "children", cardinality: "one", acyclic: true },
          relates: { symmetric: true },
        },
      },
    },
  },
},

A link reads "source kind target": link("parent", issue, epic) makes the epic the issue's parent, and link("blocks", design, build) means design blocks build. The cycle check runs a recursive query under an advisory lock per organization and kind, so two concurrent links can't close a cycle between them.

The subjects come from config.subjects, or from options.subjects with the same shape. Both ends must exist in the organization and be readable by the caller, and linking needs relations.manage. A subject with cascade: true deletes its links when its row is deleted.

Link and unlinkCopy Anchor Link

const relations = createRelations({ transport });

const result = await relations
  .link({
    organizationId,
    kind: "blocks",
    source: { type: "task", id: designId },
    target: { type: "task", id: buildId },
    data: { type: "FS", lag: 2 },
  })
  .orThrow();

await relations.unlink({
  organizationId,
  kind: "blocked_by",
  source: { type: "task", id: buildId },
  target: { type: "task", id: designId },
});

link resolves to the stored link, created: false when it already existed (its data is updated when you pass data), and replaced with the old target when a one-target kind moved. Both methods return an undo token that reverses the change, including putting a replaced parent back. See Undo tokens.

Read linksCopy Anchor Link

Reads run as the caller and need relations.read, which the default member role has. rollup also reads the subject table as the caller, so its policies decide which rows count:

const points = await relations
  .rollup({
    organizationId,
    kind: "parent",
    subject: { type: "issue", id: epicId },
    of: "issue",
    agg: "sum",
    column: "estimate",
  })
  .orThrow();

The SQL functions are link, unlink, relations_of, relations_by_kind, ancestors, descendants and relation_rollup. Walks stop at 100 levels.

EventsCopy Anchor Link

link and unlink record subject.linked and subject.unlinked with the kind and both ends, and call the before_relation_link and after_relation_link hooks.

Adopt modeCopy Anchor Link

Adopt mode maps the relations table onto an existing one with the same columns. Tables that hold one kind each, such as a sub-issue table or a reporting-line table, are not adopt targets yet.

With ReUICopy Anchor Link

• Gantt: toGanttTasks(tasks, await relations.edges(org, "blocks")) adds each task's dependencies with the type and lag from the link's data.
• Tree: toTreeItems(items, await relations.edges(org, "parent")) returns the flat { [id]: { name, children } } map a tree view takes, for sub-issues or a reporting line.
• Data Grid: a "Blocked by" column from of(org, task, "blocked_by"), and an undo toast from the undo token.

The free c-gantt-* and c-tree-* examples show both views. ReUI's Tempo and Roster templates show sub-issues and reporting trees; Pro blocks are licensed per user, so copy them from reui.io.