@zinn-dev/core 0.5.0 → 0.6.0

package/index.ts

@@ -1,6 +1,7 @@
 import type { Column } from "./src/types";
 import type { ProjectCreateInput, ProjectEditInput } from "./src/schemas/project";
 import type { TaskCreateInput, TaskEditInput } from "./src/schemas/task";
+import type { RelationCreateInput } from "./src/schemas/relation";
 
 import { randomUUIDv7 } from "bun";
 import { generateKeyBetween } from "fractional-indexing";
@@ -8,8 +9,10 @@ import { generateKeyBetween } from "fractional-indexing";
 import * as dbProject from "./src/db/project";
 import * as dbColumn from "./src/db/column";
 import * as dbTask from "./src/db/task";
+import * as dbRelation from "./src/db/relation";
 import { standardizeProjectKey } from "./src/lib";
 import { validateTaskInput, taskCreateSchema, taskEditSchema } from "./src/schemas/task";
+import { relationCreateSchema } from "./src/schemas/relation";
 
 import {
   validateProjectInput,
@@ -19,9 +22,11 @@ import {
 
 export type { ProjectCreateInput, ProjectEditInput } from "./src/schemas/project";
 export type { TaskCreateInput, TaskEditInput } from "./src/schemas/task";
+export type { RelationCreateInput } from "./src/schemas/relation";
 
 export { projectCreateSchema, projectEditSchema } from "./src/schemas/project";
 export { taskCreateSchema, taskEditSchema } from "./src/schemas/task";
+export { relationCreateSchema } from "./src/schemas/relation";
 
 export const project = {
   getById: dbProject.getById,
@@ -376,3 +381,54 @@ export const task = {
     })!;
   },
 };
+
+export const relation = {
+  create: (input: RelationCreateInput) => {
+    const props = validateTaskInput(relationCreateSchema, input);
+    const sourceTask = getTaskByKey(props.sourceTaskKey);
+    const targetTask = getTaskByKey(props.targetTaskKey);
+
+    if (sourceTask.id === targetTask.id) {
+      throw new Error("A task cannot have a relation to itself. Not appropriate.");
+    }
+
+    let sourceId = sourceTask.id;
+    let targetId = targetTask.id;
+
+    /**
+     * To avoid headaches with relations that
+     *  technically have no semantic source/target
+     *  it felt reasonable to invent reliable "source" and "target"
+     *  by enforcing the placements through ID comparison
+     */
+    const isSymmetricRelation = props.relation_type === "related";
+    if (isSymmetricRelation && sourceId > targetId) {
+      sourceId = targetTask.id;
+      targetId = sourceTask.id;
+    }
+
+    const relationMatch = dbRelation.getByTaskIdsAndType({
+      source_task_id: sourceId,
+      target_task_id: targetId,
+      relation_type: props.relation_type,
+    });
+
+    if (relationMatch != null) {
+      throw new Error("This relation already exists");
+    }
+
+    return dbRelation.create({
+      source_task_id: sourceId,
+      target_task_id: targetId,
+      relation_type: props.relation_type,
+    });
+  },
+  getAll: (taskKey: string) => {
+    if (taskKey == null) {
+      throw new Error("Provide a task key to list relations");
+    }
+    const taskMatch = getTaskByKey(taskKey);
+
+    return dbRelation.getAllByTaskId(taskMatch.id);
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zinn-dev/core",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shared logic for zinn, a kanban workflow in the terminal.",
   "license": "MIT",
   "bugs": {

package/src/constant.ts

@@ -14,6 +14,7 @@ export const DB_TABLE = {
   project: "project",
   projectColumn: "project_column",
   task: "task",
+  task_relations: "task_relations",
 };
 
 // TODO: implement zod schema for setting.json

package/src/db/relation.test.ts

@@ -0,0 +1,103 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+function runRelationCheck(script: string) {
+  const testDir = mkdtempSync(join(tmpdir(), "zinn-relations-"));
+  try {
+    // Separate process keeps the DB singleton and environment isolated from other tests.
+    const result = Bun.spawnSync([process.execPath, "--eval", `
+      import { strict as assert } from "node:assert";
+      import { project, task, relation } from ${JSON.stringify(new URL("../../index.ts", import.meta.url).pathname)};
+      import { getDb } from ${JSON.stringify(new URL("../db.ts", import.meta.url).pathname)};
+      ${script}
+    `], { env: { ...process.env, ZINN_DIR: testDir } });
+    expect(result.stderr.toString()).toBe("");
+    expect(result.exitCode).toBe(0);
+  } finally {
+    rmSync(testDir, { recursive: true, force: true });
+  }
+}
+
+for (const inputOrder of ["smaller first", "larger first"]) {
+  test(`related stores the smaller task ID as source with ${inputOrder}`, () => {
+    runRelationCheck(`
+      const app = project.create({ key: "APP" });
+      const tasks = [1, 2].map(() => task.create({
+        project_id: app.id, title: "Task", description: null,
+      })).sort((a, b) => a.id < b.id ? -1 : 1);
+      const [smaller, larger] = tasks;
+      const source = ${JSON.stringify(inputOrder)} === "smaller first" ? smaller : larger;
+      const target = source === smaller ? larger : smaller;
+      const create = (source, target) => relation.create({
+        sourceTaskKey: "APP-" + source.number,
+        targetTaskKey: "APP-" + target.number,
+        relation_type: "related",
+      });
+      const related = create(source, target);
+      assert.equal(related.source_task_id, smaller.id);
+      assert.equal(related.target_task_id, larger.id);
+      assert.throws(() => create(source, target), /already exists/);
+      assert.throws(() => create(target, source), /already exists/);
+      assert.equal(relation.getAll("APP-1").length, 1);
+      assert.equal(relation.getAll("APP-2")[0].id, related.id);
+    `);
+  });
+}
+
+test("dependency preserves the dependent task as source regardless of task ID order", () => {
+  runRelationCheck(`
+    const app = project.create({ key: "APP" });
+    const tasks = [1, 2].map(() => task.create({
+      project_id: app.id, title: "Task", description: null,
+    })).sort((a, b) => a.id < b.id ? -1 : 1);
+    for (const [dependent, prerequisite] of [tasks, [...tasks].reverse()]) {
+      const dependency = relation.create({
+        sourceTaskKey: "APP-" + dependent.number,
+        targetTaskKey: "APP-" + prerequisite.number,
+        relation_type: "dependency",
+      });
+      assert.equal(dependency.source_task_id, dependent.id);
+      assert.equal(dependency.target_task_id, prerequisite.id);
+    }
+    // A symmetric connection between the same tasks is a separate relation.
+    relation.create({ sourceTaskKey: "APP-1", targetTaskKey: "APP-2", relation_type: "related" });
+    assert.equal(relation.getAll("APP-1").length, 3);
+  `);
+});
+
+test("relations clean up without deleting connected tasks", () => {
+  runRelationCheck(`
+      const a = project.create({ key: "APP" });
+      const b = project.create({ key: "OTHER" });
+      for (let i = 0; i < 4; i++) {
+        task.create({ project_id: a.id, title: "Task", description: null });
+      }
+      task.create({ project_id: b.id, title: "Survivor", description: null });
+      const create = (sourceTaskKey, targetTaskKey, relation_type) =>
+        relation.create({ sourceTaskKey, targetTaskKey, relation_type });
+      const related = create("APP-2", "APP-1", "related");
+      assert.ok(related.id);
+      assert.ok(related.created_at > 0);
+      assert.ok(related.source_task_id < related.target_task_id);
+      assert.throws(() => create("APP-1", "APP-2", "related"), /already exists/);
+      assert.throws(() => create("APP-1", "APP-1", "related"), /itself/);
+      assert.equal(relation.getAll("APP-1")[0].id, related.id);
+      assert.equal(relation.getAll("APP-2")[0].id, related.id);
+      const dependency = create("APP-4", "APP-3", "dependency");
+      assert.equal(dependency.source_task_id, task.getByKey("APP-4").id);
+      assert.equal(dependency.target_task_id, task.getByKey("APP-3").id);
+      const preserved = create("APP-3", "OTHER-1", "related");
+      task.delete("APP-4");
+      assert.deepEqual(relation.getAll("APP-3").map(r => r.id), [preserved.id]);
+      create("APP-3", "APP-2", "dependency");
+      task.delete("APP-2");
+      assert.deepEqual(relation.getAll("APP-1"), []);
+      assert.deepEqual(relation.getAll("APP-3").map(r => r.id), [preserved.id]);
+      project.delete("APP");
+      assert.ok(task.getByKey("OTHER-1"));
+      assert.deepEqual(relation.getAll("OTHER-1"), []);
+      assert.deepEqual(getDb().query("PRAGMA foreign_key_check").all(), []);
+  `);
+});

package/src/db/relation.ts

@@ -0,0 +1,58 @@
+import type { Bind, TaskRelation } from "../types";
+
+import { randomUUIDv7 } from "bun";
+
+import { DB_TABLE } from "../constant";
+import { getDb } from "../db";
+
+export function getAll() {
+  const db = getDb();
+  return db.query<TaskRelation, any>(`SELECT * FROM ${DB_TABLE.task_relations}`).all();
+}
+
+export function getAllByTaskId(taskId: string) {
+  const db = getDb();
+
+  return db
+    .query<TaskRelation, Bind<{ taskId: string }>>(`SELECT * FROM ${DB_TABLE.task_relations}
+    WHERE source_task_id = $taskId OR target_task_id = $taskId`)
+    .all({ $taskId: taskId });
+}
+
+export function getByTaskIdsAndType(
+  props: Pick<TaskRelation, "source_task_id" | "target_task_id" | "relation_type">,
+) {
+  const db = getDb();
+
+  return db
+    .query<TaskRelation, Bind<typeof props>>(`SELECT * FROM ${DB_TABLE.task_relations}
+    WHERE source_task_id = $source_task_id
+      AND target_task_id = $target_task_id
+      AND relation_type = $relation_type`)
+    .get({
+      $source_task_id: props.source_task_id,
+      $target_task_id: props.target_task_id,
+      $relation_type: props.relation_type,
+    });
+}
+
+type CreateTaskRelationInput = Pick<
+  TaskRelation,
+  "id" | "source_task_id" | "target_task_id" | "relation_type" | "created_at"
+>;
+export function create(props: Omit<CreateTaskRelationInput, "id" | "created_at">) {
+  const db = getDb();
+
+  const query = db.query<TaskRelation, Bind<CreateTaskRelationInput>>(`INSERT INTO
+    ${DB_TABLE.task_relations} (id, source_task_id, target_task_id, relation_type, created_at)
+    VALUES              ($id, $source_task_id, $target_task_id, $relation_type, $created_at)
+    RETURNING *;`);
+
+  return query.get({
+    $id: randomUUIDv7(),
+    $source_task_id: props.source_task_id,
+    $target_task_id: props.target_task_id,
+    $relation_type: props.relation_type,
+    $created_at: Date.now(),
+  });
+}

package/src/db.ts

@@ -42,6 +42,19 @@ function initDb() {
   updated_at  INTEGER NOT NULL,
   archived_at INTEGER);`).run();
 
+  // --- TASK RELATIONS TABLE
+  db.query(`CREATE TABLE IF NOT EXISTS ${DB_TABLE.task_relations} (
+  id              TEXT PRIMARY KEY,
+  source_task_id  TEXT NOT NULL REFERENCES ${DB_TABLE.task}(id) ON DELETE CASCADE,
+  target_task_id  TEXT NOT NULL REFERENCES ${DB_TABLE.task}(id) ON DELETE CASCADE,
+  relation_type   TEXT NOT NULL CHECK (
+    relation_type IN ('related', 'dependency', 'duplicate')
+  ),
+  created_at      INTEGER NOT NULL,
+
+  UNIQUE (source_task_id, target_task_id, relation_type),
+  CHECK (source_task_id <> target_task_id));`).run();
+
   return db;
 }
 

package/src/schemas/relation.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const relationCreateSchema = z.strictObject({
+  // For dependency, the source task depends on the target task.
+  sourceTaskKey: z.string(),
+  targetTaskKey: z.string(),
+  relation_type: z.enum(["related", "dependency", "duplicate"]),
+});
+
+export type RelationCreateInput = z.infer<typeof relationCreateSchema>;

package/src/types.ts

@@ -5,6 +5,8 @@ export type Bind<T, K extends string & keyof T = string & keyof T> = {
   [Property in BoundProperty<K>]: T[keyof T];
 };
 
+export type WithId<T extends { id: string }> = Pick<T, "id"> & Partial<Omit<T, "id">>;
+
 export type Project = {
   id: string;
   key: string;
@@ -15,7 +17,6 @@ export type Project = {
   archived_at: number | null;
 };
 
-export type TaskMoveDirection = "top" | "up" | "down" | "bottom";
 export type Task = {
   id: string;
   project_id: string;
@@ -29,6 +30,15 @@ export type Task = {
   archived_at: number | null;
 };
 
+export type TaskRelationType = "related" | "dependency" | "duplicate";
+export type TaskRelation = {
+  id: string;
+  source_task_id: string;
+  target_task_id: string;
+  relation_type: TaskRelationType;
+  created_at: number;
+};
+
 export type Column = {
   id: string;
   project_id: string;