@spinajs/orm-api 2.0.491 → 2.0.495
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 +87 -87
- package/lib/tsconfig.cjs.tsbuildinfo +1 -1
- package/lib/tsconfig.mjs.tsbuildinfo +1 -1
- package/package.json +71 -69
package/README.md
CHANGED
|
@@ -1,87 +1,87 @@
|
|
|
1
|
-
# `@spinajs/orm-api`
|
|
2
|
-
|
|
3
|
-
Building blocks for CRUD controllers over [`@spinajs/orm`](../orm) models: a route argument that
|
|
4
|
-
resolves a model *type* from a URL segment, query-argument DTOs for filtering / including /
|
|
5
|
-
paging, a pluggable collection transformer, and a policy that validates the requested model.
|
|
6
|
-
|
|
7
|
-
## Read this first
|
|
8
|
-
|
|
9
|
-
The name suggests a ready-made generic CRUD API. It is **not** that today.
|
|
10
|
-
|
|
11
|
-
| Component | State |
|
|
12
|
-
| --- | --- |
|
|
13
|
-
| `JsonApi` controller (`src/controllers/JsonApi.ts`) | **Entirely commented out.** This package registers no routes. |
|
|
14
|
-
| `Crud` base controller | Ships and works. |
|
|
15
|
-
| `ModelType()` + `FindModelType` | Ship and work. |
|
|
16
|
-
| `QueryArgs`, `QueryFilter`, `QueryIncludes` | Ship and work. |
|
|
17
|
-
| `PlainJsonCollectionTransformer` | Ships; is the registered default. |
|
|
18
|
-
| `FromModel` / `AsModel` | Ship, but are an older, less capable copy of [`@spinajs/orm-http`](../orm-http)'s. |
|
|
19
|
-
| `RepositoryMiddleware` | Defined but not exported, and nothing invokes it. |
|
|
20
|
-
| `src/index.ts` | Re-exports only the four route-argument symbols; everything else is unreachable by specifier. |
|
|
21
|
-
| Bundled config `system.dirs.controllers` | Points at a directory in `@spinajs/orm-http` that does not exist. |
|
|
22
|
-
| Bundled config transformer | Names `JsonApiCollectionTransformer`, which is registered nowhere. |
|
|
23
|
-
| Test suite | Does not run — fails in `before all` with `No __file_provider_instance__ registered`, and asserts against `collection/*` routes no controller defines. |
|
|
24
|
-
|
|
25
|
-
**Use this package for its pieces and write the controller yourself.** If you only need route
|
|
26
|
-
arguments and filtering, prefer [`@spinajs/orm-http`](../orm-http) — it is the maintained one.
|
|
27
|
-
|
|
28
|
-
## Usage
|
|
29
|
-
|
|
30
|
-
```ts
|
|
31
|
-
import { BaseController, BasePath, Get, Ok, Policy, Query } from '@spinajs/http';
|
|
32
|
-
import { IModelStatic, ModelBase } from '@spinajs/orm';
|
|
33
|
-
import { Autoinject } from '@spinajs/di';
|
|
34
|
-
// Reachable only by relative path — see the docs.
|
|
35
|
-
import { Crud, CollectionApiTransformer, _assertSingleColumnKey } from '../../src/interfaces.js';
|
|
36
|
-
import { ModelType } from '../../src/route-args/ModelType.js';
|
|
37
|
-
import { FindModelType } from '../../src/policies/FindModelType.js';
|
|
38
|
-
import { QueryArgs } from '../../src/dto/QueryArgs.js';
|
|
39
|
-
|
|
40
|
-
@BasePath('collection')
|
|
41
|
-
@Policy(FindModelType)
|
|
42
|
-
export class Collection extends Crud {
|
|
43
|
-
@Autoinject(CollectionApiTransformer)
|
|
44
|
-
protected Transformer: CollectionApiTransformer;
|
|
45
|
-
|
|
46
|
-
/** GET /collection/:model */
|
|
47
|
-
@Get(':model')
|
|
48
|
-
public async list(@ModelType() model: IModelStatic, @Query() args: QueryArgs) {
|
|
49
|
-
const perPage = args?.perPage && args.perPage > 0 ? Math.min(args.perPage, 100) : 25;
|
|
50
|
-
const page = args?.page && args.page > 0 ? args.page : 0;
|
|
51
|
-
|
|
52
|
-
const query = model.query().select('*');
|
|
53
|
-
const totalCount = await (query.clone() as any).selectCount();
|
|
54
|
-
const data = await query.take(perPage).skip(page * perPage);
|
|
55
|
-
|
|
56
|
-
return new Ok(this.Transformer.transform(data as ModelBase[], { model: model as any, totalCount, currentPage: page, perPage }));
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
`FindModelType` validates the `:model` segment; `ModelType()` resolves it to the model class,
|
|
62
|
-
without a guard of its own — so always pair the two.
|
|
63
|
-
|
|
64
|
-
## Documentation
|
|
65
|
-
|
|
66
|
-
Full documentation lives in **[docs/](docs/)**.
|
|
67
|
-
|
|
68
|
-
| | Page |
|
|
69
|
-
| --- | --- |
|
|
70
|
-
| 01 | [Overview](docs/01-overview.md) |
|
|
71
|
-
| 02 | [Configuration](docs/02-configuration.md) |
|
|
72
|
-
| 03 | [Building a CRUD controller](docs/03-building-a-crud-controller.md) |
|
|
73
|
-
| 04 | [Query arguments](docs/04-query-args.md) |
|
|
74
|
-
| 05 | [Transformers and policies](docs/05-transformers-and-policies.md) |
|
|
75
|
-
|
|
76
|
-
## Security note
|
|
77
|
-
|
|
78
|
-
A generic `/:model` controller exposes **every registered model**, including internal ones.
|
|
79
|
-
`FindModelType` answers "is this a real model" and authorises nothing. Put an authorisation
|
|
80
|
-
policy in front of it, or keep an allow-list of exposed model names.
|
|
81
|
-
|
|
82
|
-
## Development
|
|
83
|
-
|
|
84
|
-
```bash
|
|
85
|
-
npm run build
|
|
86
|
-
npm run docs:check # from the repo root
|
|
87
|
-
```
|
|
1
|
+
# `@spinajs/orm-api`
|
|
2
|
+
|
|
3
|
+
Building blocks for CRUD controllers over [`@spinajs/orm`](../orm) models: a route argument that
|
|
4
|
+
resolves a model *type* from a URL segment, query-argument DTOs for filtering / including /
|
|
5
|
+
paging, a pluggable collection transformer, and a policy that validates the requested model.
|
|
6
|
+
|
|
7
|
+
## Read this first
|
|
8
|
+
|
|
9
|
+
The name suggests a ready-made generic CRUD API. It is **not** that today.
|
|
10
|
+
|
|
11
|
+
| Component | State |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `JsonApi` controller (`src/controllers/JsonApi.ts`) | **Entirely commented out.** This package registers no routes. |
|
|
14
|
+
| `Crud` base controller | Ships and works. |
|
|
15
|
+
| `ModelType()` + `FindModelType` | Ship and work. |
|
|
16
|
+
| `QueryArgs`, `QueryFilter`, `QueryIncludes` | Ship and work. |
|
|
17
|
+
| `PlainJsonCollectionTransformer` | Ships; is the registered default. |
|
|
18
|
+
| `FromModel` / `AsModel` | Ship, but are an older, less capable copy of [`@spinajs/orm-http`](../orm-http)'s. |
|
|
19
|
+
| `RepositoryMiddleware` | Defined but not exported, and nothing invokes it. |
|
|
20
|
+
| `src/index.ts` | Re-exports only the four route-argument symbols; everything else is unreachable by specifier. |
|
|
21
|
+
| Bundled config `system.dirs.controllers` | Points at a directory in `@spinajs/orm-http` that does not exist. |
|
|
22
|
+
| Bundled config transformer | Names `JsonApiCollectionTransformer`, which is registered nowhere. |
|
|
23
|
+
| Test suite | Does not run — fails in `before all` with `No __file_provider_instance__ registered`, and asserts against `collection/*` routes no controller defines. |
|
|
24
|
+
|
|
25
|
+
**Use this package for its pieces and write the controller yourself.** If you only need route
|
|
26
|
+
arguments and filtering, prefer [`@spinajs/orm-http`](../orm-http) — it is the maintained one.
|
|
27
|
+
|
|
28
|
+
## Usage
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { BaseController, BasePath, Get, Ok, Policy, Query } from '@spinajs/http';
|
|
32
|
+
import { IModelStatic, ModelBase } from '@spinajs/orm';
|
|
33
|
+
import { Autoinject } from '@spinajs/di';
|
|
34
|
+
// Reachable only by relative path — see the docs.
|
|
35
|
+
import { Crud, CollectionApiTransformer, _assertSingleColumnKey } from '../../src/interfaces.js';
|
|
36
|
+
import { ModelType } from '../../src/route-args/ModelType.js';
|
|
37
|
+
import { FindModelType } from '../../src/policies/FindModelType.js';
|
|
38
|
+
import { QueryArgs } from '../../src/dto/QueryArgs.js';
|
|
39
|
+
|
|
40
|
+
@BasePath('collection')
|
|
41
|
+
@Policy(FindModelType)
|
|
42
|
+
export class Collection extends Crud {
|
|
43
|
+
@Autoinject(CollectionApiTransformer)
|
|
44
|
+
protected Transformer: CollectionApiTransformer;
|
|
45
|
+
|
|
46
|
+
/** GET /collection/:model */
|
|
47
|
+
@Get(':model')
|
|
48
|
+
public async list(@ModelType() model: IModelStatic, @Query() args: QueryArgs) {
|
|
49
|
+
const perPage = args?.perPage && args.perPage > 0 ? Math.min(args.perPage, 100) : 25;
|
|
50
|
+
const page = args?.page && args.page > 0 ? args.page : 0;
|
|
51
|
+
|
|
52
|
+
const query = model.query().select('*');
|
|
53
|
+
const totalCount = await (query.clone() as any).selectCount();
|
|
54
|
+
const data = await query.take(perPage).skip(page * perPage);
|
|
55
|
+
|
|
56
|
+
return new Ok(this.Transformer.transform(data as ModelBase[], { model: model as any, totalCount, currentPage: page, perPage }));
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`FindModelType` validates the `:model` segment; `ModelType()` resolves it to the model class,
|
|
62
|
+
without a guard of its own — so always pair the two.
|
|
63
|
+
|
|
64
|
+
## Documentation
|
|
65
|
+
|
|
66
|
+
Full documentation lives in **[docs/](docs/)**.
|
|
67
|
+
|
|
68
|
+
| | Page |
|
|
69
|
+
| --- | --- |
|
|
70
|
+
| 01 | [Overview](docs/01-overview.md) |
|
|
71
|
+
| 02 | [Configuration](docs/02-configuration.md) |
|
|
72
|
+
| 03 | [Building a CRUD controller](docs/03-building-a-crud-controller.md) |
|
|
73
|
+
| 04 | [Query arguments](docs/04-query-args.md) |
|
|
74
|
+
| 05 | [Transformers and policies](docs/05-transformers-and-policies.md) |
|
|
75
|
+
|
|
76
|
+
## Security note
|
|
77
|
+
|
|
78
|
+
A generic `/:model` controller exposes **every registered model**, including internal ones.
|
|
79
|
+
`FindModelType` answers "is this a real model" and authorises nothing. Put an authorisation
|
|
80
|
+
policy in front of it, or keep an allow-list of exposed model names.
|
|
81
|
+
|
|
82
|
+
## Development
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npm run build
|
|
86
|
+
npm run docs:check # from the repo root
|
|
87
|
+
```
|