@eggjs/ajv-plugin 4.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @eggjs/tegg-ajv-plugin
+
+[![NPM version][npm-image]][npm-url]
+[![Known Vulnerabilities][snyk-image]][snyk-url]
+[![npm download][download-image]][download-url]
+[![Node.js Version](https://img.shields.io/node/v/@eggjs/tegg-ajv-plugin.svg?style=flat)](https://nodejs.org/en/download/)
+
+[npm-image]: https://img.shields.io/npm/v/@eggjs/tegg-ajv-plugin.svg?style=flat-square
+[npm-url]: https://npmjs.org/package/@eggjs/tegg-ajv-plugin
+[snyk-image]: https://snyk.io/test/npm/@eggjs/tegg-ajv-plugin/badge.svg?style=flat-square
+[snyk-url]: https://snyk.io/test/npm/@eggjs/tegg-ajv-plugin
+[download-image]: https://img.shields.io/npm/dm/@eggjs/tegg-ajv-plugin.svg?style=flat-square
+[download-url]: https://npmjs.org/package/@eggjs/tegg-ajv-plugin
+
+参考 [@eggjs/typebox-validate](https://github.com/eggjs/egg/tree/next/plugins/typebox-validate) 的最佳实践，结合 ajv + typebox，只需要定义一次参数类型和规则，就能同时拥有参数校验和类型定义（完整的 ts 类型提示）。
+
+## egg 模式
+
+### Install
+
+```shell
+# tegg 注解
+npm i --save @eggjs/tegg
+# tegg 插件
+npm i --save @eggjs/tegg-plugin
+# tegg ajv 插件
+npm i --save @eggjs/tegg-ajv-plugin
+```
+
+### Prepare
+
+```json
+// tsconfig.json
+{
+  "extends": "@eggjs/tsconfig"
+}
+```
+
+### Config
+
+```js
+// config/plugin.js
+exports.tegg = {
+  package: '@eggjs/tegg-plugin',
+  enable: true,
+};
+
+exports.teggAjv = {
+  package: '@eggjs/tegg-ajv-plugin',
+  enable: true,
+};
+```
+
+## standalone 模式
+
+### Install
+
+```shell
+# tegg 注解
+npm i --save @eggjs/tegg
+# tegg ajv 插件
+npm i --save @eggjs/tegg-ajv-plugin
+```
+
+### Prepare
+
+```json
+// tsconfig.json
+{
+  "extends": "@eggjs/tsconfig"
+}
+```
+
+## Usage
+
+1、定义入参校验 Schema
+
+使用 typebox 定义，会内置到 tegg 导出
+
+```ts
+import { Type, TransformEnum } from '@eggjs/tegg/ajv';
+
+const SyncPackageTaskSchema = Type.Object({
+  fullname: Type.String({
+    transform: [TransformEnum.trim],
+    maxLength: 100,
+  }),
+  tips: Type.String({
+    transform: [TransformEnum.trim],
+    maxLength: 1024,
+  }),
+  skipDependencies: Type.Boolean(),
+  syncDownloadData: Type.Boolean(),
+  // force sync immediately, only allow by admin
+  force: Type.Boolean(),
+  // sync history version
+  forceSyncHistory: Type.Boolean(),
+  // source registry
+  registryName: Type.Optional(Type.String()),
+});
+```
+
+2、从校验 Schema 生成静态的入参类型
+
+```ts
+import { Static } from '@eggjs/tegg/ajv';
+
+type SyncPackageTaskType = Static<typeof SyncPackageTaskSchema>;
+```
+
+3、在 Controller 中使用入参类型和校验 Schema
+
+注入全局单例 ajv，调用 `ajv.validate(XxxSchema, params)` 进行参数校验，参数校验失败会直接抛出 `AjvInvalidParamError` 异常，
+tegg 会自动返回相应的错误响应给客户端。
+
+```ts
+import { Inject, HTTPController, HTTPMethod, HTTPMethodEnum, HTTPBody } from '@eggjs/tegg';
+import { Ajv, Type, Static, TransformEnum } from '@eggjs/tegg/ajv';
+
+const SyncPackageTaskSchema = Type.Object({
+  fullname: Type.String({
+    transform: [TransformEnum.trim],
+    maxLength: 100,
+  }),
+  tips: Type.String({
+    transform: [TransformEnum.trim],
+    maxLength: 1024,
+  }),
+  skipDependencies: Type.Boolean(),
+  syncDownloadData: Type.Boolean(),
+  // force sync immediately, only allow by admin
+  force: Type.Boolean(),
+  // sync history version
+  forceSyncHistory: Type.Boolean(),
+  // source registry
+  registryName: Type.Optional(Type.String()),
+});
+
+type SyncPackageTaskType = Static<typeof SyncPackageTaskSchema>;
+
+@HTTPController()
+export class HelloController {
+  private readonly ajv: Ajv;
+
+  @HTTPMethod({
+    method: HTTPMethodEnum.POST,
+    path: '/sync',
+  })
+  async sync(@HTTPBody() task: SyncPackageTaskType) {
+    this.ajv.validate(SyncPackageTaskSchema, task);
+    return {
+      task,
+    };
+  }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/Ajv.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./lib/Ajv.js";
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsY0FBYyxjQUFjLENBQUMifQ==

package/dist/lib/Ajv.d.ts

@@ -0,0 +1,13 @@
+import { type Schema } from 'ajv/dist/2019.js';
+import { type Ajv as IAjv, AjvInvalidParamError } from '@eggjs/ajv-decorator';
+export declare class Ajv implements IAjv {
+    #private;
+    static InvalidParamErrorClass: typeof AjvInvalidParamError;
+    protected _init(): void;
+    /**
+     * Validate data with typebox Schema.
+     *
+     * If validate fail, with throw `Ajv.InvalidParamErrorClass`
+     */
+    validate(schema: Schema, data: unknown): void;
+}

package/dist/lib/Ajv.js

@@ -0,0 +1,73 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var Ajv_1;
+import { Ajv2019 } from 'ajv/dist/2019.js';
+import addFormats from '@eggjs/ajv-formats';
+import keyWords from '@eggjs/ajv-keywords';
+import { AjvInvalidParamError } from '@eggjs/ajv-decorator';
+import { SingletonProto, AccessLevel } from '@eggjs/core-decorator';
+import { LifecycleInit } from '@eggjs/lifecycle';
+let Ajv = class Ajv {
+    static { Ajv_1 = this; }
+    static InvalidParamErrorClass = AjvInvalidParamError;
+    #ajvInstance;
+    _init() {
+        this.#ajvInstance = new Ajv2019();
+        // @ts-expect-error ajv-keywords is not typed
+        keyWords(this.#ajvInstance, 'transform');
+        // @ts-expect-error ajv-formats is not typed
+        addFormats(this.#ajvInstance, [
+            'date-time',
+            'time',
+            'date',
+            'email',
+            'hostname',
+            'ipv4',
+            'ipv6',
+            'uri',
+            'uri-reference',
+            'uuid',
+            'uri-template',
+            'json-pointer',
+            'relative-json-pointer',
+            'regex',
+        ])
+            .addKeyword('kind')
+            .addKeyword('modifier');
+    }
+    /**
+     * Validate data with typebox Schema.
+     *
+     * If validate fail, with throw `Ajv.InvalidParamErrorClass`
+     */
+    validate(schema, data) {
+        const result = this.#ajvInstance.validate(schema, data);
+        if (!result) {
+            throw new Ajv_1.InvalidParamErrorClass('Validation Failed', {
+                errorData: data,
+                currentSchema: JSON.stringify(schema),
+                errors: this.#ajvInstance.errors,
+            });
+        }
+    }
+};
+__decorate([
+    LifecycleInit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], Ajv.prototype, "_init", null);
+Ajv = Ajv_1 = __decorate([
+    SingletonProto({
+        accessLevel: AccessLevel.PUBLIC,
+    })
+], Ajv);
+export { Ajv };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiQWp2LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2xpYi9BanYudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7OztBQUFBLE9BQU8sRUFBZSxPQUFPLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUN4RCxPQUFPLFVBQVUsTUFBTSxvQkFBb0IsQ0FBQztBQUM1QyxPQUFPLFFBQVEsTUFBTSxxQkFBcUIsQ0FBQztBQUMzQyxPQUFPLEVBQW9CLG9CQUFvQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDOUUsT0FBTyxFQUFFLGNBQWMsRUFBRSxXQUFXLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNwRSxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFLMUMsSUFBTSxHQUFHLEdBQVQsTUFBTSxHQUFHOztJQUNkLE1BQU0sQ0FBQyxzQkFBc0IsR0FBZ0Msb0JBQW9CLENBQUM7SUFFbEYsWUFBWSxDQUFVO0lBR1osS0FBSztRQUNiLElBQUksQ0FBQyxZQUFZLEdBQUcsSUFBSSxPQUFPLEVBQUUsQ0FBQztRQUNsQyw2Q0FBNkM7UUFDN0MsUUFBUSxDQUFDLElBQUksQ0FBQyxZQUFZLEVBQUUsV0FBVyxDQUFDLENBQUM7UUFDekMsNENBQTRDO1FBQzVDLFVBQVUsQ0FBQyxJQUFJLENBQUMsWUFBWSxFQUFFO1lBQzVCLFdBQVc7WUFDWCxNQUFNO1lBQ04sTUFBTTtZQUNOLE9BQU87WUFDUCxVQUFVO1lBQ1YsTUFBTTtZQUNOLE1BQU07WUFDTixLQUFLO1lBQ0wsZUFBZTtZQUNmLE1BQU07WUFDTixjQUFjO1lBQ2QsY0FBYztZQUNkLHVCQUF1QjtZQUN2QixPQUFPO1NBQ1IsQ0FBQzthQUNDLFVBQVUsQ0FBQyxNQUFNLENBQUM7YUFDbEIsVUFBVSxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQzVCLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsUUFBUSxDQUFDLE1BQWMsRUFBRSxJQUFhO1FBQ3BDLE1BQU0sTUFBTSxHQUFHLElBQUksQ0FBQyxZQUFZLENBQUMsUUFBUSxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsQ0FBQztRQUN4RCxJQUFJLENBQUMsTUFBTSxFQUFFLENBQUM7WUFDWixNQUFNLElBQUksS0FBRyxDQUFDLHNCQUFzQixDQUFDLG1CQUFtQixFQUFFO2dCQUN4RCxTQUFTLEVBQUUsSUFBSTtnQkFDZixhQUFhLEVBQUUsSUFBSSxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUM7Z0JBQ3JDLE1BQU0sRUFBRSxJQUFJLENBQUMsWUFBWSxDQUFDLE1BQU87YUFDbEMsQ0FBQyxDQUFDO1FBQ0wsQ0FBQztJQUNILENBQUM7O0FBdkNTO0lBRFQsYUFBYSxFQUFFOzs7O2dDQXdCZjtBQTdCVSxHQUFHO0lBSGYsY0FBYyxDQUFDO1FBQ2QsV0FBVyxFQUFFLFdBQVcsQ0FBQyxNQUFNO0tBQ2hDLENBQUM7R0FDVyxHQUFHLENBOENmIn0=

package/dist/types.d.ts

@@ -0,0 +1 @@
+import '@eggjs/tegg-plugin/types';

package/dist/types.js

@@ -0,0 +1,2 @@
+import '@eggjs/tegg-plugin/types';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTywwQkFBMEIsQ0FBQyJ9

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@eggjs/ajv-plugin",
+  "eggPlugin": {
+    "name": "teggAjv",
+    "strict": false,
+    "dependencies": [
+      "tegg"
+    ]
+  },
+  "eggModule": {
+    "name": "teggAjv"
+  },
+  "version": "4.0.0-beta.0",
+  "description": "ajv plugin for egg and tegg",
+  "keywords": [
+    "egg",
+    "plugin",
+    "typescript",
+    "module",
+    "tegg",
+    "ajv"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./lib/Ajv": "./dist/lib/Ajv.js",
+    "./types": "./dist/types.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/eggjs/egg/tree/next/tegg/plugin/ajv",
+  "bugs": {
+    "url": "https://github.com/eggjs/egg/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:eggjs/egg.git",
+    "directory": "tegg/plugin/ajv"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "@eggjs/ajv-formats": "^3.0.1",
+    "@eggjs/ajv-keywords": "^5.1.0",
+    "ajv": "^8.8.2",
+    "@eggjs/ajv-decorator": "4.0.0-beta.29",
+    "@eggjs/core-decorator": "4.0.0-beta.29",
+    "@eggjs/lifecycle": "4.0.0-beta.29"
+  },
+  "peerDependencies": {
+    "egg": "4.1.0-beta.29"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "tsdown": "0.15.9",
+    "typescript": "^5.9.3",
+    "unplugin-unused": "^0.5.4",
+    "@eggjs/tegg": "4.0.0-beta.29",
+    "@eggjs/tegg-config": "4.0.0-beta.29",
+    "@eggjs/tegg-controller-plugin": "4.0.0-beta.29",
+    "@eggjs/mock": "7.0.0-beta.29",
+    "@eggjs/tegg-plugin": "4.0.0-beta.29",
+    "egg": "4.1.0-beta.29"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "clean": "rimraf dist *.tsbuildinfo",
+    "build": "tsdown && npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}