index.ts · Source

index.tspackages/database-engine/src/relations/index.tsraw ← relations5,220 B← Back to the app
1/**
2 * @factory/database-engine/relations — link-set diffing + cardinality policy
3 * (TASK-0081, pure half).
4 *
5 * `diffLinks` computes the {added, removed} of an absolute desired link set
6 * vs the current set (the API's transaction does delete-then-insert).
7 * `applyCardinality` enforces the cardinality policy (database-architecture
8 * §1.4: "cardinality as policy, not constraint"): 1:1 replacement semantics
9 * (a second target on the "one" side unlinks the previous — the replaced
10 * ids are returned), 1:N single-side assertions. The join table is uniform
11 * M:N; these functions decide what the transaction writes.
12 */
13 
14export type Cardinality = "ONE_TO_ONE" | "ONE_TO_MANY" | "MANY_TO_MANY";
15 
16export interface LinkDiff {
17  added: string[];
18  removed: string[];
19  unchanged: string[];
20}
21 
22/**
23 * Diff an absolute desired set against the current links.
24 * `current` = record's existing target ids; `desired` = the full desired set
25 * (the client sends absolute, not delta — TASK-0081 R1).
26 */
27export function diffLinks(current: readonly string[], desired: readonly string[]): LinkDiff {
28  const cur = new Set(current);
29  const des = new Set(desired);
30  const added: string[] = [];
31  const removed: string[] = [];
32  const unchanged: string[] = [];
33  for (const id of desired) {
34    if (cur.has(id)) unchanged.push(id);
35    else added.push(id);
36  }
37  for (const id of current) {
38    if (!des.has(id)) removed.push(id);
39  }
40  return { added, removed, unchanged };
41}
42 
43export interface CardinalityCheck {
44  ok: boolean;
45  /** Target ids to unlink (1:1 replacement). */
46  replaced: string[];
47  error?: string;
48}
49 
50/**
51 * Validate a desired link set against the relation's cardinality.
52 * `isOneSide` = whether this record sits on the exclusive ("one") side.
53 *  - ONE_TO_ONE: the "one" side holds at most 1 target; a 2nd replaces the
54 *    first (`replaced` = the previous id, returned to the API for its
55 *    response). Both sides exclusive — the caller also checks the target's
56 *    existing partner (bidirectional replacement).
57 *  - ONE_TO_MANY: the "one" side holds exactly ≤ 1 target (>1 → 400); the
58 *    "many" side is unlimited.
59 *  - MANY_TO_MANY: unlimited.
60 * Target ids are deduped (a repeated id in the desired set is not an error).
61 */
62export function applyCardinality(
63  current: readonly string[],
64  desired: readonly string[],
65  cardinality: Cardinality,
66  isOneSide: boolean,
67): CardinalityCheck {
68  const deduped = [...new Set(desired)];
69  if (cardinality === "MANY_TO_MANY") return { ok: true, replaced: [] };
70  if (isOneSide) {
71    if (deduped.length > 1) {
72      return { ok: false, replaced: [], error: "one_side_exceeds_one_target" };
73    }
74    // 1:1 — replacing the previous link is allowed
75    const replaced = current.filter((id) => !deduped.includes(id));
76    return { ok: true, replaced };
77  }
78  // many side of 1:N — unlimited targets
79  return { ok: true, replaced: [] };
80}
81 
82/**
83 * Compute the full transaction plan for `setLinks`: the join-table rows to
84 * delete and insert, plus (1:1) the displaced partner on the target side.
85 * `targetPartners` = map of target id → the record currently partnered with
86 * it (for bidirectional 1:1 replacement).
87 */
88export interface SetLinksPlan {
89  deleteIds: string[];
90  insertIds: string[];
91  /** 1:1: records on the OTHER side displaced by this set. */
92  displacedPartners: Array<{ targetId: string; partnerRecordId: string }>;
93  replaced: string[];
94}
95 
96export function planSetLinks(
97  current: readonly string[],
98  desired: readonly string[],
99  cardinality: Cardinality,
100  isOneSide: boolean,
101  targetPartners: ReadonlyMap<string, string>,
102): SetLinksPlan {
103  const check = applyCardinality(current, desired, cardinality, isOneSide);
104  if (!check.ok) throw new Error(check.error ?? "cardinality violation");
105  const { added, removed } = diffLinks(current, desired);
106  const deduped = [...new Set(desired)];
107  const displacedPartners: Array<{ targetId: string; partnerRecordId: string }> = [];
108  if (cardinality === "ONE_TO_ONE") {
109    for (const targetId of deduped) {
110      const partner = targetPartners.get(targetId);
111      if (partner !== undefined) displacedPartners.push({ targetId, partnerRecordId: partner });
112    }
113  }
114  return { deleteIds: removed, insertIds: added, displacedPartners, replaced: check.replaced };
115}
116 
117/** Cascade: record trash → its links removed (both directions by row shape). */
118export function linksForRecord(
119  links: readonly {
120    databaseId: string;
121    recordId: string;
122    targetDatabaseId: string;
123    targetRecordId: string;
124  }[],
125  recordId: string,
126): string[] {
127  const out = new Set<string>();
128  for (const l of links) {
129    if (l.recordId === recordId) out.add(l.targetRecordId);
130  }
131  return [...out];
132}
133 
134/** Relation counts for the query response (TASK-0081 R2 `relationCounts`). */
135export function relationCounts(
136  links: readonly { recordId: string; targetRecordId: string }[],
137  recordIds: readonly string[],
138): Record<string, number> {
139  const counts: Record<string, number> = {};
140  for (const id of recordIds) counts[id] = 0;
141  for (const l of links) {
142    if (counts[l.recordId] !== undefined) counts[l.recordId] = (counts[l.recordId] ?? 0) + 1;
143  }
144  return counts;
145}
146