express-zod-api 25.5.1 → 25.5.3
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 +97 -81
- package/README.md +61 -54
- package/dist/index.d.ts +8 -8
- package/dist/index.js +2 -2
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
## Version 25
|
|
4
4
|
|
|
5
|
+
### v25.5.3
|
|
6
|
+
|
|
7
|
+
- Updated environment requirements in the Readme:
|
|
8
|
+
- Version 25 should be run in an ESM environment because it installs the Zod plugin using the `import` statement;
|
|
9
|
+
- To ensure this, either set `type: module` in `package.json`, use `.mts` extension, or run using `tsx`/`vite-node`;
|
|
10
|
+
- Although all Node.js versions support `require(ESM)`, `zod` remains a dual package with both CJS and ESM copies;
|
|
11
|
+
- If your code uses `require("zod")` (CJS), it is not the same instance that the framework operates;
|
|
12
|
+
- This can lead to `TypeError: example is not a function` and loss of metadata set by the `.meta()` method;
|
|
13
|
+
- This issue was reported by [@squishykid](https://github.com/squishykid).
|
|
14
|
+
|
|
15
|
+
### v25.5.2
|
|
16
|
+
|
|
17
|
+
- Added `z.function()` to the list of JSON-incompatible schemas:
|
|
18
|
+
- It will warn when using such schema in a JSON operating Endpoint;
|
|
19
|
+
- `z.function()` [became a schema again](https://github.com/colinhacks/zod/issues/4143) in Zod 4.1.0.
|
|
20
|
+
|
|
5
21
|
### v25.5.1
|
|
6
22
|
|
|
7
23
|
- Aligned the requirements on Node.js versions between for `@express-zod-api/zod-plugin`;
|
|
@@ -1458,7 +1474,7 @@ const config = createConfig({
|
|
|
1458
1474
|
- The ESLint plugin was introduced in v20.0.0 for automated migration from v19 (except assertions in tests);
|
|
1459
1475
|
- For migrating from v19 use the following minimal config and run `eslint --fix`:
|
|
1460
1476
|
|
|
1461
|
-
```
|
|
1477
|
+
```js
|
|
1462
1478
|
// eslint.config.js (or .mjs if you're developing in a CommonJS environment)
|
|
1463
1479
|
import parser from "@typescript-eslint/parser";
|
|
1464
1480
|
import migration from "express-zod-api/migration";
|
|
@@ -1491,7 +1507,7 @@ export default [
|
|
|
1491
1507
|
- it can also be a function returning one of those values depending on duration in milliseconds;
|
|
1492
1508
|
- thus, you can immediately assess the measured performance.
|
|
1493
1509
|
|
|
1494
|
-
```
|
|
1510
|
+
```ts
|
|
1495
1511
|
const done = logger.profile({
|
|
1496
1512
|
message: "expensive operation",
|
|
1497
1513
|
severity: (ms) => (ms > 500 ? "error" : "info"),
|
|
@@ -1509,14 +1525,14 @@ done(); // error: expensive operation '555.55ms'
|
|
|
1509
1525
|
- The output severity is `debug` (will be customizable later), so logger must have the corresponding `level`;
|
|
1510
1526
|
- It prints the duration in log using adaptive units: from picoseconds to minutes.
|
|
1511
1527
|
|
|
1512
|
-
```
|
|
1528
|
+
```ts
|
|
1513
1529
|
// usage assuming that logger is an instance of BuiltinLogger
|
|
1514
1530
|
const done = logger.profile("expensive operation");
|
|
1515
1531
|
doExpensiveOperation();
|
|
1516
1532
|
done(); // debug: expensive operation '555 milliseconds'
|
|
1517
1533
|
```
|
|
1518
1534
|
|
|
1519
|
-
```
|
|
1535
|
+
```ts
|
|
1520
1536
|
// to set up config using the built-in logger do this:
|
|
1521
1537
|
import { createConfig, BuiltinLogger } from "express-zod-api";
|
|
1522
1538
|
|
|
@@ -1541,7 +1557,7 @@ declare module "express-zod-api" {
|
|
|
1541
1557
|
- The method returns: `Promise<{ output, requestMock, responseMock, loggerMock }>`;
|
|
1542
1558
|
- Export fixed in v20.14.3.
|
|
1543
1559
|
|
|
1544
|
-
```
|
|
1560
|
+
```ts
|
|
1545
1561
|
import { z } from "zod";
|
|
1546
1562
|
import { Middleware, testMiddleware } from "express-zod-api";
|
|
1547
1563
|
|
|
@@ -1945,7 +1961,7 @@ const after = ez.raw({
|
|
|
1945
1961
|
- Consider reusing `const` across your files for persistent connections;
|
|
1946
1962
|
- In case of intentional non-persistent connection, consider resources cleanup if necessary:
|
|
1947
1963
|
|
|
1948
|
-
```
|
|
1964
|
+
```ts
|
|
1949
1965
|
import { createResultHandler } from "express-zod-api";
|
|
1950
1966
|
|
|
1951
1967
|
const resultHandlerWithCleanup = createResultHandler({
|
|
@@ -2170,7 +2186,7 @@ withRest: # z.tuple([z.boolean()]).rest(z.string())
|
|
|
2170
2186
|
- Suggested use case: database clients that do not close their connections when their instances are destroyed.
|
|
2171
2187
|
- The `options` coming to Result Handler can be empty or incomplete in case of errors and failures.
|
|
2172
2188
|
|
|
2173
|
-
```
|
|
2189
|
+
```ts
|
|
2174
2190
|
import {
|
|
2175
2191
|
createResultHandler,
|
|
2176
2192
|
EndpointsFactory,
|
|
@@ -2207,7 +2223,7 @@ const dbEquippedFactory = new EndpointsFactory(
|
|
|
2207
2223
|
- Please note: the `.debug()` method of the configured logger is used for upload related logging, therefore the
|
|
2208
2224
|
severity `level` of that logger must be configured accordingly in order to see those messages.
|
|
2209
2225
|
|
|
2210
|
-
```
|
|
2226
|
+
```ts
|
|
2211
2227
|
import { createConfig } from "express-zod-api";
|
|
2212
2228
|
import { Logger } from "winston";
|
|
2213
2229
|
|
|
@@ -2250,7 +2266,7 @@ info: POST: /v1/avatar/upload
|
|
|
2250
2266
|
- It can be used to connect a middleware that restricts the ability to upload;
|
|
2251
2267
|
- It accepts a function similar to `beforeRouting`, having `app` and `logger` in its argument.
|
|
2252
2268
|
|
|
2253
|
-
```
|
|
2269
|
+
```ts
|
|
2254
2270
|
import createHttpError from "http-errors";
|
|
2255
2271
|
import { createConfig } from "express-zod-api";
|
|
2256
2272
|
|
|
@@ -2374,7 +2390,7 @@ after:
|
|
|
2374
2390
|
- The option controls how deeply the objects should be inspected, serialized and printed.
|
|
2375
2391
|
- It can be set to `null` or `Infinity` for unlimited depth.
|
|
2376
2392
|
|
|
2377
|
-
```
|
|
2393
|
+
```ts
|
|
2378
2394
|
// Reproduction example
|
|
2379
2395
|
import { createConfig, createServer } from "express-zod-api";
|
|
2380
2396
|
|
|
@@ -2389,7 +2405,7 @@ subject.prop = subject;
|
|
|
2389
2405
|
logger.error("Circular reference", subject);
|
|
2390
2406
|
```
|
|
2391
2407
|
|
|
2392
|
-
```
|
|
2408
|
+
```ts
|
|
2393
2409
|
// Feature example
|
|
2394
2410
|
import { createConfig } from "express-zod-api";
|
|
2395
2411
|
|
|
@@ -2402,7 +2418,7 @@ createConfig({ logger: { level: "warn", depth: null } });
|
|
|
2402
2418
|
|
|
2403
2419
|
- Fixed logging arrays by the default `winston` logger.
|
|
2404
2420
|
|
|
2405
|
-
```
|
|
2421
|
+
```ts
|
|
2406
2422
|
// before: Items { '0': 123 }
|
|
2407
2423
|
// after: Items [ 123 ]
|
|
2408
2424
|
logger.debug("Items", [123]);
|
|
@@ -2539,7 +2555,7 @@ after:
|
|
|
2539
2555
|
- The provider function receives the initially configured logger and the request, it can also be asynchronous;
|
|
2540
2556
|
- Consider the following example in case of Winston logger:
|
|
2541
2557
|
|
|
2542
|
-
```
|
|
2558
|
+
```ts
|
|
2543
2559
|
import { createConfig } from "express-zod-api";
|
|
2544
2560
|
import { Logger } from "winston"; // or another compatible logger
|
|
2545
2561
|
import { randomUUID } from "node:crypto";
|
|
@@ -2821,7 +2837,7 @@ operationId:
|
|
|
2821
2837
|
- Consider using `logger` property supplied to `createConfig()` instead;
|
|
2822
2838
|
- Otherwise, supply also the `winston` argument to the helper (`import winston from "winston"`).
|
|
2823
2839
|
|
|
2824
|
-
```
|
|
2840
|
+
```ts
|
|
2825
2841
|
import winston from "winston";
|
|
2826
2842
|
import { createConfig, createLogger, createServer } from "express-zod-api";
|
|
2827
2843
|
|
|
@@ -2844,7 +2860,7 @@ declare module "express-zod-api" {
|
|
|
2844
2860
|
const { app, httpServer } = await createServer(config, routing);
|
|
2845
2861
|
```
|
|
2846
2862
|
|
|
2847
|
-
```
|
|
2863
|
+
```ts
|
|
2848
2864
|
// Adjust your tests: set the MockOverrides type once anywhere
|
|
2849
2865
|
declare module "express-zod-api" {
|
|
2850
2866
|
interface MockOverrides extends jest.Mock {} // or Mock from vitest
|
|
@@ -2874,7 +2890,7 @@ declare module "express-zod-api" {
|
|
|
2874
2890
|
|
|
2875
2891
|
- Hotfix for 14.2.4: handling the case of empty object supplied as a second argument to the logger methods.
|
|
2876
2892
|
|
|
2877
|
-
```
|
|
2893
|
+
```ts
|
|
2878
2894
|
logger.info("Payload", {});
|
|
2879
2895
|
```
|
|
2880
2896
|
|
|
@@ -2882,7 +2898,7 @@ logger.info("Payload", {});
|
|
|
2882
2898
|
|
|
2883
2899
|
- Fixed internal logging format when primitive are supplied as a second argument to the logger methods.
|
|
2884
2900
|
|
|
2885
|
-
```
|
|
2901
|
+
```ts
|
|
2886
2902
|
logger.info("Listening", 8090);
|
|
2887
2903
|
```
|
|
2888
2904
|
|
|
@@ -2918,7 +2934,7 @@ logger.info("Listening", 8090);
|
|
|
2918
2934
|
- `ez.raw()` — which is the same as `z.object({ raw: ez.file().buffer() })`.
|
|
2919
2935
|
- Thus, the raw data becomes available to a handler as `input.raw` property.
|
|
2920
2936
|
|
|
2921
|
-
```
|
|
2937
|
+
```ts
|
|
2922
2938
|
import express from "express";
|
|
2923
2939
|
import { createConfig, defaultEndpointsFactory, ez } from "express-zod-api";
|
|
2924
2940
|
|
|
@@ -2949,7 +2965,7 @@ const rawAcceptingEndpoint = defaultEndpointsFactory.build({
|
|
|
2949
2965
|
[in Node.js documentation](https://nodejs.org/dist/latest-v20.x/docs/api/net.html#serverlistenoptions-callback).
|
|
2950
2966
|
- Thanks to [@huyhoang160593](https://github.com/huyhoang160593) for noticing the lack of configurability.
|
|
2951
2967
|
|
|
2952
|
-
```
|
|
2968
|
+
```ts
|
|
2953
2969
|
import { createConfig } from "express-zod-api";
|
|
2954
2970
|
|
|
2955
2971
|
createConfig({
|
|
@@ -2998,7 +3014,7 @@ createConfig({
|
|
|
2998
3014
|
- or `npm install -D @types/express @types/node @types/http-errors`
|
|
2999
3015
|
- The property `DependsOnMethod::methods` is renamed to `endpoints`.
|
|
3000
3016
|
|
|
3001
|
-
```
|
|
3017
|
+
```ts
|
|
3002
3018
|
// before
|
|
3003
3019
|
import { createHttpError } from "express-zod-api";
|
|
3004
3020
|
// after
|
|
@@ -3018,7 +3034,7 @@ import createHttpError from "http-errors";
|
|
|
3018
3034
|
- Featuring an ability to specify multiple server URLs when generating documentation.
|
|
3019
3035
|
- This feature is a shorthand for `new Documentation().addServer()`
|
|
3020
3036
|
|
|
3021
|
-
```
|
|
3037
|
+
```ts
|
|
3022
3038
|
new Documentation({
|
|
3023
3039
|
serverUrl: ["https://example1.com", "https://example2.com"],
|
|
3024
3040
|
// ...
|
|
@@ -3030,7 +3046,7 @@ new Documentation({
|
|
|
3030
3046
|
- Feature: ability to assign a function to the `operationId` property of the `EndpointsFactory::build()` argument.
|
|
3031
3047
|
- This can help to customize the Operation ID for the endpoints serving multiple methods.
|
|
3032
3048
|
|
|
3033
|
-
```
|
|
3049
|
+
```ts
|
|
3034
3050
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
3035
3051
|
|
|
3036
3052
|
defaultEndpointsFactory.build({
|
|
@@ -3048,7 +3064,7 @@ defaultEndpointsFactory.build({
|
|
|
3048
3064
|
- When using this feature, you must ensure the uniqueness of the IDs you specified across your API endpoints.
|
|
3049
3065
|
- The feature is implemented by [@john-schmitz](https://github.com/john-schmitz).
|
|
3050
3066
|
|
|
3051
|
-
```
|
|
3067
|
+
```ts
|
|
3052
3068
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
3053
3069
|
|
|
3054
3070
|
defaultEndpointsFactory.build({
|
|
@@ -3065,7 +3081,7 @@ defaultEndpointsFactory.build({
|
|
|
3065
3081
|
- The headers are lowercase when describing their validation schema.
|
|
3066
3082
|
- Parameters in request headers described the following way are supported by the documentation generator.
|
|
3067
3083
|
|
|
3068
|
-
```
|
|
3084
|
+
```ts
|
|
3069
3085
|
import { createConfig, defaultEndpointsFactory } from "express-zod-api";
|
|
3070
3086
|
import { z } from "zod";
|
|
3071
3087
|
|
|
@@ -3592,7 +3608,7 @@ after:
|
|
|
3592
3608
|
implementation.
|
|
3593
3609
|
- Read the [customization instructions](README.md#customizing-input-sources).
|
|
3594
3610
|
|
|
3595
|
-
```
|
|
3611
|
+
```ts
|
|
3596
3612
|
// Your custom ResultHandler
|
|
3597
3613
|
// Before: if you're having an expression like this:
|
|
3598
3614
|
if (error instanceof z.ZodError) {
|
|
@@ -3626,7 +3642,7 @@ inputSources: { delete: ["body", "query", "params"] }
|
|
|
3626
3642
|
- `mimeType` overrides `mimeTypes` when both are specified.
|
|
3627
3643
|
- The `createApiResponse()` method is deprecated and will be removed in next major release.
|
|
3628
3644
|
|
|
3629
|
-
```
|
|
3645
|
+
```ts
|
|
3630
3646
|
// JSON responding ResultHandler Example
|
|
3631
3647
|
// before
|
|
3632
3648
|
createResultHandler({
|
|
@@ -3641,7 +3657,7 @@ createResultHandler({
|
|
|
3641
3657
|
});
|
|
3642
3658
|
```
|
|
3643
3659
|
|
|
3644
|
-
```
|
|
3660
|
+
```ts
|
|
3645
3661
|
// Example on customizing MIME types and status codes
|
|
3646
3662
|
// before
|
|
3647
3663
|
createResultHandler({
|
|
@@ -3724,7 +3740,7 @@ after:
|
|
|
3724
3740
|
- The list of required object properties was depicted incorrectly by the OpenAPI generator in case of using the new
|
|
3725
3741
|
`coerce` feature in the response schema.
|
|
3726
3742
|
|
|
3727
|
-
```
|
|
3743
|
+
```ts
|
|
3728
3744
|
// reproduction example
|
|
3729
3745
|
const endpoint = defaultEndpointsFactory.build({
|
|
3730
3746
|
// ...
|
|
@@ -3760,7 +3776,7 @@ after:
|
|
|
3760
3776
|
- `ZodNativeEnum` (similar to `ZodEnum`), `ZodCatch`, `ZodBranded`, `ZodPipeline`.
|
|
3761
3777
|
- Additionally, the representation of some schemas have been changed slightly:
|
|
3762
3778
|
|
|
3763
|
-
```
|
|
3779
|
+
```ts
|
|
3764
3780
|
interface Changes<T> {
|
|
3765
3781
|
ZodFile: {
|
|
3766
3782
|
before: any;
|
|
@@ -3823,7 +3839,7 @@ output/anything: Number must be greater than 0
|
|
|
3823
3839
|
- The regular expression used for validating `z.dateIn()` made easier
|
|
3824
3840
|
by [@niklashigi](https://github.com/niklashigi).
|
|
3825
3841
|
|
|
3826
|
-
```
|
|
3842
|
+
```ts
|
|
3827
3843
|
const before = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{3})?)?Z?$/;
|
|
3828
3844
|
const after = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$/;
|
|
3829
3845
|
```
|
|
@@ -3846,7 +3862,7 @@ const after = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$/;
|
|
|
3846
3862
|
- The list of the allowed methods in the response to `OPTIONS` request did only contain the first method declared
|
|
3847
3863
|
within `DependsOnMethod` instance.
|
|
3848
3864
|
|
|
3849
|
-
```
|
|
3865
|
+
```ts
|
|
3850
3866
|
// reproduction minimal setup
|
|
3851
3867
|
const routing: Routing = {
|
|
3852
3868
|
test: new DependsOnMethod({
|
|
@@ -3932,7 +3948,7 @@ after:
|
|
|
3932
3948
|
- The feature suggested by [@johngeorgewright](https://github.com/johngeorgewright)
|
|
3933
3949
|
and [ssteuteville](https://github.com/ssteuteville).
|
|
3934
3950
|
|
|
3935
|
-
```
|
|
3951
|
+
```ts
|
|
3936
3952
|
// example
|
|
3937
3953
|
import { z } from "express-zod-api";
|
|
3938
3954
|
|
|
@@ -3966,7 +3982,7 @@ const endpoint = endpointsFactory.build({
|
|
|
3966
3982
|
generated from the `description` by trimming.
|
|
3967
3983
|
- You can optionally disable this behavior with the new option `hasSummaryFromDescription` of the `OpenAPI` generator.
|
|
3968
3984
|
|
|
3969
|
-
```
|
|
3985
|
+
```ts
|
|
3970
3986
|
const exampleEndpoint = yourEndpointsFactory.build({
|
|
3971
3987
|
// ...
|
|
3972
3988
|
description: "The detailed explanaition on what this endpoint does.",
|
|
@@ -3988,7 +4004,7 @@ const exampleEndpoint = yourEndpointsFactory.build({
|
|
|
3988
4004
|
- The feature suggested by [@TheWisestOne](https://github.com/TheWisestOne).
|
|
3989
4005
|
- The property `scopes` (introduced in v7.9.0) has got its singular variation `scope`.
|
|
3990
4006
|
|
|
3991
|
-
```
|
|
4007
|
+
```ts
|
|
3992
4008
|
import {
|
|
3993
4009
|
createConfig,
|
|
3994
4010
|
EndpointsFactory,
|
|
@@ -4048,7 +4064,7 @@ const exampleEndpoint = taggedEndpointsFactory.build({
|
|
|
4048
4064
|
- The list of the allowed methods in the response to `OPTIONS` request did only contain the first method declared
|
|
4049
4065
|
within `DependsOnMethod` instance.
|
|
4050
4066
|
|
|
4051
|
-
```
|
|
4067
|
+
```ts
|
|
4052
4068
|
// reproduction minimal setup
|
|
4053
4069
|
const routing: Routing = {
|
|
4054
4070
|
test: new DependsOnMethod({
|
|
@@ -4081,7 +4097,7 @@ const routing: Routing = {
|
|
|
4081
4097
|
- In this case that entity will be stringified into a `.message` of `Error`.
|
|
4082
4098
|
- The issue manifested itself as a positive API response without data.
|
|
4083
4099
|
|
|
4084
|
-
```
|
|
4100
|
+
```ts
|
|
4085
4101
|
// reproduction example
|
|
4086
4102
|
const myEndpoint = defaultEndpointsFactory.build({
|
|
4087
4103
|
method: "get",
|
|
@@ -4111,7 +4127,7 @@ const myEndpoint = defaultEndpointsFactory.build({
|
|
|
4111
4127
|
flows including scopes.
|
|
4112
4128
|
- Endpoints utilizing those middlewares can now specify their `scopes`.
|
|
4113
4129
|
|
|
4114
|
-
```
|
|
4130
|
+
```ts
|
|
4115
4131
|
import { createMiddleware, defaultEndpointsFactory, z } from "express-zod-api";
|
|
4116
4132
|
|
|
4117
4133
|
// example middleware
|
|
@@ -4168,7 +4184,7 @@ const myEndpoint = defaultEndpointsFactory.addMiddleware(myMiddleware).build({
|
|
|
4168
4184
|
- Supported security types: `basic`, `bearer`, `input`, `header`, `cookie`, `openid` and `oauth2`.
|
|
4169
4185
|
- OpenID and OAuth2 security types are currently have the limited support: without scopes.
|
|
4170
4186
|
|
|
4171
|
-
```
|
|
4187
|
+
```ts
|
|
4172
4188
|
// example middleware
|
|
4173
4189
|
import { createMiddleware } from "express-zod-api";
|
|
4174
4190
|
|
|
@@ -4238,7 +4254,7 @@ createMiddleware({
|
|
|
4238
4254
|
- **Please note:** If using both `cors` package (express middleware) and `cors` configuration option, the
|
|
4239
4255
|
configuration option sets CORS headers first, so the middleware can override them if needed.
|
|
4240
4256
|
|
|
4241
|
-
```
|
|
4257
|
+
```ts
|
|
4242
4258
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
4243
4259
|
import cors from "cors";
|
|
4244
4260
|
|
|
@@ -4260,7 +4276,7 @@ const myFactory = defaultEndpointsFactory.addExpressMiddleware(
|
|
|
4260
4276
|
- Setting `cors: true` implies the default headers;
|
|
4261
4277
|
- The feature suggested by [@HardCoreQual](https://github.com/HardCoreQual).
|
|
4262
4278
|
|
|
4263
|
-
```
|
|
4279
|
+
```ts
|
|
4264
4280
|
import { createConfig } from "express-zod-api";
|
|
4265
4281
|
|
|
4266
4282
|
const config = createConfig({
|
|
@@ -4285,7 +4301,7 @@ Access-Control-Max-Age: 5000
|
|
|
4285
4301
|
The output was empty, considering the first argument to be a message.
|
|
4286
4302
|
It's fixed in this version by adding `[No message]` message before printing the object.
|
|
4287
4303
|
|
|
4288
|
-
```
|
|
4304
|
+
```ts
|
|
4289
4305
|
// reproduction example
|
|
4290
4306
|
logger.debug({ something: "test" });
|
|
4291
4307
|
```
|
|
@@ -4363,7 +4379,7 @@ logger.debug({ something: "test" });
|
|
|
4363
4379
|
- `zod-to-ts` version is 1.0.0.
|
|
4364
4380
|
- The type of optional I/O parameters in the generated Client is aligned with `zod` definition.
|
|
4365
4381
|
|
|
4366
|
-
```
|
|
4382
|
+
```ts
|
|
4367
4383
|
interface Before {
|
|
4368
4384
|
foo: number | undefined;
|
|
4369
4385
|
}
|
|
@@ -4389,7 +4405,7 @@ interface After {
|
|
|
4389
4405
|
- Its parameter `path` now contains substituted path params;
|
|
4390
4406
|
- The feature suggested by [@hellovai](https://github.com/hellovai).
|
|
4391
4407
|
|
|
4392
|
-
```
|
|
4408
|
+
```ts
|
|
4393
4409
|
// example client-generator.ts
|
|
4394
4410
|
import fs from "fs";
|
|
4395
4411
|
import { Client } from "express-zod-api";
|
|
@@ -4397,7 +4413,7 @@ import { Client } from "express-zod-api";
|
|
|
4397
4413
|
fs.writeFileSync("./frontend/client.ts", new Client(routing).print(), "utf-8");
|
|
4398
4414
|
```
|
|
4399
4415
|
|
|
4400
|
-
```
|
|
4416
|
+
```ts
|
|
4401
4417
|
// example frontend using the most simple Implementation based on fetch
|
|
4402
4418
|
import { ExpressZodAPIClient } from "./client.ts";
|
|
4403
4419
|
|
|
@@ -4447,7 +4463,7 @@ client.provide("get", "/v1/user/retrieve", { id: "10" });
|
|
|
4447
4463
|
- Instead, it is now documented using `oneOf` OpenAPI notation.
|
|
4448
4464
|
- In addition, you can now also use the new `z.discriminatedUnion()` as the input schema on the top level.
|
|
4449
4465
|
|
|
4450
|
-
```
|
|
4466
|
+
```ts
|
|
4451
4467
|
// how to migrate
|
|
4452
4468
|
export const myMiddleware = createMiddleware({
|
|
4453
4469
|
input: z
|
|
@@ -4460,7 +4476,7 @@ export const myMiddleware = createMiddleware({
|
|
|
4460
4476
|
});
|
|
4461
4477
|
```
|
|
4462
4478
|
|
|
4463
|
-
```
|
|
4479
|
+
```ts
|
|
4464
4480
|
// example
|
|
4465
4481
|
const endpoint = defaultEndpointsFactory.build({
|
|
4466
4482
|
method: "post",
|
|
@@ -4510,7 +4526,7 @@ const endpoint = defaultEndpointsFactory.build({
|
|
|
4510
4526
|
- You can also specify an error transformer so that the `ResultHandler` would send the status you need.
|
|
4511
4527
|
- In case the error is not a `HttpError`, the `ResultHandler` will send the status `500`.
|
|
4512
4528
|
|
|
4513
|
-
```
|
|
4529
|
+
```ts
|
|
4514
4530
|
import { defaultEndpointsFactory, createHttpError } from "express-zod-api";
|
|
4515
4531
|
import cors from "cors";
|
|
4516
4532
|
import { auth } from "express-oauth2-jwt-bearer";
|
|
@@ -4567,7 +4583,7 @@ const advancedUsage = defaultEndpointsFactory.use(auth(), {
|
|
|
4567
4583
|
- `z.dateOut()`, on the contrary, accepts a `Date` and provides `ResultHanlder` with a `string` representation in ISO
|
|
4568
4584
|
format for the response transmission.
|
|
4569
4585
|
|
|
4570
|
-
```
|
|
4586
|
+
```ts
|
|
4571
4587
|
import { z, defaultEndpointsFactory } from "express-zod-api";
|
|
4572
4588
|
|
|
4573
4589
|
const updateUserEndpoint = defaultEndpointsFactory.build({
|
|
@@ -4613,7 +4629,7 @@ const updateUserEndpoint = defaultEndpointsFactory.build({
|
|
|
4613
4629
|
- Only responses with compressible content types are subject to compression.
|
|
4614
4630
|
- There is also a default threshold of 1KB that can be configured.
|
|
4615
4631
|
|
|
4616
|
-
```
|
|
4632
|
+
```ts
|
|
4617
4633
|
import { createConfig } from "express-zod-api";
|
|
4618
4634
|
|
|
4619
4635
|
const config = createConfig({
|
|
@@ -4659,7 +4675,7 @@ const config = createConfig({
|
|
|
4659
4675
|
- You can find the documentation on these arguments here: http://expressjs.com/en/4x/api.html#express.static
|
|
4660
4676
|
- The feature suggested by [@Isaac-Leonard](https://github.com/Isaac-Leonard).
|
|
4661
4677
|
|
|
4662
|
-
```
|
|
4678
|
+
```ts
|
|
4663
4679
|
import { Routing, ServeStatic } from "express-zod-api";
|
|
4664
4680
|
import path from "path";
|
|
4665
4681
|
|
|
@@ -4681,7 +4697,7 @@ const routing: Routing = {
|
|
|
4681
4697
|
- The method executes the endpoint and returns the created mocks.
|
|
4682
4698
|
- After that you only need to assert your expectations in the test.
|
|
4683
4699
|
|
|
4684
|
-
```
|
|
4700
|
+
```ts
|
|
4685
4701
|
import { testEndpoint } from "express-zod-api";
|
|
4686
4702
|
|
|
4687
4703
|
test("should respond successfully", async () => {
|
|
@@ -4709,7 +4725,7 @@ test("should respond successfully", async () => {
|
|
|
4709
4725
|
- This option is only available when using `createServer()` method.
|
|
4710
4726
|
- New configuration option `https`:
|
|
4711
4727
|
|
|
4712
|
-
```
|
|
4728
|
+
```ts
|
|
4713
4729
|
import { createConfig } from "express-zod-api";
|
|
4714
4730
|
|
|
4715
4731
|
const config = createConfig({
|
|
@@ -4744,7 +4760,7 @@ const config = createConfig({
|
|
|
4744
4760
|
- Under the hood the method creates a middleware with an empty input and attaches it to the factory.
|
|
4745
4761
|
- The argument supplied to the method is available within `options` parameter of the Endpoint's `handler`.
|
|
4746
4762
|
|
|
4747
|
-
```
|
|
4763
|
+
```ts
|
|
4748
4764
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
4749
4765
|
|
|
4750
4766
|
const newFactory = defaultEndpointsFactory.addOptions({
|
|
@@ -4802,7 +4818,7 @@ after: "/v1/user/{id}"
|
|
|
4802
4818
|
- You no longer need a middleware like `paramsProviderMiddleware` to handle path params.
|
|
4803
4819
|
- The route path params are now reflected in the generated documentation.
|
|
4804
4820
|
|
|
4805
|
-
```
|
|
4821
|
+
```ts
|
|
4806
4822
|
const routingExample: Routing = {
|
|
4807
4823
|
v1: {
|
|
4808
4824
|
user: {
|
|
@@ -4830,7 +4846,7 @@ const getUserEndpoint = endpointsFactory.build({
|
|
|
4830
4846
|
|
|
4831
4847
|
- The default configuration of `inputSources` has been changed.
|
|
4832
4848
|
|
|
4833
|
-
```
|
|
4849
|
+
```ts
|
|
4834
4850
|
const newInputSourcesByDefault: InputSources = {
|
|
4835
4851
|
get: ["query", "params"],
|
|
4836
4852
|
post: ["body", "params", "files"],
|
|
@@ -4874,7 +4890,7 @@ const newInputSourcesByDefault: InputSources = {
|
|
|
4874
4890
|
- Notice: `withMeta()` mutates its argument;
|
|
4875
4891
|
- The feature suggested by [@digimuza](https://github.com/digimuza).
|
|
4876
4892
|
|
|
4877
|
-
```
|
|
4893
|
+
```ts
|
|
4878
4894
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
4879
4895
|
|
|
4880
4896
|
const exampleEndpoint = defaultEndpointsFactory.build({
|
|
@@ -4941,7 +4957,7 @@ example:
|
|
|
4941
4957
|
- New config option `inputSources` allows you to specify the properties of the request, that are combined into an
|
|
4942
4958
|
input that is being validated and available to your endpoints and middlewares.
|
|
4943
4959
|
|
|
4944
|
-
```
|
|
4960
|
+
```ts
|
|
4945
4961
|
import { createConfig } from "express-zod-api";
|
|
4946
4962
|
|
|
4947
4963
|
createConfig({
|
|
@@ -4959,7 +4975,7 @@ createConfig({
|
|
|
4959
4975
|
|
|
4960
4976
|
- For example, in case you need `query` along with `body` available to your endpoints handling POST requests, consider:
|
|
4961
4977
|
|
|
4962
|
-
```
|
|
4978
|
+
```ts
|
|
4963
4979
|
createConfig({
|
|
4964
4980
|
// ...,
|
|
4965
4981
|
inputSources: {
|
|
@@ -4978,7 +4994,7 @@ createConfig({
|
|
|
4978
4994
|
so I add startup logo in this regard.
|
|
4979
4995
|
- However, you can turn it off with a simple setting:
|
|
4980
4996
|
|
|
4981
|
-
```
|
|
4997
|
+
```ts
|
|
4982
4998
|
import {createConfig} from 'express-zod-api';
|
|
4983
4999
|
|
|
4984
5000
|
const config = createConfig({
|
|
@@ -4994,7 +5010,7 @@ const config = createConfig({
|
|
|
4994
5010
|
- In case of using enums and literals in the key schema they will be described as required ones in the generated
|
|
4995
5011
|
OpenAPI / Swagger documentation.
|
|
4996
5012
|
|
|
4997
|
-
```
|
|
5013
|
+
```ts
|
|
4998
5014
|
// example
|
|
4999
5015
|
z.record(
|
|
5000
5016
|
z.enum(["option1", "option2"]), // keys
|
|
@@ -5005,7 +5021,7 @@ z.record(
|
|
|
5005
5021
|
- Feature #145: `attachRouting()` now returns the `logger` instance and `notFoundHandler`. You can use it with your
|
|
5006
5022
|
custom express app for handling `404` (not found) errors:
|
|
5007
5023
|
|
|
5008
|
-
```
|
|
5024
|
+
```ts
|
|
5009
5025
|
const { notFoundHandler } = attachRouting(config, routing);
|
|
5010
5026
|
app.use(notFoundHandler);
|
|
5011
5027
|
app.listen();
|
|
@@ -5013,7 +5029,7 @@ app.listen();
|
|
|
5013
5029
|
|
|
5014
5030
|
- Or you can use the `logger` instance with any `ResultHandler` for the same purpose:
|
|
5015
5031
|
|
|
5016
|
-
```
|
|
5032
|
+
```ts
|
|
5017
5033
|
const { logger } = attachRouting(config, routing);
|
|
5018
5034
|
app.use((request, response) => {
|
|
5019
5035
|
defaultResultHandler.handler({
|
|
@@ -5048,7 +5064,7 @@ app.listen();
|
|
|
5048
5064
|
- Introducing the new schema: `z.upload()`.
|
|
5049
5065
|
- New configuration option:
|
|
5050
5066
|
|
|
5051
|
-
```
|
|
5067
|
+
```ts
|
|
5052
5068
|
const config = createConfig({
|
|
5053
5069
|
server: {
|
|
5054
5070
|
upload: true,
|
|
@@ -5067,7 +5083,7 @@ const config = createConfig({
|
|
|
5067
5083
|
|
|
5068
5084
|
- Creating the `Endpoint`:
|
|
5069
5085
|
|
|
5070
|
-
```
|
|
5086
|
+
```ts
|
|
5071
5087
|
const fileUploadEndpoint = defaultEndpointsFactory.build({
|
|
5072
5088
|
method: "post",
|
|
5073
5089
|
type: "upload", // <- new option, required
|
|
@@ -5106,7 +5122,7 @@ after:
|
|
|
5106
5122
|
Please avoid using it for Endpoint outputs.
|
|
5107
5123
|
- Supporting default values of optional properties in OpenAPI/Swagger documentation.
|
|
5108
5124
|
|
|
5109
|
-
```
|
|
5125
|
+
```ts
|
|
5110
5126
|
// example
|
|
5111
5127
|
z.object({
|
|
5112
5128
|
name: z.string().optional().default("John Wick"),
|
|
@@ -5130,7 +5146,7 @@ z.object({
|
|
|
5130
5146
|
- Please use helper function `createConfig()`.
|
|
5131
5147
|
- This way it assigns the correct type for using configuration with `createServer()` and `attachRouting()`.
|
|
5132
5148
|
|
|
5133
|
-
```
|
|
5149
|
+
```ts
|
|
5134
5150
|
// before
|
|
5135
5151
|
const configBefore: ConfigType = {
|
|
5136
5152
|
server: {
|
|
@@ -5237,7 +5253,7 @@ ZodString: # z.string()
|
|
|
5237
5253
|
`.base64()` which also reflected in the generated Swagger / OpenAPI documentation.
|
|
5238
5254
|
You can use it instead of `z.string()` with `createApiResponse()`:
|
|
5239
5255
|
|
|
5240
|
-
```
|
|
5256
|
+
```ts
|
|
5241
5257
|
// before
|
|
5242
5258
|
const fileStreamingEndpointsFactoryBefore = new EndpointsFactory(
|
|
5243
5259
|
createResultHandler({
|
|
@@ -5294,7 +5310,7 @@ const fileStreamingEndpointsFactoryAfter = new EndpointsFactory(
|
|
|
5294
5310
|
facilitate type inference with essentially double nesting of generic types. Typescript does not yet support such
|
|
5295
5311
|
features as `MyGenericType<A<B>>`.
|
|
5296
5312
|
|
|
5297
|
-
```
|
|
5313
|
+
```ts
|
|
5298
5314
|
// before
|
|
5299
5315
|
export const endpointsFactoryBefore = new EndpointsFactory();
|
|
5300
5316
|
// after
|
|
@@ -5303,14 +5319,14 @@ export const endpointsFactoryAfter = new EndpointsFactory(defaultResultHandler);
|
|
|
5303
5319
|
import { defaultEndpointsFactory } from "express-zod-api";
|
|
5304
5320
|
```
|
|
5305
5321
|
|
|
5306
|
-
```
|
|
5322
|
+
```ts
|
|
5307
5323
|
// before
|
|
5308
5324
|
resultHandler: ResultHandler; // optional
|
|
5309
5325
|
// after
|
|
5310
5326
|
errorHandler: ResultHandlerDefinition<any, any>; // optional, default: defaultResultHandler
|
|
5311
5327
|
```
|
|
5312
5328
|
|
|
5313
|
-
```
|
|
5329
|
+
```ts
|
|
5314
5330
|
// Example. Before (v1):
|
|
5315
5331
|
import { EndpointOutput } from "express-zod-api";
|
|
5316
5332
|
|
|
@@ -5353,7 +5369,7 @@ type MyEndpointResponse = EndpointResponse<typeof myEndpointV2>; // => the follo
|
|
|
5353
5369
|
// }
|
|
5354
5370
|
```
|
|
5355
5371
|
|
|
5356
|
-
```
|
|
5372
|
+
```ts
|
|
5357
5373
|
// before
|
|
5358
5374
|
new OpenAPI({
|
|
5359
5375
|
/* ... */
|
|
@@ -5364,7 +5380,7 @@ new OpenAPI({
|
|
|
5364
5380
|
}).getSpecAsYaml();
|
|
5365
5381
|
```
|
|
5366
5382
|
|
|
5367
|
-
```
|
|
5383
|
+
```ts
|
|
5368
5384
|
// before
|
|
5369
5385
|
const myResultHandlerV1: ResultHandler = ({
|
|
5370
5386
|
error,
|
|
@@ -5423,7 +5439,7 @@ const myResultHandlerV2 = createResultHandler({
|
|
|
5423
5439
|
- Ability to specify the endpoint description and export it to the Swagger / OpenAPI specification:
|
|
5424
5440
|
- The feature suggested by [@glitch452](https://github.com/glitch452).
|
|
5425
5441
|
|
|
5426
|
-
```
|
|
5442
|
+
```ts
|
|
5427
5443
|
// example
|
|
5428
5444
|
const endpoint = endpointsFactory.build({
|
|
5429
5445
|
description: "Here is an example description of the endpoint",
|
|
@@ -5433,7 +5449,7 @@ const endpoint = endpointsFactory.build({
|
|
|
5433
5449
|
|
|
5434
5450
|
- Ability to specify either `methods` or `method` property to `.build()`. This is just a more convenient way for a single method case.
|
|
5435
5451
|
|
|
5436
|
-
```
|
|
5452
|
+
```ts
|
|
5437
5453
|
// example
|
|
5438
5454
|
const endpoint = endpointsFactory.build({
|
|
5439
5455
|
method: "get", // same as methods:['get'] before
|
|
@@ -5445,7 +5461,7 @@ const endpoint = endpointsFactory.build({
|
|
|
5445
5461
|
It can also be the same Endpoint that handle multiple methods as well.
|
|
5446
5462
|
This is a solution for the question raised in issue [#29](https://github.com/RobinTail/express-zod-api/issues/29).
|
|
5447
5463
|
|
|
5448
|
-
```
|
|
5464
|
+
```ts
|
|
5449
5465
|
// example of different I/O schemas for /v1/user
|
|
5450
5466
|
const routing: Routing = {
|
|
5451
5467
|
v1: {
|
|
@@ -5490,7 +5506,7 @@ const routing: Routing = {
|
|
|
5490
5506
|
- Zod version is v3.0.0-beta.1.
|
|
5491
5507
|
- Ability to use z.ZodIntersection and z.ZodUnion as an I/O schema for handlers and middlewares.
|
|
5492
5508
|
|
|
5493
|
-
```
|
|
5509
|
+
```ts
|
|
5494
5510
|
// example
|
|
5495
5511
|
const middleware = createMiddleware({
|
|
5496
5512
|
input: z
|
|
@@ -5510,7 +5526,7 @@ const middleware = createMiddleware({
|
|
|
5510
5526
|
|
|
5511
5527
|
- Ability to use `z.transform()` in handler's output schema.
|
|
5512
5528
|
|
|
5513
|
-
```
|
|
5529
|
+
```ts
|
|
5514
5530
|
// example
|
|
5515
5531
|
const endpoint = factory.build({
|
|
5516
5532
|
methods: ["post"],
|
|
@@ -5538,7 +5554,7 @@ const endpoint = factory.build({
|
|
|
5538
5554
|
|
|
5539
5555
|
- `ConfigType` changes:
|
|
5540
5556
|
|
|
5541
|
-
```
|
|
5557
|
+
```ts
|
|
5542
5558
|
// before
|
|
5543
5559
|
export interface ConfigType {
|
|
5544
5560
|
server: {
|
|
@@ -5572,7 +5588,7 @@ export type ConfigType = (
|
|
|
5572
5588
|
|
|
5573
5589
|
- More convenient way to attach routing to your custom express app:
|
|
5574
5590
|
|
|
5575
|
-
```
|
|
5591
|
+
```ts
|
|
5576
5592
|
// before
|
|
5577
5593
|
initRouting({ app, logger, config, routing });
|
|
5578
5594
|
// after
|
|
@@ -5590,7 +5606,7 @@ attachRouting(config, routing);
|
|
|
5590
5606
|
- Ability to specify your custom Winston logger in config.
|
|
5591
5607
|
- `createLogger()` now accepts `LoggerConfig` as an argument:
|
|
5592
5608
|
|
|
5593
|
-
```
|
|
5609
|
+
```ts
|
|
5594
5610
|
// before
|
|
5595
5611
|
createLogger(config);
|
|
5596
5612
|
// after
|
|
@@ -5606,7 +5622,7 @@ createLogger(config.logger);
|
|
|
5606
5622
|
- Zod version is v3.0.0-alpha33.
|
|
5607
5623
|
- The syntax for generating the Swagger/OpenAPI specification has changed:
|
|
5608
5624
|
|
|
5609
|
-
```
|
|
5625
|
+
```ts
|
|
5610
5626
|
// before
|
|
5611
5627
|
generateOpenApi().getSpecAsYaml();
|
|
5612
5628
|
// after
|