-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #8 from ty-ras/issue/3-add-jsdoc
Issue/3 add jsdoc
- Loading branch information
Showing
31 changed files
with
2,054 additions
and
1,422 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,6 +1,6 @@ | ||
| { | ||
| "name": "@ty-ras/data-backend-zod", | ||
| "version": "0.13.0", | ||
| "version": "1.0.0", | ||
| "author": { | ||
| "name": "Stanislav Muhametsin", | ||
| "email": "[email protected]", | ||
|
|
@@ -31,38 +31,44 @@ | |
| } | ||
| }, | ||
| "dependencies": { | ||
| "@ty-ras/data-zod": "0.13.0", | ||
| "@ty-ras/endpoint-spec": "0.13.0" | ||
| "@ty-ras/data-zod": "^1.0.0", | ||
| "@ty-ras/endpoint-spec": "^1.0.0" | ||
| }, | ||
| "peerDependencies": { | ||
| "raw-body": "^2.5.1" | ||
| }, | ||
| "devDependencies": { | ||
| "@babel/core": "7.19.3", | ||
| "@babel/eslint-parser": "7.19.1", | ||
| "@types/node": "18.7.18", | ||
| "@typescript-eslint/eslint-plugin": "5.38.0", | ||
| "@typescript-eslint/parser": "5.38.0", | ||
| "ava": "5.0.1", | ||
| "c8": "7.12.0", | ||
| "eslint": "8.23.1", | ||
| "eslint-config-prettier": "8.5.0", | ||
| "@babel/core": "7.21.5", | ||
| "@babel/eslint-parser": "7.21.3", | ||
| "@typescript-eslint/eslint-plugin": "5.59.2", | ||
| "@typescript-eslint/parser": "5.59.2", | ||
| "@types/node": "18.16.3", | ||
| "ava": "5.2.0", | ||
| "c8": "7.13.0", | ||
| "eslint": "8.39.0", | ||
| "eslint-plugin-jsdoc": "43.1.1", | ||
| "eslint-plugin-path-import-extension": "0.9.0", | ||
| "eslint-plugin-type-only-import": "0.9.0", | ||
| "eslint-config-prettier": "8.8.0", | ||
| "eslint-plugin-prettier": "4.2.1", | ||
| "eslint-plugin-sonarjs": "0.15.0", | ||
| "prettier": "2.7.1", | ||
| "eslint-plugin-sonarjs": "0.19.0", | ||
| "prettier": "2.8.8", | ||
| "raw-body": "2.5.1", | ||
| "ts-node": "10.9.1", | ||
| "typescript": "4.8.4", | ||
| "typescript": "5.0.4", | ||
| "zod": "3.20.6" | ||
| }, | ||
| "scripts": { | ||
| "build:run": "yarn run lint && yarn run tsc", | ||
| "build:ci": "yarn run clear-build-artifacts && yarn run compile-d-ts-files && yarn run tsc --outDir ./dist-esm && yarn run tsc --module CommonJS --outDir ./dist-cjs && yarn run format-output-files", | ||
| "build:ci": "yarn run clear-build-artifacts && yarn run compile-d-ts-files && yarn run tsc --outDir ./dist-esm && yarn run tsc --module CommonJS --outDir ./dist-cjs && yarn run remove-empty-js-files && yarn run generate-stub-package-json-for-cjs && yarn run format-output-files", | ||
| "clear-build-artifacts": "rm -rf dist dist-ts dist-cjs dist-esm build", | ||
| "compile-d-ts-files": "yarn run tsc --removeComments false --emitDeclarationOnly --declaration --declarationDir ./dist-ts && yarn run copy-d-ts-files && yarn run tsc:plain --project tsconfig.out.json", | ||
| "copy-d-ts-files": "find ./src -mindepth 1 -maxdepth 1 -name '*.d.ts' -exec cp {} ./dist-ts +", | ||
| "format-output-files": "find dist-ts -name '*.ts' -type f -exec sh -c \"echo '/* eslint-disable */\n/* eslint-enable prettier/prettier */'\"' | cat - $1 > $1.tmp && mv $1.tmp $1' -- {} \\; && eslint --no-eslintrc --config '.eslintrc.output.ts.cjs' --fix './dist-ts/**/*.ts' && eslint --no-eslintrc --config '.eslintrc.output.cjs' --fix 'dist-cjs/*js' 'dist-esm/*js'", | ||
| "compile-d-ts-files": "yarn run tsc --removeComments false --emitDeclarationOnly --declaration --declarationDir ./dist-ts && yarn run tsc:plain --project tsconfig.out.json", | ||
| "format-output-files": "yarn run format-output-files-ts && yarn run format-output-files-js", | ||
| "format-output-files-ts": "eslint --no-eslintrc --config '.eslintrc.out-ts.cjs' --fix --fix-type layout './dist-ts/**/*.ts'", | ||
| "format-output-files-js": "eslint --no-eslintrc --config '.eslintrc.out.cjs' --fix 'dist-cjs/**/*js' 'dist-esm/**/*js'", | ||
| "generate-stub-package-json-for-cjs": "../scripts/generate-stub-package-json.cjs", | ||
| "lint": "eslint ./src --ext .ts,.tsx", | ||
| "remove-empty-js-files": "../scripts/remove-empty-js-files.cjs", | ||
| "tsc": "tsc --project tsconfig.build.json", | ||
| "tsc:plain": "tsc", | ||
| "test:coverage": "c8 --temp-directory /tmp ava", | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,145 @@ | ||
| import * as dataBE from "@ty-ras/data-backend"; | ||
| /** | ||
| * @file This file contains code to create generic TyRAS callbacks from 'native' `zod` validators, for HTTP request and response body validation. | ||
| */ | ||
|
|
||
| import * as data from "@ty-ras/data-backend"; | ||
| import * as common from "@ty-ras/data-zod"; | ||
| import * as rawbody from "raw-body"; | ||
| import type * as protocol from "./protocol.types"; | ||
|
|
||
| // We only support json things for zod validation. | ||
| /** | ||
| * This is the default MIME type used to serialize/deserialize response/request bodies. | ||
| * Its value is `application/json`. | ||
| */ | ||
| export const CONTENT_TYPE = "application/json" as const; | ||
|
|
||
| export const requestBody = <T>( | ||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorRequestInputSpec} for validating request body, wrapping native `zod` {@link common.Decoder}, without additional options. | ||
| * @param validation The {@link common.Decoder} responsible for validating the deserialized and and JSON-parsed request body. | ||
| * @returns The {@link data.DataValidatorRequestInputSpec} that can be passed to TyRAS functions as request body validator. | ||
| */ | ||
| export function requestBody<T>( | ||
| validation: common.Decoder<T>, | ||
| ): data.DataValidatorRequestInputSpec< | ||
| T, | ||
| protocol.InputValidatorSpec<T, typeof CONTENT_TYPE> | ||
| >; | ||
|
|
||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorRequestInputSpec} for validating request body, wrapping native `zod` {@link common.Decoder}, with additional options. | ||
| * @param validation The {@link common.Decoder} responsible for validating the deserialized and and JSON-parsed request body. | ||
| * @param opts The {@link RequestBodyCreationOptions}, without custom content type specifier. | ||
| * @returns The {@link data.DataValidatorRequestInputSpec} that can be passed to TyRAS functions as request body validator. | ||
| */ | ||
| export function requestBody<T>( | ||
| validation: common.Decoder<T>, | ||
| opts: RequestBodyCreationOptions & { contentType?: never }, | ||
| ): data.DataValidatorRequestInputSpec< | ||
| T, | ||
| protocol.InputValidatorSpec<T, typeof CONTENT_TYPE> | ||
| >; | ||
|
|
||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorRequestInputSpec} for validating request body, wrapping native `zod` {@link common.Decoder}, with additional options, including content type. | ||
| * @param validation The {@link common.Decoder} responsible for validating the deserialized and and JSON-parsed request body. | ||
| * @param opts The {@link RequestBodyCreationOptions}, along with custom content type specifier. | ||
| * @returns The {@link data.DataValidatorRequestInputSpec} that can be passed to TyRAS functions as request body validator. | ||
| */ | ||
| export function requestBody<T, TContentType extends string>( | ||
| validation: common.Decoder<T>, | ||
| opts: RequestBodyCreationOptions & { contentType: TContentType }, | ||
| ): data.DataValidatorRequestInputSpec< | ||
| T, | ||
| protocol.InputValidatorSpec<T, TContentType> | ||
| >; | ||
|
|
||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorRequestInputSpec} for validating request body, wrapping native `zod` {@link common.Decoder}, with additional options, possibly including content type. | ||
| * @param validation The {@link common.Decoder} responsible for validating the deserialized and and JSON-parsed request body. | ||
| * @param opts The {@link RequestBodyCreationOptions}, possibly with custom content type specifier. | ||
| * @returns The {@link data.DataValidatorRequestInputSpec} that can be passed to TyRAS functions as request body validator. | ||
| */ | ||
| export function requestBody<T, TContentType extends string>( | ||
| validation: common.Decoder<T>, | ||
| strictContentType = false, | ||
| opts?: rawbody.Options, | ||
| ): dataBE.DataValidatorRequestInputSpec<T, InputValidatorSpec<T>> => | ||
| dataBE.requestBodyGeneric( | ||
| opts?: RequestBodyCreationOptions & { contentType?: TContentType }, | ||
| ): data.DataValidatorRequestInputSpec< | ||
| T, | ||
| protocol.InputValidatorSpec<T, TContentType> | ||
| > { | ||
| return data.requestBodyGeneric( | ||
| validation, | ||
| common.plainValidator(validation), | ||
| CONTENT_TYPE, | ||
| strictContentType, | ||
| common.fromDecoder(validation), | ||
| opts?.contentType ?? CONTENT_TYPE, | ||
| opts?.strictContentType === true, | ||
| async (readable, encoding) => { | ||
| const bufferOrString = await rawbody.default(readable, { | ||
| encoding: opts?.encoding ?? encoding, | ||
| ...(opts ?? {}), | ||
| encoding: opts?.opts?.encoding ?? encoding, | ||
| ...(opts?.opts ?? {}), | ||
| }); | ||
| return bufferOrString instanceof Buffer | ||
| ? bufferOrString.toString() | ||
| : bufferOrString; | ||
| }, | ||
| ); | ||
| } | ||
|
|
||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorResponseOutputSpec} for validating response body, wrapping native `zod` {@link common.Encoder}. | ||
| * @param validation The {@link common.Encoder} responsible for validating the response body before it is stringified and serialized. | ||
| * @returns The {@link data.DataValidatorResponseOutputSpec} that can be passed to TyRAS functions as response body validator. | ||
| */ | ||
| export function responseBody<TOutput, TSerialized>( | ||
| validation: common.Encoder<TOutput, TSerialized>, | ||
| ): data.DataValidatorResponseOutputSpec< | ||
| TOutput, | ||
| protocol.OutputValidatorSpec<TOutput, TSerialized, typeof CONTENT_TYPE> | ||
| >; | ||
|
|
||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorResponseOutputSpec} for validating response body, wrapping native `zod` {@link common.Encoder}. | ||
| * @param validation The {@link common.Encoder} responsible for validating the response body before it is stringified and serialized. | ||
| * @param contentType The content type to use. | ||
| * @returns The {@link data.DataValidatorResponseOutputSpec} that can be passed to TyRAS functions as response body validator. | ||
| */ | ||
| export function responseBody<TOutput, TSerialized, TContentType extends string>( | ||
| validation: common.Encoder<TOutput, TSerialized>, | ||
| contentType: TContentType, | ||
| ): data.DataValidatorResponseOutputSpec< | ||
| TOutput, | ||
| protocol.OutputValidatorSpec<TOutput, TSerialized, TContentType> | ||
| >; | ||
|
|
||
| export const responseBody = <TOutput, TSerialized>( | ||
| /** | ||
| * Creates a new generic TyRAS {@link data.DataValidatorResponseOutputSpec} for validating response body, wrapping native `zod` {@link common.Encoder}. | ||
| * @param validation The {@link common.Encoder} responsible for validating the response body before it is stringified and serialized. | ||
| * @param contentType The possible content type to use. | ||
| * @returns The {@link data.DataValidatorResponseOutputSpec} that can be passed to TyRAS functions as response body validator. | ||
| */ | ||
| export function responseBody<TOutput, TSerialized, TContentType extends string>( | ||
| validation: common.Encoder<TOutput, TSerialized>, | ||
| ): dataBE.DataValidatorResponseOutputSpec< | ||
| contentType?: TContentType, | ||
| ): data.DataValidatorResponseOutputSpec< | ||
| TOutput, | ||
| OutputValidatorSpec<TOutput, TSerialized> | ||
| > => | ||
| dataBE.responseBodyGeneric( | ||
| protocol.OutputValidatorSpec<TOutput, TSerialized, TContentType> | ||
| > { | ||
| return data.responseBodyGeneric( | ||
| validation, | ||
| common.plainValidatorEncoder(validation), | ||
| CONTENT_TYPE, | ||
| common.fromEncoder(validation), | ||
| contentType ?? CONTENT_TYPE, | ||
| ); | ||
| } | ||
|
|
||
| export type InputValidatorSpec<TData> = { | ||
| [CONTENT_TYPE]: common.Decoder<TData>; | ||
| }; | ||
| /** | ||
| * This interface contains data that can be specified when using {@link requestBody}. | ||
| */ | ||
| export interface RequestBodyCreationOptions { | ||
| /** | ||
| * If set to `true`, the returned request body validator will throw an error if request's `Content-Type` header does not match exactly the given content type (or {@link CONTENT_TYPE} if not given). | ||
| */ | ||
| strictContentType?: boolean; | ||
|
|
||
| export type OutputValidatorSpec<TOutput, TSerialized> = { | ||
| [CONTENT_TYPE]: common.Encoder<TOutput, TSerialized>; | ||
| }; | ||
| /** | ||
| * The option {@link rawbody.Options} to use when deserializing the request body. | ||
| */ | ||
| opts?: rawbody.Options; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.