ramdb2-cli 2.0.0-alpha.2 → 2.0.0-alpha.20
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/CHANGELOG.md +83 -0
- package/README.md +21 -2
- package/package.json +2 -2
- package/src/cli.js +17 -2
- package/src/directives.js +12 -3
- package/src/generate/classes.js +29 -0
- package/src/generate/client.js +18 -6
- package/src/generate/typeDefs.js +16 -2
- package/src/generate.js +45 -7
- package/src/index.js +1 -0
- package/src/infra/down.js +19 -0
- package/src/model.js +51 -1
- package/src/new.js +2 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,88 @@
|
|
|
1
1
|
# ramdb2-cli
|
|
2
2
|
|
|
3
|
+
## 2.0.0-alpha.20
|
|
4
|
+
|
|
5
|
+
No changes in this release.
|
|
6
|
+
|
|
7
|
+
## 2.0.0-alpha.19
|
|
8
|
+
|
|
9
|
+
No changes in this release.
|
|
10
|
+
|
|
11
|
+
## 2.0.0-alpha.18
|
|
12
|
+
|
|
13
|
+
No changes in this release.
|
|
14
|
+
|
|
15
|
+
## 2.0.0-alpha.17
|
|
16
|
+
|
|
17
|
+
No changes in this release.
|
|
18
|
+
|
|
19
|
+
## 2.0.0-alpha.16
|
|
20
|
+
|
|
21
|
+
No changes in this release.
|
|
22
|
+
|
|
23
|
+
## 2.0.0-alpha.15
|
|
24
|
+
|
|
25
|
+
No changes in this release.
|
|
26
|
+
|
|
27
|
+
## 2.0.0-alpha.14
|
|
28
|
+
|
|
29
|
+
No changes in this release.
|
|
30
|
+
|
|
31
|
+
## 2.0.0-alpha.13
|
|
32
|
+
|
|
33
|
+
No changes in this release.
|
|
34
|
+
|
|
35
|
+
## 2.0.0-alpha.12
|
|
36
|
+
|
|
37
|
+
No changes in this release.
|
|
38
|
+
|
|
39
|
+
## 2.0.0-alpha.11
|
|
40
|
+
|
|
41
|
+
### Patch Changes
|
|
42
|
+
|
|
43
|
+
- cf18bd4: Dates stored as Unix seconds (D64 of ramdb2, D25 of the client). The directives `@date` (a day, without time zone: the seconds of its midnight UTC) and `@datetime` (an instant) go on an `Int` field; 0 or null is no date. The generated client class lists them in `static dates`. `ramdb2-core` and `ramdb2-client` export the same date functions: `day`, `dayText`, `dateTime`, `dateTimeText`, `today(timeZone)`, `dayOf`, `addDays`, `addMonths`… ramdb2-vue shows them as `YYYY-MM-DD` (`HH:MM:SS`), sorts and filters on the seconds, searches a typed day, month or year, exports real Excel dates and CSV text, and types them with the date input of the browser; option `dates: { timeZone, formatDate, formatDateTime }` of the site. The schema of `ramdb2-cli new` gets `Task.due: Int @date`.
|
|
44
|
+
|
|
45
|
+
## 2.0.0-alpha.10
|
|
46
|
+
|
|
47
|
+
No changes in this release.
|
|
48
|
+
|
|
49
|
+
## 2.0.0-alpha.9
|
|
50
|
+
|
|
51
|
+
No changes in this release.
|
|
52
|
+
|
|
53
|
+
## 2.0.0-alpha.8
|
|
54
|
+
|
|
55
|
+
No changes in this release.
|
|
56
|
+
|
|
57
|
+
## 2.0.0-alpha.7
|
|
58
|
+
|
|
59
|
+
### Minor Changes
|
|
60
|
+
|
|
61
|
+
- 8fa4d07: `@transient(getter: true)`: a getter of the class gives the value of the field, so a query filters and sorts on it (`static transientGetters`), and `RdbCrud` sorts its column by default. ramdb2-server refuses to start when the getter is missing, and refuses in a query a `@transient` resolved by GraphQL only (D62).
|
|
62
|
+
|
|
63
|
+
## 2.0.0-alpha.6
|
|
64
|
+
|
|
65
|
+
No changes in this release.
|
|
66
|
+
|
|
67
|
+
## 2.0.0-alpha.5
|
|
68
|
+
|
|
69
|
+
### Minor Changes
|
|
70
|
+
|
|
71
|
+
- e34f3bd: `generate` and `client` remove the generated classes of a type gone from the schema, and name its extended class in a warning (D61).
|
|
72
|
+
|
|
73
|
+
## 2.0.0-alpha.4
|
|
74
|
+
|
|
75
|
+
### Minor Changes
|
|
76
|
+
|
|
77
|
+
- 919e6ae: Permissions by field (D58): `@restricted` in the schema, `permissions.<Type>.fields` in ramdb2-server. A refused field gives `null`; a query on a restricted field only covers the objects whose field the user may read.
|
|
78
|
+
- a26c413: The `see` permission applies to the relations (D57): a list relation is filtered, an object relation the user cannot see gives `null`. `ramdb2-cli generate` serves the object relations as nullable; `ramdb2-cli client` types them `Xxx | null`.
|
|
79
|
+
|
|
80
|
+
## 2.0.0-alpha.3
|
|
81
|
+
|
|
82
|
+
### Minor Changes
|
|
83
|
+
|
|
84
|
+
- 92570bd: `ramdb2-cli infra down <server>`: stops a server (docker compose down), keeps its volumes; asks first, unless `--yes`.
|
|
85
|
+
|
|
3
86
|
## 2.0.0-alpha.2
|
|
4
87
|
|
|
5
88
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -42,12 +42,16 @@ Several `--schema` files are read as one schema. In a project created by `ramdb2
|
|
|
42
42
|
| `db/generated/<table>.js` | class `XxxBase`: fields, foreign keys, indexes, rules, default values, getters and setters, relations, computed fields, finders, invalidation code | at each generation |
|
|
43
43
|
| `db/extended/<table>.js` | class `Xxx extends XxxBase`: your business rules, computed fields and methods | never: created when missing |
|
|
44
44
|
| `db/index.js` | the extended classes, and `classes` for `store.register(...classes)` | at each generation |
|
|
45
|
-
| `schema/typeDefs.graphql` | the schema served by the API: without the directives (but `@sensitive`) nor the `@private` fields, with `id` and the foreign keys | at each generation |
|
|
45
|
+
| `schema/typeDefs.graphql` | the schema served by the API: without the directives (but `@sensitive`) nor the `@private` fields, with `id` and the foreign keys; a field that leads to one persistent object is nullable, as the `see` permission may hide it, and so is a `@restricted` field | at each generation |
|
|
46
46
|
| `schema/operations.graphql` | the `JSON` scalar, and for each type its input (with the `@sensitive` fields, without the `@private` ones), validation, query and list types, its queries and mutations | at each generation |
|
|
47
47
|
|
|
48
48
|
Never edit a generated file: the next generation would erase the change. Everything you write goes in
|
|
49
49
|
`db/extended`, and in your own schema files (`extend type Query { ... }`).
|
|
50
50
|
|
|
51
|
+
When a type leaves the schema, its file in `db/generated/` is removed (`removed` in the output); only a file with
|
|
52
|
+
the header `// Generated by ramdb2-cli` is ever removed. Its file in `db/extended/`, written by you, is kept and
|
|
53
|
+
named in a warning. `client` does the same in its `generated/` and `extended/` folders.
|
|
54
|
+
|
|
51
55
|
### The schema: the preTypeDefs
|
|
52
56
|
|
|
53
57
|
```graphql
|
|
@@ -96,9 +100,12 @@ a directive in the wrong place, a missing or badly typed argument is an error.
|
|
|
96
100
|
| `@onDelete` | list | `action: CASCADE \| SET_ZERO \| RESTRICT \| NOTHING` | deletion policy of these objects |
|
|
97
101
|
| `@computed` | field | `depends: [String!]!` | a cached value, with the paths it depends on |
|
|
98
102
|
| `@pattern` | field | `regex: String!`, `message: String` | a validation rule |
|
|
99
|
-
| `@transient` | field | | a field of the API that is not stored |
|
|
103
|
+
| `@transient` | field | `getter: Boolean = false` | a field of the API that is not stored. `getter: true`: a getter of the class gives its value (written in the extended class), so a query filters and sorts on it, and ramdb2-server checks the getter at start. A scalar without arguments. Not indexed: a query reads the getter on every candidate object |
|
|
100
104
|
| `@sensitive` | field | | its value is masked in the logs of ramdb2-server (`"[REDACTED]"`) |
|
|
101
105
|
| `@private` | field | | stored and read by your code, but absent from the API: neither read, written nor queried (a password hash). Not with `!` when it would be required, nor with a FULLTEXT index |
|
|
106
|
+
| `@date` | field | | an `Int` that is a day of the calendar, without time zone: the Unix seconds of its midnight UTC; 0 or null for no date. ramdb2-vue shows, searches, exports and types it as a date |
|
|
107
|
+
| `@datetime` | field | | an `Int` that is an instant: Unix seconds; 0 or null for no date. Shown and typed in the time zone of the site |
|
|
108
|
+
| `@restricted` | field | | read through the API only when its permission allows it, object by object (`permissions.<Type>.fields` of ramdb2-server); served nullable. On a stored field, an object relation (with its foreign key), a computed or `@transient` field. A computed field that depends on it must be `@restricted` too |
|
|
102
109
|
|
|
103
110
|
### How the fields are read
|
|
104
111
|
|
|
@@ -258,6 +265,7 @@ as for `generate`). It writes, in `--dest`:
|
|
|
258
265
|
API.
|
|
259
266
|
- `transient`: the `@transient` fields of a scalar type (scalar, enum, custom scalar, list of them), always loaded
|
|
260
267
|
with the object. One of an object type, or with a required argument, is left out with a warning.
|
|
268
|
+
- `transientGetters`: the `@transient(getter: true)` fields, sorted by default in a `RdbCrud`.
|
|
261
269
|
- `fullText`: the fields of the `FULLTEXT` index, in the order of the schema (`[]` without one), for a search with `$text`.
|
|
262
270
|
- `generatedRules`: the same rules as the server (`required`, `pattern`, `oneOf`), plus `requiredKey('idProject')`
|
|
263
271
|
for a required object relation.
|
|
@@ -444,6 +452,17 @@ not point to the server yet) does not stop the others; the exit code is then 1.
|
|
|
444
452
|
The decrypted secrets live in `build/<server>/.secrets-*` (only you can read it) while a command runs, and are
|
|
445
453
|
deleted at the end, even on an error. Not in `/tmp`: Docker installed as a snap cannot read it.
|
|
446
454
|
|
|
455
|
+
### Stop a server
|
|
456
|
+
|
|
457
|
+
```sh
|
|
458
|
+
ramdb2-cli infra down ovh1 # asks first; --yes to skip the question
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
`down` runs `docker compose down --remove-orphans` on the server: the containers of all its sites (ramdb2 and
|
|
462
|
+
custom) and its network are removed. The volumes (the databases, the backup queues), the images and the
|
|
463
|
+
certificates stay: `ramdb2-cli infra deploy ovh1` starts the server again as it was. Like every command that talks
|
|
464
|
+
to a server, it decrypts the secrets: Compose needs them to read `compose.yaml`.
|
|
465
|
+
|
|
447
466
|
### Secrets: sops and age, once
|
|
448
467
|
|
|
449
468
|
```sh
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ramdb2-cli",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.20",
|
|
4
4
|
"description": "Code generator and project scaffolding for ramdb2 and ramdb2-server",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": "./src/index.js",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"devDependencies": {
|
|
30
30
|
"@vitejs/plugin-vue": "^6.0.10",
|
|
31
|
-
"ramdb2-core": "^2.0.0-alpha.
|
|
31
|
+
"ramdb2-core": "^2.0.0-alpha.20",
|
|
32
32
|
"vite": "^8.3.5",
|
|
33
33
|
"vue": "^3.5.44",
|
|
34
34
|
"vue-router": "^5.4.0"
|
package/src/cli.js
CHANGED
|
@@ -9,6 +9,7 @@ import { query } from './query.js'
|
|
|
9
9
|
import { readInfra } from './infra/config.js'
|
|
10
10
|
import { buildInfra } from './infra/build.js'
|
|
11
11
|
import { deploy } from './infra/deploy.js'
|
|
12
|
+
import { down } from './infra/down.js'
|
|
12
13
|
import { keygen } from './infra/keygen.js'
|
|
13
14
|
import { fetch as fetchBackup, listBackups, restore } from './infra/backups.js'
|
|
14
15
|
import { createInterface } from 'node:readline/promises'
|
|
@@ -50,6 +51,10 @@ const HELP = `ramdb2-cli: code generator of ramdb2
|
|
|
50
51
|
on the server (DOCKER_HOST=ssh://...), the missing Let's Encrypt certificates, and nginx reloaded.
|
|
51
52
|
--staging: the test certificates of Let's Encrypt, not trusted by browsers.
|
|
52
53
|
|
|
54
|
+
ramdb2-cli infra down <server> [--yes]
|
|
55
|
+
Stops the server: docker compose down, its containers and its network removed. The volumes (the
|
|
56
|
+
databases), the images and the certificates stay: infra deploy starts it again. Asks first, unless --yes.
|
|
57
|
+
|
|
53
58
|
ramdb2-cli infra keygen <server> [--force]
|
|
54
59
|
Creates the SSH key of the server for its backups: secrets/<server>.key, encrypted by sops (.sops.yaml),
|
|
55
60
|
and secrets/<server>.pub, printed, to install on the backup server. --force replaces an existing key.
|
|
@@ -122,14 +127,15 @@ const commands = {
|
|
|
122
127
|
},
|
|
123
128
|
}
|
|
124
129
|
|
|
125
|
-
function report({ written, kept, warnings }) {
|
|
130
|
+
function report({ written, kept, removed = [], warnings }) {
|
|
126
131
|
for (const path of written) console.log(`written ${path}`)
|
|
127
132
|
for (const path of kept) console.log(`kept ${path} (written by hand)`)
|
|
133
|
+
for (const path of removed) console.log(`removed ${path} (type no longer in the schema)`)
|
|
128
134
|
for (const warning of warnings) console.log(`warning ${warning}`)
|
|
129
135
|
}
|
|
130
136
|
|
|
131
137
|
async function infra(values, [action, ...args]) {
|
|
132
|
-
const actions = ['build', 'deploy', 'keygen', 'backups', 'restore', 'fetch']
|
|
138
|
+
const actions = ['build', 'deploy', 'down', 'keygen', 'backups', 'restore', 'fetch']
|
|
133
139
|
if (!actions.includes(action)) return usage(`infra needs an action: ${actions.join(', ')}`)
|
|
134
140
|
const infra = readInfra(values.config ?? 'infra.yaml')
|
|
135
141
|
switch (action) {
|
|
@@ -145,6 +151,15 @@ async function infra(values, [action, ...args]) {
|
|
|
145
151
|
if (certificates.some(certificate => !certificate.ok)) process.exitCode = 1
|
|
146
152
|
return
|
|
147
153
|
}
|
|
154
|
+
case 'down':
|
|
155
|
+
if (args.length !== 1) return usage('infra down needs one server')
|
|
156
|
+
if (!infra.servers.some(server => server.name === args[0])) throw new Error(`No server ${args[0]} in infra.yaml`)
|
|
157
|
+
if (!values.yes && !(await confirm(`Stop all the sites of ${args[0]}? Their data stays. [y/N] `))) {
|
|
158
|
+
console.log('Nothing done')
|
|
159
|
+
return
|
|
160
|
+
}
|
|
161
|
+
await down(infra, args[0])
|
|
162
|
+
return
|
|
148
163
|
case 'keygen':
|
|
149
164
|
if (args.length !== 1) return usage('infra keygen needs one server')
|
|
150
165
|
await keygen(infra, args[0], { force: values.force ?? false })
|
package/src/directives.js
CHANGED
|
@@ -27,16 +27,25 @@ directive @computed(depends: [String!]!) on FIELD_DEFINITION
|
|
|
27
27
|
"Validation rule: the value must match the regular expression."
|
|
28
28
|
directive @pattern(regex: String!, message: String) on FIELD_DEFINITION
|
|
29
29
|
|
|
30
|
-
"Field of a persistent type that is not stored: resolved elsewhere."
|
|
31
|
-
directive @transient on FIELD_DEFINITION
|
|
30
|
+
"Field of a persistent type that is not stored: resolved elsewhere. getter: a getter of the class gives its value, so a query can filter and sort on it (D62)."
|
|
31
|
+
directive @transient(getter: Boolean = false) on FIELD_DEFINITION
|
|
32
32
|
|
|
33
33
|
"Field stored and readable in code, but absent from the GraphQL API: neither read, written nor queried (D47)."
|
|
34
34
|
directive @private on FIELD_DEFINITION
|
|
35
35
|
|
|
36
|
+
"Field readable only when the permission of the server allows it, for each object (D58): served nullable."
|
|
37
|
+
directive @restricted on FIELD_DEFINITION
|
|
38
|
+
|
|
39
|
+
"An Int that is a day of the calendar, without time zone: the Unix seconds of its midnight UTC; 0 or null for no date (D64). Shown, searched, exported and typed as a date by ramdb2-vue."
|
|
40
|
+
directive @date on FIELD_DEFINITION
|
|
41
|
+
|
|
42
|
+
"An Int that is an instant: Unix seconds; 0 or null for no date (D64). Shown, searched, exported and typed as a date and a time by ramdb2-vue."
|
|
43
|
+
directive @datetime on FIELD_DEFINITION
|
|
44
|
+
|
|
36
45
|
"Value masked in the logs. Kept in the schema served by Apollo: ramdb2-server reads it."
|
|
37
46
|
directive @sensitive on FIELD_DEFINITION | INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION
|
|
38
47
|
`
|
|
39
48
|
|
|
40
49
|
/** Names of the directives above removed from the schema served by Apollo: all but @sensitive. */
|
|
41
|
-
export const DIRECTIVE_NAMES = new Set(['persistent', 'group', 'index', 'field', 'onDelete', 'computed', 'pattern', 'transient', 'private'])
|
|
50
|
+
export const DIRECTIVE_NAMES = new Set(['persistent', 'group', 'index', 'field', 'onDelete', 'computed', 'pattern', 'transient', 'private', 'restricted', 'date', 'datetime'])
|
|
42
51
|
export const INTERNAL_TYPES = new Set(['RamdbIndexType', 'RamdbOnDelete'])
|
package/src/generate/classes.js
CHANGED
|
@@ -40,6 +40,24 @@ function generatedClass(type, model, code) {
|
|
|
40
40
|
lines.push(' // @private: never read, written nor queried through the GraphQL API')
|
|
41
41
|
lines.push(` static privateFields = [${privateFields.map(quote).join(', ')}]`)
|
|
42
42
|
}
|
|
43
|
+
if (type.restricted.length > 0) {
|
|
44
|
+
lines.push('')
|
|
45
|
+
lines.push(' // @restricted: read through the API only when permissions.<Type>.fields allows it (D58)')
|
|
46
|
+
lines.push(` static restrictedFields = [${type.restricted.map(quote).join(', ')}]`)
|
|
47
|
+
}
|
|
48
|
+
if (type.transient.length > 0) {
|
|
49
|
+
lines.push('')
|
|
50
|
+
lines.push(' // @transient: not stored. Those of transientGetters are getters of the class, filtered and sorted by a query (D62)')
|
|
51
|
+
lines.push(` static transient = [${type.transient.map(t => quote(t.name)).join(', ')}]`)
|
|
52
|
+
lines.push(` static transientGetters = [${type.transient.filter(t => t.getter).map(t => quote(t.name)).join(', ')}]`)
|
|
53
|
+
}
|
|
54
|
+
if (type.children.length > 0) {
|
|
55
|
+
lines.push('')
|
|
56
|
+
lines.push(' // The list relations: the table of their objects and the foreign key that points here')
|
|
57
|
+
lines.push(' static listRelations = {')
|
|
58
|
+
for (const child of type.children) lines.push(` ${child.name}: { table: '${byNameTable(model, child.target)}', key: '${child.fk}' },`)
|
|
59
|
+
lines.push(' }')
|
|
60
|
+
}
|
|
43
61
|
|
|
44
62
|
const foreignKeys = type.parents.map(parent => [parent, onDeleteOf(parent, type, model)])
|
|
45
63
|
if (foreignKeys.length > 0) {
|
|
@@ -259,6 +277,13 @@ function extendedClass(type) {
|
|
|
259
277
|
lines.push('')
|
|
260
278
|
lines.push(' // Integrity rules checked by delete(): (values, obj) => "" | message')
|
|
261
279
|
lines.push(' static deleteRules = []')
|
|
280
|
+
for (const transient of type.transient.filter(t => t.getter)) {
|
|
281
|
+
lines.push('')
|
|
282
|
+
lines.push(` /** @returns {${transient.jsType}} @transient(getter: true): read by GraphQL and by the queries (D62) */`)
|
|
283
|
+
lines.push(` get ${transient.name}() {`)
|
|
284
|
+
lines.push(` throw new Error('${type.name}.${transient.name} is not written yet')`)
|
|
285
|
+
lines.push(' }')
|
|
286
|
+
}
|
|
262
287
|
for (const computed of type.computed) {
|
|
263
288
|
lines.push('')
|
|
264
289
|
lines.push(` /** @returns {${computed.jsType}} depends on ${computed.depends.join(', ')} */`)
|
|
@@ -290,3 +315,7 @@ export function jsdoc(description, indent, extra = []) {
|
|
|
290
315
|
export function quote(string) {
|
|
291
316
|
return `'${string}'`
|
|
292
317
|
}
|
|
318
|
+
|
|
319
|
+
function byNameTable(model, name) {
|
|
320
|
+
return model.byName.get(name).table
|
|
321
|
+
}
|
package/src/generate/client.js
CHANGED
|
@@ -70,8 +70,15 @@ function generatedClass(type, model) {
|
|
|
70
70
|
lines.push('')
|
|
71
71
|
lines.push(` static transient = [${transient.map(t => quote(t.name)).join(', ')}]`)
|
|
72
72
|
lines.push('')
|
|
73
|
+
lines.push(' // Getters of the server class: filtered and sorted by a query (D62 of ramdb2)')
|
|
74
|
+
lines.push(` static transientGetters = [${transient.filter(t => t.getter).map(t => quote(t.name)).join(', ')}]`)
|
|
75
|
+
lines.push('')
|
|
73
76
|
lines.push(` static fullText = [${fullText.map(quote).join(', ')}]`)
|
|
74
77
|
lines.push('')
|
|
78
|
+
// The Int fields that are dates, in Unix seconds (D64 of ramdb2): a day (date) or an instant (datetime)
|
|
79
|
+
const dates = Object.entries(type.dates).filter(([name]) => !privateFields.includes(name))
|
|
80
|
+
lines.push(` static dates = {${dates.length ? ' ' + dates.map(([name, kind]) => `${name}: '${kind}'`).join(', ') + ' ' : ''}}`)
|
|
81
|
+
lines.push('')
|
|
75
82
|
const relations = [
|
|
76
83
|
...type.parents.map(p => ` ${p.name}: { type: '${p.target}', key: '${p.fk}' },`),
|
|
77
84
|
...type.children.map(c => ` ${c.name}: { type: '${c.target}', key: '${c.fk}', list: true },`),
|
|
@@ -89,34 +96,39 @@ function generatedClass(type, model) {
|
|
|
89
96
|
lines.push(' }')
|
|
90
97
|
}
|
|
91
98
|
|
|
99
|
+
// A @restricted field may be hidden by its permission on the server (D58): null
|
|
100
|
+
const orNull = (name, jsType) => type.restricted.includes(name) && !/\bnull\b/.test(jsType) ? `${jsType} | null` : jsType
|
|
92
101
|
for (const parent of type.parents) {
|
|
93
102
|
lines.push('')
|
|
94
|
-
lines.push(` /** @returns {number} foreign key of ${parent.name}, 0 = none */`)
|
|
103
|
+
lines.push(` /** @returns {${orNull(parent.fk, 'number')}} foreign key of ${parent.name}, 0 = none */`)
|
|
95
104
|
lines.push(` get ${parent.fk}() { return this._f.${parent.fk} }`)
|
|
96
105
|
}
|
|
97
106
|
for (const field of fields) {
|
|
98
107
|
lines.push('')
|
|
99
|
-
lines.push(jsdoc(field.description, ' ', [`@returns {${field.jsType}}`]))
|
|
108
|
+
lines.push(jsdoc(field.description, ' ', [`@returns {${orNull(field.name, field.jsType)}}`]))
|
|
100
109
|
lines.push(` get ${field.name}() { return this._f.${field.name} }`)
|
|
101
110
|
}
|
|
102
111
|
for (const relation of [...type.parents, ...type.children]) {
|
|
103
112
|
const target = model.byName.get(relation.target)
|
|
104
|
-
|
|
113
|
+
// An object relation may be hidden by the permission see of the server (D57): null
|
|
114
|
+
const returns = type.children.includes(relation) ? '[]' : ' | null'
|
|
105
115
|
lines.push('')
|
|
106
116
|
lines.push(jsdoc(relation.description, ' ', [
|
|
107
117
|
`Loaded with include: ['${relation.name}'].`,
|
|
108
|
-
`@returns {import('../extended/${target.table}.js').default${
|
|
118
|
+
`@returns {import('../extended/${target.table}.js').default${returns}}`,
|
|
109
119
|
]))
|
|
110
120
|
lines.push(` get ${relation.name}() { return this._relation('${relation.name}') }`)
|
|
111
121
|
}
|
|
112
122
|
for (const computed of type.computed) {
|
|
113
123
|
lines.push('')
|
|
114
|
-
|
|
124
|
+
// Served nullable when it leads to one persistent object (D57)
|
|
125
|
+
const served = /^\w+!$/.test(computed.display) && model.byName.has(computed.display.slice(0, -1)) ? `${computed.jsType} | null` : computed.jsType
|
|
126
|
+
lines.push(jsdoc(computed.description, ' ', ['Computed by the server.', `@returns {${orNull(computed.name, served)}}`]))
|
|
115
127
|
lines.push(` get ${computed.name}() { return this._c.${computed.name} }`)
|
|
116
128
|
}
|
|
117
129
|
for (const field of transient) {
|
|
118
130
|
lines.push('')
|
|
119
|
-
lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${field.jsType}}`]))
|
|
131
|
+
lines.push(jsdoc(field.description, ' ', ['Resolved by the project on the server.', `@returns {${orNull(field.name, field.jsType)}}`]))
|
|
120
132
|
lines.push(` get ${field.name}() { return this._c.${field.name} }`)
|
|
121
133
|
}
|
|
122
134
|
lines.push('}')
|
package/src/generate/typeDefs.js
CHANGED
|
@@ -3,6 +3,8 @@ import { DIRECTIVE_NAMES } from '../directives.js'
|
|
|
3
3
|
|
|
4
4
|
// The schema served by Apollo (spec section 3): the preTypeDefs without the directives of ramdb2-cli,
|
|
5
5
|
// descriptions kept, with the id and the foreign keys of the persistent types.
|
|
6
|
+
// A field that leads to one persistent object is served nullable (D57): the permission `see` may hide it.
|
|
7
|
+
// A @restricted field, and the foreign key of a @restricted relation, too (D58): its permission may hide it.
|
|
6
8
|
|
|
7
9
|
/**
|
|
8
10
|
* @param {import('../model.js').Model} model
|
|
@@ -23,8 +25,9 @@ export function typeDefsFile(model) {
|
|
|
23
25
|
if (field.directives?.some(directive => directive.name.value === 'private')) continue
|
|
24
26
|
const parent = type.parents.find(p => p.name === field.name.value)
|
|
25
27
|
// The foreign key, before its relation: what a client sends to create or modify the object
|
|
26
|
-
|
|
27
|
-
fields.push(
|
|
28
|
+
const restricted = type.restricted.includes(field.name.value)
|
|
29
|
+
if (parent !== undefined) fields.push(fieldNode(`${parent.fk}: Int${restricted ? '' : '!'}`))
|
|
30
|
+
fields.push(restricted ? nullable(field) : nullableObject(field, model))
|
|
28
31
|
}
|
|
29
32
|
return { ...node, fields }
|
|
30
33
|
},
|
|
@@ -33,6 +36,17 @@ export function typeDefsFile(model) {
|
|
|
33
36
|
return { path: 'schema/typeDefs.graphql', content: header + print(document) + '\n', overwrite: true }
|
|
34
37
|
}
|
|
35
38
|
|
|
39
|
+
// `project: Project!` → `project: Project`: the ! keeps its meaning of required foreign key in the model only
|
|
40
|
+
function nullableObject(field, model) {
|
|
41
|
+
const type = field.type
|
|
42
|
+
if (type.kind !== Kind.NON_NULL_TYPE || type.type.kind !== Kind.NAMED_TYPE || !model.byName.has(type.type.name.value)) return field
|
|
43
|
+
return { ...field, type: type.type }
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function nullable(field) {
|
|
47
|
+
return field.type.kind === Kind.NON_NULL_TYPE ? { ...field, type: field.type.type } : field
|
|
48
|
+
}
|
|
49
|
+
|
|
36
50
|
function fieldNode(source) {
|
|
37
51
|
const field = parse(`type T { ${source} }`, { noLocation: true }).definitions[0].fields[0]
|
|
38
52
|
return field.kind === Kind.FIELD_DEFINITION ? field : undefined
|
package/src/generate.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
|
2
|
-
import { dirname, join } from 'node:path'
|
|
1
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
|
|
2
|
+
import { dirname, join, posix } from 'node:path'
|
|
3
3
|
import { readSchema } from './model.js'
|
|
4
4
|
import { classFiles } from './generate/classes.js'
|
|
5
5
|
import { clientFiles } from './generate/client.js'
|
|
@@ -9,24 +9,29 @@ import { operationsFile } from './generate/operations.js'
|
|
|
9
9
|
/**
|
|
10
10
|
* Generates the database layer of a project from its preTypeDefs (spec section 12).
|
|
11
11
|
* Generated files are rewritten; files written by hand (extended classes) are created only when missing.
|
|
12
|
+
* The generated classes of a type gone from the schema are removed, its extended class is named in a warning.
|
|
12
13
|
* @param {{schema: string | string[], dest: string}} options schema file(s), destination folder
|
|
13
|
-
* @returns {{written: string[], kept: string[], warnings: string[]}} paths relative to dest
|
|
14
|
+
* @returns {{written: string[], kept: string[], removed: string[], warnings: string[]}} paths relative to dest
|
|
14
15
|
*/
|
|
15
16
|
export function generate({ schema, dest }) {
|
|
16
17
|
const model = readSchemaFiles(schema)
|
|
17
|
-
|
|
18
|
+
const files = [...classFiles(model), typeDefsFile(model), operationsFile(model)]
|
|
19
|
+
const { removed, warnings } = removeOrphans(files, dest)
|
|
20
|
+
return { ...writeFiles(files, dest), removed, warnings: [...model.warnings, ...warnings] }
|
|
18
21
|
}
|
|
19
22
|
|
|
20
23
|
/**
|
|
21
24
|
* Generates the classes of a ramdb2-client application from the preTypeDefs of its server (spec section 12, D49):
|
|
22
|
-
* generated/<table>.js (rewritten), extended/<table>.js (created once) and index.js, in dest.
|
|
25
|
+
* generated/<table>.js (rewritten), extended/<table>.js (created once) and index.js, in dest. Orphans are handled
|
|
26
|
+
* as by generate.
|
|
23
27
|
* @param {{schema: string | string[], dest: string}} options schema file(s), destination folder
|
|
24
|
-
* @returns {{written: string[], kept: string[], warnings: string[]}} paths relative to dest
|
|
28
|
+
* @returns {{written: string[], kept: string[], removed: string[], warnings: string[]}} paths relative to dest
|
|
25
29
|
*/
|
|
26
30
|
export function generateClient({ schema, dest }) {
|
|
27
31
|
const model = readSchemaFiles(schema)
|
|
28
32
|
const { files, warnings } = clientFiles(model)
|
|
29
|
-
|
|
33
|
+
const orphans = removeOrphans(files, dest)
|
|
34
|
+
return { ...writeFiles(files, dest), removed: orphans.removed, warnings: [...model.warnings, ...warnings, ...orphans.warnings] }
|
|
30
35
|
}
|
|
31
36
|
|
|
32
37
|
function readSchemaFiles(schema) {
|
|
@@ -49,3 +54,36 @@ function writeFiles(files, dest) {
|
|
|
49
54
|
}
|
|
50
55
|
return { written, kept }
|
|
51
56
|
}
|
|
57
|
+
|
|
58
|
+
// The marker of a file written by ramdb2-cli: only such a file is ever removed
|
|
59
|
+
const GENERATED = '// Generated by ramdb2-cli'
|
|
60
|
+
|
|
61
|
+
// The classes of a type removed from the schema (D61): in each folder of generated classes, a generated file that
|
|
62
|
+
// this generation does not write is removed; in each folder of extended classes, a file without its generated
|
|
63
|
+
// class is only named in a warning, since it was written by hand.
|
|
64
|
+
function removeOrphans(files, dest) {
|
|
65
|
+
const removed = []
|
|
66
|
+
const warnings = []
|
|
67
|
+
const folders = new Map()
|
|
68
|
+
for (const file of files) {
|
|
69
|
+
const folder = posix.dirname(file.path)
|
|
70
|
+
if (!['generated', 'extended'].includes(posix.basename(folder))) continue
|
|
71
|
+
if (!folders.has(folder)) folders.set(folder, new Set())
|
|
72
|
+
folders.get(folder).add(posix.basename(file.path))
|
|
73
|
+
}
|
|
74
|
+
for (const [folder, names] of folders) {
|
|
75
|
+
const path = join(dest, folder)
|
|
76
|
+
if (!existsSync(path)) continue
|
|
77
|
+
for (const entry of readdirSync(path, { withFileTypes: true })) {
|
|
78
|
+
if (!entry.isFile() || !entry.name.endsWith('.js') || names.has(entry.name)) continue
|
|
79
|
+
const relative = posix.join(folder, entry.name)
|
|
80
|
+
if (posix.basename(folder) === 'extended') {
|
|
81
|
+
warnings.push(`${relative}: its type is no longer in the schema, remove it by hand if it is not used`)
|
|
82
|
+
} else if (readFileSync(join(path, entry.name), 'utf8').startsWith(GENERATED)) {
|
|
83
|
+
rmSync(join(path, entry.name))
|
|
84
|
+
removed.push(relative)
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return { removed, warnings }
|
|
89
|
+
}
|
package/src/index.js
CHANGED
|
@@ -9,5 +9,6 @@ export { operationNames } from './generate/operations.js'
|
|
|
9
9
|
export { readInfra, InfraError } from './infra/config.js'
|
|
10
10
|
export { buildInfra, serverFiles, certificates } from './infra/build.js'
|
|
11
11
|
export { deploy } from './infra/deploy.js'
|
|
12
|
+
export { down } from './infra/down.js'
|
|
12
13
|
export { keygen } from './infra/keygen.js'
|
|
13
14
|
export { listBackups, restore, fetch as fetchBackup } from './infra/backups.js'
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// ramdb2-cli infra down (D55): stops and removes the containers and the network of a server. The volumes (the
|
|
2
|
+
// databases), the images and the certificates stay: infra deploy starts the server again as it was.
|
|
3
|
+
import { check, runCommand, withServer } from './server.js'
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Stops one server. Its secrets are decrypted too: Compose needs them to read compose.yaml.
|
|
7
|
+
* @param {import('./config.js').Infra} infra
|
|
8
|
+
* @param {string} name the server
|
|
9
|
+
* @param {object} [options]
|
|
10
|
+
* @param {import('./server.js').Runner} [options.run]
|
|
11
|
+
* @param {(line: string) => void} [options.print]
|
|
12
|
+
*/
|
|
13
|
+
export async function down(infra, name, { run = runCommand, print = console.log } = {}) {
|
|
14
|
+
return withServer(infra, name, run, async ({ server, compose, env }) => {
|
|
15
|
+
print(`${name}: docker compose down on ${server.host} (the volumes stay)`)
|
|
16
|
+
await check(run('docker', [...compose, 'down', '--remove-orphans'], { env }), 'docker compose down')
|
|
17
|
+
print(`${name}: stopped`)
|
|
18
|
+
})
|
|
19
|
+
}
|
package/src/model.js
CHANGED
|
@@ -64,6 +64,8 @@ export class SchemaError extends Error {
|
|
|
64
64
|
* @property {string | undefined} description
|
|
65
65
|
* @property {boolean} scalar scalar, enum, custom scalar or a list of them (a type of another layer is a scalar)
|
|
66
66
|
* @property {string[]} requiredArgs arguments without a default value
|
|
67
|
+
* @property {boolean} getter @transient(getter: true): a getter of the class gives its value, a query filters and
|
|
68
|
+
* sorts on it (D62)
|
|
67
69
|
*
|
|
68
70
|
* @typedef {object} Index
|
|
69
71
|
* @property {string} name
|
|
@@ -82,6 +84,10 @@ export class SchemaError extends Error {
|
|
|
82
84
|
* @property {Computed[]} computed
|
|
83
85
|
* @property {Transient[]} transient fields resolved by the project on the server
|
|
84
86
|
* @property {Index[]} indexes declared with @index (the inverse indexes of the foreign keys are automatic)
|
|
87
|
+
* @property {string[]} restricted @restricted fields (D58): stored fields, relations with their foreign key,
|
|
88
|
+
* computed and @transient fields
|
|
89
|
+
* @property {Record<string, 'date' | 'datetime'>} dates the Int fields of @date and @datetime (D64): stored, computed
|
|
90
|
+
* or @transient
|
|
85
91
|
*
|
|
86
92
|
* @typedef {object} Model
|
|
87
93
|
* @property {Type[]} types
|
|
@@ -136,6 +142,8 @@ export function readSchema(source) {
|
|
|
136
142
|
computed: [],
|
|
137
143
|
transient: [],
|
|
138
144
|
indexes: [],
|
|
145
|
+
restricted: [],
|
|
146
|
+
dates: {},
|
|
139
147
|
_gql: gqlType,
|
|
140
148
|
}
|
|
141
149
|
types.push(type)
|
|
@@ -155,7 +163,8 @@ export function readSchema(source) {
|
|
|
155
163
|
const list = isListType(isNonNullType(gqlField.type) ? gqlField.type.ofType : gqlField.type)
|
|
156
164
|
const description = gqlField.description ?? undefined
|
|
157
165
|
const computed = values('computed', node)
|
|
158
|
-
const
|
|
166
|
+
const transientArgs = values('transient', node)
|
|
167
|
+
const transient = transientArgs !== undefined
|
|
159
168
|
const pattern = values('pattern', node)
|
|
160
169
|
const onDelete = values('onDelete', node)
|
|
161
170
|
const field = values('field', node)
|
|
@@ -163,6 +172,22 @@ export function readSchema(source) {
|
|
|
163
172
|
if (isPrivate && (computed !== undefined || transient || name === 'id' || isObjectType(named) || list)) {
|
|
164
173
|
errors.push(`${at(name)}: @private only goes on a stored scalar field`)
|
|
165
174
|
}
|
|
175
|
+
// A date is an Int of Unix seconds, whatever the field: stored, computed or @transient (D64)
|
|
176
|
+
const dateKinds = ['date', 'datetime'].filter(kind => values(kind, node) !== undefined)
|
|
177
|
+
if (dateKinds.length > 1) errors.push(`${at(name)}: @date and @datetime exclude each other`)
|
|
178
|
+
else if (dateKinds.length === 1) {
|
|
179
|
+
if (named.name !== 'Int' || list || name === 'id') errors.push(`${at(name)}: @${dateKinds[0]} only goes on an Int field (Unix seconds), not on the id`)
|
|
180
|
+
else type.dates[name] = dateKinds[0]
|
|
181
|
+
}
|
|
182
|
+
if (values('restricted', node) !== undefined) {
|
|
183
|
+
if (name === 'id') errors.push(`${at(name)}: the id cannot be @restricted`)
|
|
184
|
+
else if (isPrivate) errors.push(`${at(name)}: @private and @restricted exclude each other`)
|
|
185
|
+
else if (list && isPersistent(named)) errors.push(`${at(name)}: a list relation cannot be @restricted: restrict the object relation of the other type`)
|
|
186
|
+
else {
|
|
187
|
+
type.restricted.push(name)
|
|
188
|
+
if (isPersistent(named) && computed === undefined && !transient) type.restricted.push('id' + upperFirst(name))
|
|
189
|
+
}
|
|
190
|
+
}
|
|
166
191
|
|
|
167
192
|
if (computed !== undefined && transient) errors.push(`${at(name)}: @computed and @transient exclude each other`)
|
|
168
193
|
if (computed !== undefined) {
|
|
@@ -177,7 +202,12 @@ export function readSchema(source) {
|
|
|
177
202
|
description,
|
|
178
203
|
scalar: isLeafType(named),
|
|
179
204
|
requiredArgs: gqlField.args.filter(arg => isNonNullType(arg.type) && arg.defaultValue === undefined).map(arg => arg.name),
|
|
205
|
+
getter: transientArgs.getter === true,
|
|
180
206
|
})
|
|
207
|
+
// A getter reads the object alone: one scalar value, no argument (filtered and sorted by the engine)
|
|
208
|
+
if (transientArgs.getter === true && (!isLeafType(named) || list || gqlField.args.length > 0)) {
|
|
209
|
+
errors.push(`${at(name)}: @transient(getter: true) only goes on a scalar field without arguments`)
|
|
210
|
+
}
|
|
181
211
|
continue
|
|
182
212
|
}
|
|
183
213
|
if (name === 'id') {
|
|
@@ -236,6 +266,7 @@ export function readSchema(source) {
|
|
|
236
266
|
checkRelations(types, byName, errors)
|
|
237
267
|
for (const type of types) readIndexes(type, values, errors)
|
|
238
268
|
for (const type of types) checkComputed(type, byName, errors)
|
|
269
|
+
for (const type of types) checkRestrictedDependencies(type, byName, errors)
|
|
239
270
|
|
|
240
271
|
if (errors.length > 0) throw new SchemaError(errors)
|
|
241
272
|
for (const type of types) delete type._gql
|
|
@@ -358,6 +389,25 @@ function checkComputed(type, byName, errors) {
|
|
|
358
389
|
for (const name of local.keys()) visit(name, [])
|
|
359
390
|
}
|
|
360
391
|
|
|
392
|
+
// A computed field that depends on a @restricted field would reveal it: it must be @restricted too (D58).
|
|
393
|
+
// A path is restricted when it ends on a restricted field, goes through a restricted relation, or goes through a
|
|
394
|
+
// list relation whose foreign key is restricted (the list tells which objects point here).
|
|
395
|
+
function checkRestrictedDependencies(type, byName, errors) {
|
|
396
|
+
for (const computed of type.computed) {
|
|
397
|
+
if (type.restricted.includes(computed.name)) continue
|
|
398
|
+
for (const path of computed.depends) {
|
|
399
|
+
const { steps, end, last, error } = resolvePath(type, path.split('.'), byName)
|
|
400
|
+
if (error !== undefined) continue
|
|
401
|
+
const through = steps.some(step => step.kind === 'parent'
|
|
402
|
+
? step.from.restricted.includes(step.relation.name)
|
|
403
|
+
: step.to.restricted.includes(step.relation.fk))
|
|
404
|
+
if (through || (last !== undefined && end.restricted.includes(last))) {
|
|
405
|
+
errors.push(`${type.name}.${computed.name}: depends on "${path}", which is @restricted: add @restricted to ${computed.name}`)
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
|
|
361
411
|
/**
|
|
362
412
|
* Follows a dependency path from a type.
|
|
363
413
|
* @returns {{steps?: {relation: Parent | Child, kind: 'parent' | 'child', from: Type, to: Type}[], end?: Type, last?: string, error?: string}}
|
package/src/new.js
CHANGED