@opra/common 1.28.3 → 1.28.5
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/LICENSE +1 -1
- package/README.md +86 -4
- package/browser.js +3 -3
- package/document/data-type/complex-type-base.js +6 -2
- package/document/data-type/data-type.d.ts +1 -0
- package/document/decorators/http-operation-entity-update-many.decorator.js +1 -0
- package/document/decorators/http-operation-entity-update.decorator.js +1 -0
- package/document/decorators/http-operation-entity.decorator.d.ts +2 -0
- package/document/factory/http-api.factory.js +1 -0
- package/document/http/http-operation.d.ts +3 -2
- package/document/http/http-request-body.d.ts +3 -0
- package/document/http/http-request-body.js +2 -0
- package/package.json +3 -2
- package/schema/http/http-request-body.interface.d.ts +4 -0
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,19 +1,101 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<a href="https://oprajs.com">
|
|
4
|
+
<img src="https://oprajs.com/img/opra-header-block.webp" width="880" alt="OPRA — Open Platform for Rich APIs" />
|
|
5
|
+
</a>
|
|
6
|
+
|
|
1
7
|
# @opra/common
|
|
2
8
|
|
|
9
|
+
Shared foundation of the OPRA framework — schema model, decorators, type system, and filter DSL
|
|
10
|
+
|
|
3
11
|
[![NPM Version][npm-image]][npm-url]
|
|
4
12
|
[![NPM Downloads][downloads-image]][downloads-url]
|
|
5
13
|
[![CI Tests][ci-test-image]][ci-test-url]
|
|
6
14
|
[![Test Coverage][coveralls-image]][coveralls-url]
|
|
7
15
|
|
|
16
|
+
[🌐 Documentation](https://oprajs.com) · [🚀 Getting Started](https://oprajs.com/docs/introduction) · [📦 Packages](https://github.com/panates/opra#packages) · [💬 Issues](https://github.com/panates/opra/issues)
|
|
17
|
+
|
|
18
|
+
</div>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
Shared foundation package of the [OPRA](https://oprajs.com) framework. Provides the API document model, schema types, decorators, exception hierarchy, filter DSL, and utilities used by all OPRA adapters and services.
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- **API Document Model** — `ApiDocument` with `HttpApi`, `MQApi`, and `WSApi` transport layers in a single schema
|
|
27
|
+
- **Rich Type System** — Simple, Complex, Array, Enum, Union, and a full set of utility types (`PartialType`, `PickType`, `OmitType`, `MixinType`, …)
|
|
28
|
+
- **Decorator-Driven API** — `@HttpController`, `@HttpOperation`, `@MQOperation`, `@WSOperation` and parameter/response decorators
|
|
29
|
+
- **Filter DSL** — ANTLR4-based query language (`OpraFilter.parse()`) for flexible server-side filtering
|
|
30
|
+
- **Exception Hierarchy** — `OpraException` and `OpraHttpError` subclasses (`NotFoundError`, `ForbiddenError`, …) with severity levels
|
|
31
|
+
- **`ResponsiveMap`** — Case-insensitive ordered Map with well-known key support
|
|
32
|
+
- **i18n Support** — Built-in internationalization with a `translate()` helper and lazy-loaded resource bundles
|
|
33
|
+
- **HTTP & MIME Constants** — `HttpStatusCodes`, `HttpHeaderCodes`, `MimeTypes` enumerations
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install @opra/common
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Usage
|
|
42
|
+
|
|
43
|
+
### Define Models
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { ApiField, ComplexType } from '@opra/common';
|
|
8
47
|
|
|
9
|
-
|
|
10
|
-
|
|
48
|
+
@ComplexType({ description: 'Application user' })
|
|
49
|
+
export class User {
|
|
50
|
+
@ApiField({ type: 'integer' })
|
|
51
|
+
declare id: number;
|
|
52
|
+
|
|
53
|
+
@ApiField()
|
|
54
|
+
declare name: string;
|
|
55
|
+
|
|
56
|
+
@ApiField()
|
|
57
|
+
declare email: string;
|
|
58
|
+
|
|
59
|
+
@ApiField({ type: 'boolean' })
|
|
60
|
+
declare active: boolean;
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Define an HTTP API with decorators
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
import { HttpController, HttpOperation } from '@opra/common';
|
|
68
|
+
|
|
69
|
+
@HttpController({ path: 'users' })
|
|
70
|
+
export class UsersController {
|
|
71
|
+
@HttpOperation.Entity.FindMany({ type: User })
|
|
72
|
+
async findMany() { }
|
|
73
|
+
|
|
74
|
+
@HttpOperation.Entity.GetOne({ type: User })
|
|
75
|
+
@HttpOperation.PathParam('id', 'integer')
|
|
76
|
+
async getOne(id: number) { }
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Build an API document
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { ApiDocumentFactory } from '@opra/common';
|
|
84
|
+
|
|
85
|
+
const document = await ApiDocumentFactory.createDocument({
|
|
86
|
+
spec: '1.0',
|
|
87
|
+
info: { title: 'My API', version: '1.0.0' },
|
|
88
|
+
types: [User],
|
|
89
|
+
api: { transport: 'http', controllers: [UsersController] },
|
|
90
|
+
});
|
|
91
|
+
```
|
|
11
92
|
|
|
12
93
|
## Node Compatibility
|
|
13
|
-
- node >= 20.x
|
|
14
94
|
|
|
95
|
+
- node >= 20.x
|
|
15
96
|
|
|
16
97
|
## License
|
|
98
|
+
|
|
17
99
|
Available under [MIT](LICENSE) license.
|
|
18
100
|
|
|
19
101
|
[npm-image]: https://img.shields.io/npm/v/@opra/common
|
|
@@ -22,5 +104,5 @@ Available under [MIT](LICENSE) license.
|
|
|
22
104
|
[downloads-url]: https://npmjs.org/package/@opra/common
|
|
23
105
|
[ci-test-image]: https://github.com/panates/opra/actions/workflows/test.yml/badge.svg
|
|
24
106
|
[ci-test-url]: https://github.com/panates/opra/actions/workflows/test.yml
|
|
25
|
-
[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=
|
|
107
|
+
[coveralls-image]: https://coveralls.io/repos/github/panates/opra/badge.svg?branch=dev
|
|
26
108
|
[coveralls-url]: https://coveralls.io/github/panates/opra?branch=main
|