@dads-framework/cross-domain-references 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +74 -31
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,14 +1,69 @@
1
1
  # cross-domain-references
2
2
 
3
- The reconciliation half of ADR-0023,
4
- as a kit every product runs.
3
+ Find dangling IDs after domains choose independent database schemas. Declare
4
+ each cross-domain reference and run a read-only check against Postgres. The
5
+ check reports stored IDs that have no target row, so you can clean up data
6
+ before adding a foreign key or moving records.
5
7
 
6
- Domains can replace cross-domain foreign keys with explicit references. That trade keeps
7
- domain schemas on independent lifecycles, and the escape hatch it banks on is
8
- that an FK can always be added later — which is true only while the data is
9
- clean, because `ALTER TABLE … ADD FOREIGN KEY` fails on the first dangling row.
10
- So every product LEFT JOINs every reference it declares to the key that
11
- reference claims to point at, and reports the values that match nothing.
8
+ ## Try it
9
+
10
+ In a Node.js 22+ project, install the packages.
11
+
12
+ ```sh
13
+ npm install @dads-framework/cross-domain-references @dads-framework/postgres
14
+ ```
15
+
16
+ Set `DATABASE_URL` to the connection string for a running PostgreSQL database. The
17
+ database role needs permission to create temporary tables.
18
+
19
+ Save this as `example.mts` and run `node --experimental-strip-types example.mts`.
20
+
21
+ <!-- dads:check-example -->
22
+
23
+ ```ts
24
+ import {
25
+ checkCrossDomainReferences,
26
+ declareCrossDomainReferences,
27
+ } from "@dads-framework/cross-domain-references";
28
+ import { connectPostgresClient } from "@dads-framework/postgres";
29
+
30
+ const databaseUrl = process.env["DATABASE_URL"];
31
+ if (!databaseUrl) throw new Error("Set DATABASE_URL");
32
+
33
+ const references = declareCrossDomainReferences([
34
+ {
35
+ id: "orders.managing_organization_id",
36
+ consumerDomain: "orders",
37
+ consumerTable: "orders",
38
+ consumerColumn: "managing_organization_id",
39
+ providerDomain: "organizations",
40
+ providerTable: "organizations",
41
+ providerColumn: "id",
42
+ classification: "live-association",
43
+ },
44
+ ]);
45
+
46
+ const client = await connectPostgresClient(databaseUrl);
47
+ try {
48
+ await client.query("CREATE TEMP TABLE organizations (id text PRIMARY KEY)");
49
+ await client.query(
50
+ "CREATE TEMP TABLE orders (managing_organization_id text)",
51
+ );
52
+ await client.query("INSERT INTO orders VALUES ($1)", ["missing-org"]);
53
+ const findings = await checkCrossDomainReferences(client, references);
54
+ console.log(findings.flatMap((finding) => finding.sampleIds).join(", "));
55
+ } finally {
56
+ await client.end();
57
+ }
58
+ ```
59
+
60
+ The script prints `missing-org`. The temporary tables disappear when the
61
+ connection closes.
62
+
63
+ Declare references beside the consuming domain and call the check from an
64
+ operator command or CI job. The PostgreSQL integration test seeds a document
65
+ with a missing owner and verifies that the report identifies it.
66
+ [PostgreSQL integration test](./src/lib/database/check-cross-domain-references.integration.test.ts)
12
67
 
13
68
  ## A declaration
14
69
 
@@ -16,7 +71,7 @@ A reference belongs to the domain whose table carries the id, so the
16
71
  declaration lives in that domain, never in a central file:
17
72
 
18
73
  ```ts
19
- // libs/<product>/domains/orders/server/src/lib/public-api/cross-domain-references.ts
74
+ import { declareCrossDomainReferences } from "@dads-framework/cross-domain-references";
20
75
  export const ordersCrossDomainReferences = declareCrossDomainReferences([
21
76
  {
22
77
  id: "orders.managing_organization_id",
@@ -31,8 +86,8 @@ export const ordersCrossDomainReferences = declareCrossDomainReferences([
31
86
  ]);
32
87
  ```
33
88
 
34
- `classification` is ADR-0023's, and it travels with the finding so a report
35
- reads with the policy that governs its repair. A polymorphic column — one whose
89
+ Each finding carries the reference's `classification` so an operator can
90
+ apply the application's repair policy. A polymorphic column — one whose
36
91
  target table is chosen by a `*_kind` / `*_type` discriminator — is one
37
92
  declaration per arm, each narrowed by `filters`, or by `discriminatedByParent`
38
93
  when the discriminator sits on a parent row. `declareCrossDomainReferences`
@@ -53,7 +108,7 @@ contract. The checker validates the rows returned by that client.
53
108
  The product's composition root assembles one list:
54
109
 
55
110
  ```ts
56
- export const commandCrossDomainReferences = assembleCrossDomainReferences([
111
+ export const applicationCrossDomainReferences = assembleCrossDomainReferences([
57
112
  ordersCrossDomainReferences,
58
113
  facilitiesCrossDomainReferences,
59
114
  // …one entry per domain that declares any
@@ -64,32 +119,20 @@ An empty list is valid and means what it says — this product declares no
64
119
  cross-domain reference yet. It is not silence: the check still runs and reports
65
120
  that it checked nothing.
66
121
 
67
- That list reaches two places:
68
-
69
- - **`npm run db:check-references -- --product <name>`** — `tools/check-cross-domain-references`,
70
- for a database someone can already reach (local, CI, the nightly job). Exit
71
- codes: `0` clean, `1` dangling references found, `2` the check could not run.
72
- - **The live-environment action `cross-domain-references.check`** — for the
73
- environments nobody should have to shell into. Routine tier, read-only, its
74
- handler delegating to this kit's `CheckCrossDomainReferences` query. The
75
- product declares it, not this kit: the live-environment-actions kit declares
76
- a loose reference of its own and therefore imports this one, so an action
77
- defined here would close a cycle. The application declares its own beside
78
- its API composition root.
122
+ Pass the list to `checkCrossDomainReferences(client, references)` from a CI
123
+ job or an operator command. Use `CheckCrossDomainReferences` when wiring a
124
+ read-only diagnostic action in the application. The package provides report
125
+ formatters for clean results and dangling references.
79
126
 
80
127
  ## What counts as dangling
81
128
 
82
129
  Existence, and only existence. A row naming a soft-deleted organization or
83
- facility is fine: ADR-0023 archives referenced registry rows rather than
84
- removing them, and status/scope validation belongs to the accepting mutation,
85
- not to reconciliation.
130
+ facility still points to an existing row. The accepting mutation owns
131
+ status and scope validation.
86
132
 
87
133
  ## What is deliberately not declared
88
134
 
89
- Registration is the only outcome for a loose cross-domain id column
90
- withdrew the exception hatch, which had been an empty array for its whole life.
91
- These are the cases the rule never sees at all, kept here so they are not
92
- rediscovered as false positives:
135
+ Declare references whose target existence this query can check. These cases belong elsewhere.
93
136
 
94
137
  - **SpiceDB object references** over an open string vocabulary — they are not
95
138
  rows in this database.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dads-framework/cross-domain-references",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=22"
@@ -16,10 +16,10 @@
16
16
  "README.md"
17
17
  ],
18
18
  "dependencies": {
19
- "@dads-framework/errors": "0.1.0"
19
+ "@dads-framework/errors": "0.2.0"
20
20
  },
21
21
  "devDependencies": {
22
- "@dads-framework/postgres": "0.1.0",
22
+ "@dads-framework/postgres": "0.2.0",
23
23
  "@types/pg": "^8.20.0",
24
24
  "vitest": "~4.1.0"
25
25
  },