@yrest/cli 0.9.0 → 0.10.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 +103 -29
- package/dist/cli/index.js +450 -21
- package/dist/cli/index.mjs +447 -18
- package/dist/index.d.mts +44 -0
- package/dist/index.d.ts +44 -0
- package/dist/index.js +441 -21
- package/dist/index.mjs +438 -18
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
[](https://github.com/aggiovato/yRest/actions)
|
|
11
11
|
[](https://www.npmjs.com/package/@yrest/cli)
|
|
12
12
|
[](https://www.typescriptlang.org/)
|
|
13
|
-
[](https://socket.dev/npm/package/@yrest/cli)
|
|
14
14
|
|
|
15
15
|
YAML-powered json-server alternative. Zero-config REST API mock server with full CRUD, relations, filters and snapshots from a `db.yml` file.
|
|
16
16
|
|
|
@@ -48,30 +48,32 @@ DELETE /users/1 → 200 OK
|
|
|
48
48
|
|
|
49
49
|
A YAML-first alternative to json-server for frontend development.
|
|
50
50
|
|
|
51
|
-
| Feature
|
|
52
|
-
|
|
|
53
|
-
| YAML database
|
|
54
|
-
| Zero config
|
|
55
|
-
| Full CRUD
|
|
56
|
-
| Field operators (`_gte`, `_like`, `_regex`…)
|
|
57
|
-
| Full-text search
|
|
58
|
-
| Relations: many2one, one2one, many2many
|
|
59
|
-
| Nested routes + bidirectional many2many
|
|
60
|
-
| Auto-embedding (`nested: true`)
|
|
61
|
-
| Field projection (`_fields`)
|
|
62
|
-
| Pageable mode (envelope response)
|
|
63
|
-
| Custom static routes (`_routes`)
|
|
64
|
-
| Template variables in responses
|
|
65
|
-
| Handler functions (JS logic)
|
|
66
|
-
| Conditional scenarios (`scenarios:`)
|
|
67
|
-
| Snapshot endpoints
|
|
68
|
-
| Config file
|
|
69
|
-
| API overview page (`/_about`)
|
|
70
|
-
| Watch mode
|
|
71
|
-
| Readonly mode
|
|
72
|
-
| Atomic writes
|
|
73
|
-
| TypeScript types
|
|
74
|
-
| Programmatic API for test frameworks
|
|
51
|
+
| Feature | yrest | json-server |
|
|
52
|
+
| --------------------------------------------------- | :---: | :---------: |
|
|
53
|
+
| YAML database | ✅ | ❌ |
|
|
54
|
+
| Zero config | ✅ | ✅ |
|
|
55
|
+
| Full CRUD | ✅ | ✅ |
|
|
56
|
+
| Field operators (`_gte`, `_like`, `_regex`…) | ✅ | ⚠️ |
|
|
57
|
+
| Full-text search | ✅ | ✅ |
|
|
58
|
+
| Relations: many2one, one2one, many2many | ✅ | ⚠️ |
|
|
59
|
+
| Nested routes + bidirectional many2many | ✅ | ✅ |
|
|
60
|
+
| Auto-embedding (`nested: true`) | ✅ | ❌ |
|
|
61
|
+
| Field projection (`_fields`) | ✅ | ❌ |
|
|
62
|
+
| Pageable mode (envelope response) | ✅ | ❌ |
|
|
63
|
+
| Custom static routes (`_routes`) | ✅ | ❌ |
|
|
64
|
+
| Template variables in responses | ✅ | ❌ |
|
|
65
|
+
| Handler functions (JS logic) | ✅ | ❌ |
|
|
66
|
+
| Conditional scenarios (`scenarios:`) | ✅ | ❌ |
|
|
67
|
+
| Snapshot endpoints | ✅ | ❌ |
|
|
68
|
+
| Config file | ✅ | ⚠️ |
|
|
69
|
+
| API overview page (`/_about`) | ✅ | ❌ |
|
|
70
|
+
| Watch mode | ✅ | ✅ |
|
|
71
|
+
| Readonly mode | ✅ | ❌ |
|
|
72
|
+
| Atomic writes | ✅ | ✅ |
|
|
73
|
+
| TypeScript types | ✅ | ❌ |
|
|
74
|
+
| Programmatic API for test frameworks | ✅ | ❌ |
|
|
75
|
+
| OpenAPI 3.0 spec (`GET /_openapi`, `yrest openapi`) | ✅ | ❌ |
|
|
76
|
+
| Field annotations (`_schema`) | ✅ | ❌ |
|
|
75
77
|
|
|
76
78
|
---
|
|
77
79
|
|
|
@@ -140,6 +142,31 @@ npx @yrest/cli init --sample relational --file api.yml
|
|
|
140
142
|
|
|
141
143
|
---
|
|
142
144
|
|
|
145
|
+
### `openapi`
|
|
146
|
+
|
|
147
|
+
Generates an OpenAPI 3.0.3 spec from a `db.yml` file without starting a server.
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npx @yrest/cli openapi db.yml # writes openapi.yaml
|
|
151
|
+
npx @yrest/cli openapi db.yml --format json # writes openapi.json
|
|
152
|
+
npx @yrest/cli openapi db.yml --stdout # prints to stdout
|
|
153
|
+
npx @yrest/cli openapi db.yml --output api-spec.yaml # custom output path
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
| Flag | Default | Description |
|
|
157
|
+
| ----------------- | ----------- | ----------------------------------------------------------- |
|
|
158
|
+
| `--output <file>` | _(auto)_ | Output file path (default: `openapi.yaml` / `openapi.json`) |
|
|
159
|
+
| `--format <fmt>` | `yaml` | Output format: `yaml` or `json` |
|
|
160
|
+
| `--stdout` | `false` | Print to stdout instead of writing a file |
|
|
161
|
+
| `--base <base>` | _(none)_ | Base path prefix applied to all routes |
|
|
162
|
+
| `--port <port>` | `3070` | Server port shown in the `servers` block |
|
|
163
|
+
| `--host <host>` | `localhost` | Server host shown in the `servers` block |
|
|
164
|
+
| `--title <title>` | `yRest API` | API title for the `info` block |
|
|
165
|
+
|
|
166
|
+
The spec is also available live at `GET /_openapi` (YAML) and `GET /_openapi.json` (JSON) while the server is running — no extra flag or config needed.
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
143
170
|
### `serve`
|
|
144
171
|
|
|
145
172
|
Starts the mock server.
|
|
@@ -215,6 +242,46 @@ Each top-level key becomes a resource with full CRUD endpoints.
|
|
|
215
242
|
|
|
216
243
|
---
|
|
217
244
|
|
|
245
|
+
## Field annotations (`_schema`)
|
|
246
|
+
|
|
247
|
+
Add a `_schema` block to `db.yml` to declare field-level metadata per collection. Used by the OpenAPI generator to produce accurate schemas — has no effect on runtime CRUD behavior.
|
|
248
|
+
|
|
249
|
+
```yaml
|
|
250
|
+
_schema:
|
|
251
|
+
users:
|
|
252
|
+
name: required # shorthand: marks field as required
|
|
253
|
+
email:
|
|
254
|
+
required: true
|
|
255
|
+
format: email
|
|
256
|
+
age:
|
|
257
|
+
type: integer
|
|
258
|
+
role:
|
|
259
|
+
type: string
|
|
260
|
+
enum: [admin, editor, viewer]
|
|
261
|
+
default: viewer
|
|
262
|
+
description: User role
|
|
263
|
+
|
|
264
|
+
users:
|
|
265
|
+
- id: 1
|
|
266
|
+
name: Ana
|
|
267
|
+
email: ana@test.com
|
|
268
|
+
age: 28
|
|
269
|
+
role: admin
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
| Key | Type | Description |
|
|
273
|
+
| ------------- | --------- | ----------------------------------------------------------------------------------------- |
|
|
274
|
+
| `required` | `boolean` | Marks the field as required in the OpenAPI schema |
|
|
275
|
+
| `type` | `string` | Overrides the inferred type (`string`, `integer`, `number`, `boolean`, `array`, `object`) |
|
|
276
|
+
| `format` | `string` | OpenAPI format hint (`email`, `date`, `date-time`, `uuid`, `uri`, …) |
|
|
277
|
+
| `enum` | `array` | Restricts the field to a fixed set of values |
|
|
278
|
+
| `description` | `string` | Field description included in the OpenAPI schema |
|
|
279
|
+
| `default` | `any` | Default value shown in the OpenAPI schema |
|
|
280
|
+
|
|
281
|
+
Fields not listed in `_schema` are inferred from the first items in the collection and treated as optional. `_schema` itself is excluded from the generated REST resources.
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
218
285
|
## Generated endpoints
|
|
219
286
|
|
|
220
287
|
For each resource in `db.yml`:
|
|
@@ -815,15 +882,22 @@ Useful for test suites that need a clean reset between runs or demos that need a
|
|
|
815
882
|
|
|
816
883
|
---
|
|
817
884
|
|
|
818
|
-
##
|
|
885
|
+
## Meta endpoints
|
|
886
|
+
|
|
887
|
+
Every running server exposes the following meta endpoints without any extra configuration:
|
|
819
888
|
|
|
820
|
-
|
|
889
|
+
| Endpoint | Description |
|
|
890
|
+
| -------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
891
|
+
| `GET /_about` | Self-contained HTML page listing all endpoints, modes, query params and ready-to-run `curl` examples |
|
|
892
|
+
| `GET /_openapi` | OpenAPI 3.0.3 spec in YAML format — regenerated on every request |
|
|
893
|
+
| `GET /_openapi.json` | OpenAPI 3.0.3 spec in JSON format |
|
|
821
894
|
|
|
822
895
|
```bash
|
|
823
896
|
open http://localhost:3070/_about
|
|
897
|
+
curl http://localhost:3070/_openapi.json | npx swagger-ui-watcher -
|
|
824
898
|
```
|
|
825
899
|
|
|
826
|
-
|
|
900
|
+
Both `/_about` and the OpenAPI spec reflect the live storage state and update automatically in watch mode.
|
|
827
901
|
|
|
828
902
|
---
|
|
829
903
|
|
|
@@ -1065,7 +1139,7 @@ const server = createYrestServer({
|
|
|
1065
1139
|
| Visual panel (`/_panel`) | 🔜 |
|
|
1066
1140
|
| Programmatic API for Vitest / Playwright | ✅ |
|
|
1067
1141
|
| Docker image | 🔜 |
|
|
1068
|
-
| OpenAPI export (`yrest openapi db.yml`) |
|
|
1142
|
+
| OpenAPI export (`yrest openapi db.yml`) | ✅ |
|
|
1069
1143
|
| VS Code extension with YAML snippets | 🔜 |
|
|
1070
1144
|
| Request validation with JSON Schema | 🔜 |
|
|
1071
1145
|
| Conditional scenarios (`scenarios:`, `otherwise:`) | ✅ |
|