@treatwell/moleculer-essentials 1.0.2-beta.4 → 1.1.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 +162 -0
- package/dist/index.cjs +47 -1
- package/dist/index.mjs +47 -1
- package/package.json +8 -6
package/README.md
CHANGED
|
@@ -1 +1,163 @@
|
|
|
1
1
|
# moleculer-essentials
|
|
2
|
+
|
|
3
|
+
[](https://treatwell.com/tech)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@treatwell/moleculer-essentials)
|
|
6
|
+
|
|
7
|
+
<!-- TOC -->
|
|
8
|
+
|
|
9
|
+
- [Purpose](#purpose)
|
|
10
|
+
- [Features](#features)
|
|
11
|
+
- [Installation](#installation)
|
|
12
|
+
- [Companion Packages](#companion-packages)
|
|
13
|
+
- [Usage](#usage)
|
|
14
|
+
- [Basic Example](#basic-example)
|
|
15
|
+
- [Mixins](#mixins)
|
|
16
|
+
- [License](#license)
|
|
17
|
+
<!-- TOC -->
|
|
18
|
+
|
|
19
|
+
## Purpose
|
|
20
|
+
|
|
21
|
+
`@treatwell/moleculer-essentials` is a collection of essential utilities and helpers for building
|
|
22
|
+
and managing microservices using the Moleculer framework. It aims to have a better TS support and add commonly use mixins
|
|
23
|
+
and middlewares.
|
|
24
|
+
|
|
25
|
+
## Features
|
|
26
|
+
|
|
27
|
+
- **TypeScript Support**: By using the `wrapService` (and `wrapMixin`) functions, TS can automatically infer methods signatures, settings, etc.
|
|
28
|
+
- **Common Mixins**: Includes MongoDB, Redis, Redlock, BullMQ, and more mixins commonly used in backend applications.
|
|
29
|
+
- **Zod Validation**: Integrates Zod for schema validation in service actions. Also supports (legacy) Ajv validation.
|
|
30
|
+
- **OpenAPI Integration**: Easily provide a OpenAPI (Swagger) documentation for your services.
|
|
31
|
+
- And more...
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
Install `moleculer-essentials` with your package manager:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
yarn add @treatwell/moleculer-essentials
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Companion Packages
|
|
42
|
+
|
|
43
|
+
To complete the TS support and improve the developer experience, we also provide the following companion packages:
|
|
44
|
+
|
|
45
|
+
- [@treatwell/moleculer-call-wrapper](https://github.com/treatwell/moleculer-call-wrapper): A dev dependency to generate a fully typed `call` function that replaces the default `ctx.call` in Moleculer services.
|
|
46
|
+
- [@treatwell/eslint-plugin-moleculer](https://github.com/treatwell/eslint-plugin-moleculer): An ESLint plugin to work with this package to improve TS support and prevent some common mistakes.
|
|
47
|
+
|
|
48
|
+
## Usage
|
|
49
|
+
|
|
50
|
+
### Basic Example
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// src/index.ts
|
|
54
|
+
import fg from 'fast-glob';
|
|
55
|
+
import {
|
|
56
|
+
HealthCheckMiddleware,
|
|
57
|
+
createLoggerConfig,
|
|
58
|
+
createServiceBroker,
|
|
59
|
+
defaultLogger,
|
|
60
|
+
ZodValidator,
|
|
61
|
+
} from '@treatwell/moleculer-essentials';
|
|
62
|
+
import { fileURLToPath } from 'url';
|
|
63
|
+
import { dirname, join } from 'path';
|
|
64
|
+
import { config } from 'dotenv';
|
|
65
|
+
|
|
66
|
+
async function run() {
|
|
67
|
+
// Create Service Broker
|
|
68
|
+
const broker = createServiceBroker({
|
|
69
|
+
validator: new ZodValidator(),
|
|
70
|
+
logger: createLoggerConfig(),
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
// -> Filter out service to launch
|
|
74
|
+
const entries = await fg('**/*.service.{ts,js}', {
|
|
75
|
+
cwd: join(import.meta.dirname, 'services'),
|
|
76
|
+
absolute: true,
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
const services = entries.map(f => broker.loadService(f));
|
|
80
|
+
|
|
81
|
+
if (process.env.MOLECULER_CALL_WRAPPER === 'yes') {
|
|
82
|
+
import('@treatwell/moleculer-call-wrapper')
|
|
83
|
+
.then(async ({ createWrapperCall }) =>
|
|
84
|
+
createWrapperCall('./src/call.ts', services, entries, []),
|
|
85
|
+
)
|
|
86
|
+
.catch(err => {
|
|
87
|
+
broker.logger.error('Error while creating call wrapper', err);
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
await broker.start();
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
run().catch(err => {
|
|
95
|
+
defaultLogger.error('Error while starting server', { err });
|
|
96
|
+
process.exit(1);
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
// src/services/sum.service.ts
|
|
102
|
+
import { wrapService } from '@treatwell/moleculer-essentials';
|
|
103
|
+
import { z } from 'zod/v4';
|
|
104
|
+
import { Context } from 'moleculer';
|
|
105
|
+
|
|
106
|
+
const AddParamsSchema = z.object({ a: z.number(), b: z.number() });
|
|
107
|
+
|
|
108
|
+
export default wrapService({
|
|
109
|
+
name: `sum`,
|
|
110
|
+
actions: {
|
|
111
|
+
add: {
|
|
112
|
+
params: AddParamsSchema,
|
|
113
|
+
async handler(
|
|
114
|
+
ctx: Context<z.infer<typeof AddParamsSchema>>,
|
|
115
|
+
): Promise<number> {
|
|
116
|
+
return ctx.params.a + ctx.params.b;
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
});
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Mixins
|
|
124
|
+
|
|
125
|
+
Except for the `OpenAPIMixin`, mixins are **not** exported directly from `@treatwell/moleculer-essentials`.
|
|
126
|
+
Each mixin is available in its own namespace. For example, to use the `RedisMixin`, you first need to install the `ioredis`
|
|
127
|
+
package:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
yarn add ioredis
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Then, you can import and use the mixin like this:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
import { wrapService } from '@treatwell/moleculer-essentials';
|
|
137
|
+
import { RedisMixin } from '@treatwell/moleculer-essentials/redis';
|
|
138
|
+
import { Context } from 'moleculer';
|
|
139
|
+
|
|
140
|
+
export default wrapService({
|
|
141
|
+
name: 'my-service',
|
|
142
|
+
mixins: [RedisMixin({ host: 'localhost' })],
|
|
143
|
+
|
|
144
|
+
actions: {
|
|
145
|
+
myAction: {
|
|
146
|
+
async handler(ctx: Context): Promise<string | undefined> {
|
|
147
|
+
return this.getRedis().get('key');
|
|
148
|
+
},
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
> Moleculer-essentials doesn't provide the dependencies for the mixins, but only declares them as optional `peerDependencies`.
|
|
155
|
+
> By using a specific namespace for each mixin, you can install only the dependencies you need and use.
|
|
156
|
+
|
|
157
|
+
### Documentation
|
|
158
|
+
|
|
159
|
+
The documentation isn't done yet, but you can check the [source code](./src/) to see what is available.
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
[MIT](https://choosealicense.com/licenses/mit/)
|
package/dist/index.cjs
CHANGED
|
@@ -1022,7 +1022,53 @@ function createServiceBroker(opts = {}) {
|
|
|
1022
1022
|
),
|
|
1023
1023
|
ServiceFactory,
|
|
1024
1024
|
ContextFactory,
|
|
1025
|
-
|
|
1025
|
+
// Change the internal services actions to use Zod validation
|
|
1026
|
+
// instead of the default `fastest-validator` schemas
|
|
1027
|
+
// @ts-expect-error Moleculer types doesn't support zod validators
|
|
1028
|
+
internalServices: {
|
|
1029
|
+
$node: {
|
|
1030
|
+
actions: {
|
|
1031
|
+
list: {
|
|
1032
|
+
params: v4.z.object({ withServices: v4.z.boolean(), onlyAvailable: v4.z.boolean() }).partial()
|
|
1033
|
+
},
|
|
1034
|
+
services: {
|
|
1035
|
+
params: v4.z.object({
|
|
1036
|
+
onlyLocal: v4.z.boolean(),
|
|
1037
|
+
skipInternal: v4.z.boolean(),
|
|
1038
|
+
withActions: v4.z.boolean(),
|
|
1039
|
+
withEvents: v4.z.boolean(),
|
|
1040
|
+
onlyAvailable: v4.z.boolean(),
|
|
1041
|
+
grouping: v4.z.boolean().default(true)
|
|
1042
|
+
}).partial()
|
|
1043
|
+
},
|
|
1044
|
+
actions: {
|
|
1045
|
+
params: v4.z.object({
|
|
1046
|
+
onlyLocal: v4.z.boolean(),
|
|
1047
|
+
skipInternal: v4.z.boolean(),
|
|
1048
|
+
withEndpoints: v4.z.boolean(),
|
|
1049
|
+
onlyAvailable: v4.z.boolean()
|
|
1050
|
+
}).partial()
|
|
1051
|
+
},
|
|
1052
|
+
events: {
|
|
1053
|
+
params: v4.z.object({
|
|
1054
|
+
onlyLocal: v4.z.boolean(),
|
|
1055
|
+
skipInternal: v4.z.boolean(),
|
|
1056
|
+
withEndpoints: v4.z.boolean(),
|
|
1057
|
+
onlyAvailable: v4.z.boolean()
|
|
1058
|
+
}).partial()
|
|
1059
|
+
},
|
|
1060
|
+
health: { params: v4.z.object({}) },
|
|
1061
|
+
options: { params: v4.z.object({}) },
|
|
1062
|
+
metrics: {
|
|
1063
|
+
params: v4.z.object({
|
|
1064
|
+
types: v4.z.union([v4.z.string(), v4.z.array(v4.z.string())]),
|
|
1065
|
+
includes: v4.z.union([v4.z.string(), v4.z.array(v4.z.string())]),
|
|
1066
|
+
excludes: v4.z.union([v4.z.string(), v4.z.array(v4.z.string())])
|
|
1067
|
+
}).partial()
|
|
1068
|
+
}
|
|
1069
|
+
}
|
|
1070
|
+
}
|
|
1071
|
+
},
|
|
1026
1072
|
...opts
|
|
1027
1073
|
});
|
|
1028
1074
|
}
|
package/dist/index.mjs
CHANGED
|
@@ -1022,7 +1022,53 @@ function createServiceBroker(opts = {}) {
|
|
|
1022
1022
|
),
|
|
1023
1023
|
ServiceFactory,
|
|
1024
1024
|
ContextFactory,
|
|
1025
|
-
|
|
1025
|
+
// Change the internal services actions to use Zod validation
|
|
1026
|
+
// instead of the default `fastest-validator` schemas
|
|
1027
|
+
// @ts-expect-error Moleculer types doesn't support zod validators
|
|
1028
|
+
internalServices: {
|
|
1029
|
+
$node: {
|
|
1030
|
+
actions: {
|
|
1031
|
+
list: {
|
|
1032
|
+
params: z.object({ withServices: z.boolean(), onlyAvailable: z.boolean() }).partial()
|
|
1033
|
+
},
|
|
1034
|
+
services: {
|
|
1035
|
+
params: z.object({
|
|
1036
|
+
onlyLocal: z.boolean(),
|
|
1037
|
+
skipInternal: z.boolean(),
|
|
1038
|
+
withActions: z.boolean(),
|
|
1039
|
+
withEvents: z.boolean(),
|
|
1040
|
+
onlyAvailable: z.boolean(),
|
|
1041
|
+
grouping: z.boolean().default(true)
|
|
1042
|
+
}).partial()
|
|
1043
|
+
},
|
|
1044
|
+
actions: {
|
|
1045
|
+
params: z.object({
|
|
1046
|
+
onlyLocal: z.boolean(),
|
|
1047
|
+
skipInternal: z.boolean(),
|
|
1048
|
+
withEndpoints: z.boolean(),
|
|
1049
|
+
onlyAvailable: z.boolean()
|
|
1050
|
+
}).partial()
|
|
1051
|
+
},
|
|
1052
|
+
events: {
|
|
1053
|
+
params: z.object({
|
|
1054
|
+
onlyLocal: z.boolean(),
|
|
1055
|
+
skipInternal: z.boolean(),
|
|
1056
|
+
withEndpoints: z.boolean(),
|
|
1057
|
+
onlyAvailable: z.boolean()
|
|
1058
|
+
}).partial()
|
|
1059
|
+
},
|
|
1060
|
+
health: { params: z.object({}) },
|
|
1061
|
+
options: { params: z.object({}) },
|
|
1062
|
+
metrics: {
|
|
1063
|
+
params: z.object({
|
|
1064
|
+
types: z.union([z.string(), z.array(z.string())]),
|
|
1065
|
+
includes: z.union([z.string(), z.array(z.string())]),
|
|
1066
|
+
excludes: z.union([z.string(), z.array(z.string())])
|
|
1067
|
+
}).partial()
|
|
1068
|
+
}
|
|
1069
|
+
}
|
|
1070
|
+
}
|
|
1071
|
+
},
|
|
1026
1072
|
...opts
|
|
1027
1073
|
});
|
|
1028
1074
|
}
|
package/package.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "https://github.com/treatwell/moleculer-essentials"
|
|
8
8
|
},
|
|
9
|
-
"version": "1.0
|
|
9
|
+
"version": "1.1.0",
|
|
10
10
|
"main": "./dist/index.cjs",
|
|
11
11
|
"module": "./dist/index.mjs",
|
|
12
12
|
"types": "./dist/index.d.cts",
|
|
@@ -148,16 +148,18 @@
|
|
|
148
148
|
},
|
|
149
149
|
"devDependencies": {
|
|
150
150
|
"@aws-crypto/client-node": "^4.2.1",
|
|
151
|
-
"@eslint/js": "^9.
|
|
151
|
+
"@eslint/js": "^9.34.0",
|
|
152
152
|
"@treatwell/eslint-plugin-moleculer": "^1.1.0",
|
|
153
153
|
"@tsconfig/node-lts": "^22.0.2",
|
|
154
154
|
"@types/jsonwebtoken": "^9.0.10",
|
|
155
155
|
"@types/lodash-es": "^4.17.12",
|
|
156
156
|
"@types/node": "^24.3.0",
|
|
157
|
-
"@types/redlock": "^4.0.
|
|
157
|
+
"@types/redlock": "^4.0.7",
|
|
158
158
|
"bullmq": "^5.12.10",
|
|
159
|
-
"eslint": "^9.
|
|
159
|
+
"eslint": "^9.34.0",
|
|
160
160
|
"eslint-config-prettier": "^10.1.8",
|
|
161
|
+
"eslint-import-resolver-typescript": "^4.4.4",
|
|
162
|
+
"eslint-plugin-import": "^2.32.0",
|
|
161
163
|
"eslint-plugin-prettier": "^5.5.4",
|
|
162
164
|
"ioredis": "^5.2.3",
|
|
163
165
|
"jiti": "^2.5.1",
|
|
@@ -170,9 +172,9 @@
|
|
|
170
172
|
"redlock": "^4.2.0",
|
|
171
173
|
"semantic-release": "^24.2.7",
|
|
172
174
|
"typescript": "~5.9.2",
|
|
173
|
-
"typescript-eslint": "^8.
|
|
175
|
+
"typescript-eslint": "^8.41.0",
|
|
174
176
|
"vitest": "^3.2.4",
|
|
175
|
-
"zod": "^4.
|
|
177
|
+
"zod": "^4.1.5"
|
|
176
178
|
},
|
|
177
179
|
"files": [
|
|
178
180
|
"dist"
|