@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.
- package/README.md +74 -31
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,14 +1,69 @@
|
|
|
1
1
|
# cross-domain-references
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
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
|
-
|
|
35
|
-
|
|
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
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
-
|
|
70
|
-
|
|
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
|
|
84
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
19
|
+
"@dads-framework/errors": "0.2.0"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {
|
|
22
|
-
"@dads-framework/postgres": "0.
|
|
22
|
+
"@dads-framework/postgres": "0.2.0",
|
|
23
23
|
"@types/pg": "^8.20.0",
|
|
24
24
|
"vitest": "~4.1.0"
|
|
25
25
|
},
|