@dads-framework/authorization-migration 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 +90 -17
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,17 +1,90 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
1
|
+
# `@dads-framework/authorization-migration`
|
|
2
|
+
|
|
3
|
+
Scaffold and apply ordered SpiceDB schema snapshots and relationship migration steps.
|
|
4
|
+
|
|
5
|
+
## Try it
|
|
6
|
+
|
|
7
|
+
The generated starter uses Postgres for authorization in
|
|
8
|
+
[`assembly/services.ts`](../../../apps/kit-workbench/assembly/services.ts). For the SpiceDB schema journal, see the repository's
|
|
9
|
+
[journal runner tests](./src/lib/run-authorization-migrations.test.ts), which
|
|
10
|
+
show ordered application and a rerun that skips applied entries.
|
|
11
|
+
|
|
12
|
+
Use Node.js 22 or later. The script creates a temporary journal, previews the
|
|
13
|
+
first migration ID, then checks that scaffolding the same schema again is a
|
|
14
|
+
no-op. No SpiceDB instance is needed to scaffold.
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
npm install @dads-framework/authorization-migration
|
|
18
|
+
npm install -D tsx
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Save as `scaffold-journal.mts` and run `npx tsx scaffold-journal.mts`.
|
|
22
|
+
|
|
23
|
+
<!-- dads:check-example -->
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { mkdtemp, rm } from "node:fs/promises";
|
|
27
|
+
import { tmpdir } from "node:os";
|
|
28
|
+
import { join } from "node:path";
|
|
29
|
+
import {
|
|
30
|
+
listShippedAuthorizationMigrationIds,
|
|
31
|
+
scaffoldMigration,
|
|
32
|
+
} from "@dads-framework/authorization-migration";
|
|
33
|
+
|
|
34
|
+
const journalFolder = await mkdtemp(join(tmpdir(), "dads-journal-"));
|
|
35
|
+
try {
|
|
36
|
+
const input = {
|
|
37
|
+
journalFolder,
|
|
38
|
+
mode: "new",
|
|
39
|
+
slug: "baseline",
|
|
40
|
+
composedSchema: `
|
|
41
|
+
definition authz/migration_version {}
|
|
42
|
+
definition authz/migration_journal {
|
|
43
|
+
relation applied: authz/migration_version
|
|
44
|
+
}
|
|
45
|
+
definition user {}
|
|
46
|
+
`,
|
|
47
|
+
} satisfies Parameters<typeof scaffoldMigration>[0];
|
|
48
|
+
|
|
49
|
+
console.log((await scaffoldMigration(input)).action);
|
|
50
|
+
console.log(
|
|
51
|
+
(await listShippedAuthorizationMigrationIds(journalFolder)).join(),
|
|
52
|
+
);
|
|
53
|
+
console.log((await scaffoldMigration(input)).action);
|
|
54
|
+
} finally {
|
|
55
|
+
await rm(journalFolder, { recursive: true, force: true });
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The script prints `created`, `0001_baseline`, and `up-to-date`. To retain
|
|
60
|
+
the generated `index.ts`, `schema.zed`, and `migration.ts` in your app, use
|
|
61
|
+
an existing journal directory and omit the temporary directory cleanup.
|
|
62
|
+
|
|
63
|
+
## Use it
|
|
64
|
+
|
|
65
|
+
Pass the generated index's `journal`, the absolute path of its directory, an
|
|
66
|
+
`AuthorizationMigrationStore`, and a logger with an `info` method to
|
|
67
|
+
`runAuthorizationMigrations`. For a development run against SpiceDB, start
|
|
68
|
+
with a dedicated datastore and construct `SpiceDbAuthorization` from
|
|
69
|
+
`@dads-framework/authorization` with its endpoint and credentials. Pass the
|
|
70
|
+
adapter as `store`. A successful run logs the applied ID. Rerunning the
|
|
71
|
+
same journal reports zero newly applied entries.
|
|
72
|
+
|
|
73
|
+
For independently authored patches, use `scaffoldAuthorizationChange` and
|
|
74
|
+
pass their directory as `changesFolder` on the same runner. Each patch
|
|
75
|
+
records the definitions it changes and the changes it depends on.
|
|
76
|
+
`renumberMigration` moves a snapshot entry that collided with another branch.
|
|
77
|
+
|
|
78
|
+
## What it refuses to do
|
|
79
|
+
|
|
80
|
+
The runner rejects gaps, duplicate entries, unregistered folders, and snapshots
|
|
81
|
+
that drop the journal definition. A destructive entry after the baseline
|
|
82
|
+
requires the relationship steps that make its schema write legal.
|
|
83
|
+
|
|
84
|
+
## Contract
|
|
85
|
+
|
|
86
|
+
Each `NNNN_slug` holds a full schema snapshot. The runner calls
|
|
87
|
+
`beforeSchemaWrite`, writes the snapshot, and then calls `afterSchemaWrite`
|
|
88
|
+
when those steps are present. It records success as an
|
|
89
|
+
`authz/migration_version` relationship. A failure leaves the marker
|
|
90
|
+
unwritten. Make relationship steps safe to repeat when retrying an entry.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dads-framework/authorization-migration",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"engines": {
|
|
6
6
|
"node": ">=22"
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"README.md"
|
|
17
17
|
],
|
|
18
18
|
"dependencies": {
|
|
19
|
-
"@dads-framework/access": "0.
|
|
19
|
+
"@dads-framework/access": "0.2.0",
|
|
20
20
|
"jiti": "2.4.2",
|
|
21
21
|
"zod": "^4.4.3"
|
|
22
22
|
},
|