@tsed/ajv 8.0.1 → 8.0.3

package/package.json

@@ -2,13 +2,14 @@
   "name": "@tsed/ajv",
   "description": "AJV package for Ts.ED framework",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -27,22 +28,22 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.1",
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/schema": "8.0.1",
-    "@tsed/typescript": "8.0.1",
+    "@tsed/barrels": "8.0.3",
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/schema": "8.0.3",
+    "@tsed/typescript": "8.0.3",
     "ajv": "^8.17.1",
     "eslint": "9.12.0",
     "typescript": "5.4.5",
     "vitest": "2.1.2"
   },
   "peerDependencies": {
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/schema": "8.0.1",
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/schema": "8.0.3",
     "ajv": ">=8.9.0",
     "ajv-errors": ">=3.0.0"
   },

package/readme.md

@@ -1,5 +1,5 @@
 <p style="text-align: center" align="center">
- <a href="https://tsed.io" target="_blank"><img src="https://tsed.io/tsed-og.png" width="200" alt="Ts.ED logo"/></a>
+ <a href="https://tsed.dev" target="_blank"><img src="https://tsed.dev/tsed-og.png" width="200" alt="Ts.ED logo"/></a>
 </p>
 
 <div align="center">
@@ -15,7 +15,7 @@
 
 </div>
 
-A package of Ts.ED framework. See website: https://tsed.io/#/tutorials/ajv
+A package of Ts.ED framework. See website: https://tsed.dev/tutorials/ajv.html
 
 ## Installation
 
@@ -38,11 +38,11 @@ export class Server {}
 
 ### Decorators
 
-See our API documentation on https://tsed.io/#/api/index
+See our API documentation on https://tsed.dev/api/index
 
 ## Example
 
-A model can used on a method controller along with [@BodyParams](http://tsed.io/api/common/filters/decorators/BodyParams.html) or other decorators, and will
+A model can used on a method controller along with [@BodyParams](https://tsed.dev/api/common/filters/decorators/BodyParams.html) or other decorators, and will
 be validated by Ajv.
 
 ```typescript
@@ -98,7 +98,7 @@ export class Server {}
 
 ## Contributors
 
-Please read [contributing guidelines here](https://tsed.io/contributing.html)
+Please read [contributing guidelines here](https://tsed.dev/contributing.html)
 
 <a href="https://github.com/tsedio/tsed/graphs/contributors"><img src="https://opencollective.com/tsed/contributors.svg?width=890" /></a>
 

package/src/decorators/formats.ts

@@ -0,0 +1,24 @@
+import {StoreSet, useDecorators} from "@tsed/core";
+import {Injectable} from "@tsed/di";
+import {AsyncFormatDefinition, FormatDefinition} from "ajv";
+
+export type FormatsOptions = Omit<FormatDefinition<any>, "validate" | "compare"> | Omit<AsyncFormatDefinition<any>, "validate" | "compare">;
+
+/**
+ * Create a new custom formats validator
+ * @param name
+ * @param options
+ * @decorator
+ * @ajv
+ */
+export function Formats(name: string, options: FormatsOptions = {}): ClassDecorator {
+  return useDecorators(
+    Injectable({
+      type: "ajv:formats"
+    }),
+    StoreSet("ajv:formats", {
+      name,
+      options
+    })
+  );
+}

package/src/decorators/keyword.ts

@@ -0,0 +1,26 @@
+import {StoreSet, useDecorators} from "@tsed/core";
+import {Injectable} from "@tsed/di";
+import {JsonSchema} from "@tsed/schema";
+import {AnySchemaObject, KeywordDefinition} from "ajv";
+
+export type KeywordOptions = Partial<Omit<KeywordDefinition, "metaSchema">> & {
+  metaSchema?: AnySchemaObject | JsonSchema;
+};
+
+/**
+ * Create new keyword custom validator
+ * @param options
+ * @decorator
+ * @ajv
+ */
+export function Keyword(options: KeywordOptions): ClassDecorator {
+  return useDecorators(
+    Injectable({
+      type: "ajv:keyword"
+    }),
+    StoreSet("ajv:keyword", {
+      ...options,
+      metaSchema: options.metaSchema && options.metaSchema.toJSON ? options.metaSchema.toJSON() : options.metaSchema
+    })
+  );
+}

package/src/errors/AjvValidationError.ts

@@ -0,0 +1,11 @@
+import {BadRequest} from "@tsed/exceptions";
+
+export class AjvValidationError extends BadRequest {
+  public name: string = "AJV_VALIDATION_ERROR";
+  public errors: any[];
+
+  constructor(message: string, errors: any[] = []) {
+    super(message);
+    this.errors = errors;
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./decorators/formats.js";
+export * from "./decorators/keyword.js";
+export * from "./errors/AjvValidationError.js";
+export * from "./interfaces/FormatsMethods.js";
+export * from "./interfaces/IAjvSettings.js";
+export * from "./interfaces/interfaces.js";
+export * from "./interfaces/KeywordMethods.js";
+export * from "./services/Ajv.js";
+export * from "./services/AjvService.js";
+export * from "./utils/defaultErrorFormatter.js";
+export * from "./utils/getPath.js";

package/src/interfaces/FormatsMethods.ts

@@ -0,0 +1,5 @@
+export interface FormatsMethods<T extends string | number> {
+  compare?: (data1: T, data2: T) => number | undefined;
+
+  validate(data: T): boolean;
+}

package/src/interfaces/IAjvSettings.ts

@@ -0,0 +1,23 @@
+import {ErrorObject, Options} from "ajv";
+
+/**
+ *
+ */
+export interface AjvErrorObject extends ErrorObject {
+  modelName: string;
+  collectionName?: string;
+}
+
+/**
+ *
+ */
+export type ErrorFormatter = (error: AjvErrorObject) => string;
+
+/**
+ *
+ */
+export interface IAjvSettings extends Options {
+  Ajv?: any;
+  errorFormatter?: ErrorFormatter;
+  returnsCoercedValues?: boolean;
+}

package/src/interfaces/KeywordMethods.ts

@@ -0,0 +1,23 @@
+import {AnySchemaObject, KeywordCxt, SchemaObjCxt, ValidateFunction} from "ajv";
+
+export interface AjvDataValidationCtx<T extends string | number = string | number> {
+  dataPath: string;
+  parentData: {[K in T]: any}; // object or array
+  parentDataProperty: T; // string or number
+  rootData: Record<string, any> | any[];
+  dynamicAnchors: {[Ref in string]?: ValidateFunction};
+}
+
+export interface AjvDataValidateFunction {
+  (...args: Parameters<ValidateFunction>): boolean | Promise<any>;
+}
+
+export interface AjvSchemaValidateFunction {
+  (schema: any, data: any, parentSchema?: AnySchemaObject, dataCxt?: AjvDataValidationCtx): boolean | Promise<any>;
+}
+
+export interface KeywordMethods {
+  code?: (cxt: KeywordCxt, ruleType?: string) => void;
+  compile?: (schema: any, parentSchema: AnySchemaObject, it: SchemaObjCxt) => AjvDataValidateFunction;
+  validate?: AjvSchemaValidateFunction | AjvDataValidateFunction;
+}

package/src/interfaces/interfaces.ts

@@ -0,0 +1,10 @@
+import {IAjvSettings} from "./IAjvSettings.js";
+
+declare global {
+  namespace TsED {
+    interface Configuration {
+      // @ts-ignore
+      ajv?: IAjvSettings;
+    }
+  }
+}

package/src/services/Ajv.spec.ts

@@ -0,0 +1,39 @@
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {Ajv} from "ajv";
+
+describe("Ajv", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+  it("should create a new Ajv instance", async () => {
+    const ajv = await PlatformTest.invoke<Ajv>(Ajv);
+
+    expect(ajv).toBeInstanceOf(Ajv);
+    expect(
+      ajv.validate(
+        {
+          type: "object"
+        },
+        {}
+      )
+    ).toEqual(true);
+
+    ajv.validate(
+      {
+        type: "object"
+      },
+      []
+    );
+
+    expect(ajv.errors).toEqual([
+      {
+        instancePath: "",
+        keyword: "type",
+        message: "must be object",
+        params: {
+          type: "object"
+        },
+        schemaPath: "#/type"
+      }
+    ]);
+  });
+});

package/src/services/Ajv.ts

@@ -0,0 +1,84 @@
+import {cleanObject} from "@tsed/core";
+import {constant, inject, injectable, injector, InjectorService, ProviderScope} from "@tsed/di";
+import {Ajv, Format, KeywordDefinition, Options, Vocabulary} from "ajv";
+import AjvErrors from "ajv-errors";
+import AjvFormats from "ajv-formats";
+
+import {FormatsMethods} from "../interfaces/FormatsMethods.js";
+import {IAjvSettings} from "../interfaces/IAjvSettings.js";
+
+function getHandler(key: string, service: any) {
+  if (service[key]) {
+    return service[key].bind(service);
+  }
+}
+
+function getKeywordProviders() {
+  return injector().getProviders("ajv:keyword");
+}
+
+function bindKeywords(): Vocabulary {
+  return getKeywordProviders().map((provider) => {
+    const options = provider.store.get<Omit<KeywordDefinition, "compile">>("ajv:keyword", {})!;
+    const service = inject(provider.token);
+
+    return <KeywordDefinition>cleanObject({
+      coerceTypes: "array",
+      ...options,
+      validate: getHandler("validate", service),
+      compile: getHandler("compile", service),
+      code: getHandler("code", service),
+      macro: getHandler("macro", service)
+    });
+  });
+}
+
+function getFormatsProviders() {
+  return injector().getProviders("ajv:formats");
+}
+
+function getFormats(): {name: string; options: Format}[] {
+  return getFormatsProviders().map((provider) => {
+    const {name, options} = provider.store.get<any>("ajv:formats", {})!;
+    const service = inject<FormatsMethods<any>>(provider.token);
+
+    return {
+      name,
+      options: {
+        ...options,
+        validate: service.validate.bind(service),
+        compare: service.compare?.bind(service)
+      }
+    };
+  });
+}
+
+injectable(Ajv)
+  .scope(ProviderScope.SINGLETON)
+  .factory(() => {
+    const {errorFormatter, keywords = [], ...props} = constant<IAjvSettings>("ajv") || {};
+    const options: Options = {
+      verbose: false,
+      coerceTypes: true,
+      strict: false,
+      keywords: [...keywords, ...bindKeywords()],
+      discriminator: true,
+      allErrors: true,
+      ...props
+    };
+
+    // @ts-ignore
+    const ajv = new Ajv(options);
+
+    // add support for custom error messages
+    // @ts-ignore
+    AjvErrors(ajv);
+    // @ts-ignore
+    AjvFormats(ajv as any);
+
+    getFormats().forEach(({name, options}) => {
+      ajv.addFormat(name, options);
+    });
+
+    return ajv;
+  });

package/src/services/AjvService.spec.ts

@@ -0,0 +1,47 @@
+import {catchAsyncError} from "@tsed/core";
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {object, string} from "@tsed/schema";
+
+import {AjvService} from "./AjvService.js";
+
+describe("AjvService", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+
+  it("should use the function api as schema", async () => {
+    const ajvService = PlatformTest.get<AjvService>(AjvService);
+
+    const error: any = await catchAsyncError(() => ajvService.validate("test", string().minLength(5)));
+    expect(error.errors).toEqual([
+      {
+        data: "test",
+        dataPath: "",
+        instancePath: "",
+        keyword: "minLength",
+        message: "must NOT have fewer than 5 characters",
+        params: {
+          limit: 5
+        },
+        schemaPath: "#/minLength"
+      }
+    ]);
+  });
+
+  it("should use the function api as schema (required)", async () => {
+    const ajvService = PlatformTest.get<AjvService>(AjvService);
+
+    const error: any = await catchAsyncError(() => ajvService.validate({}, object({test: string().required()})));
+    expect(error.errors).toEqual([
+      {
+        dataPath: ".test",
+        instancePath: "",
+        keyword: "required",
+        message: "must have required property 'test'",
+        params: {
+          missingProperty: "test"
+        },
+        schemaPath: "#/required"
+      }
+    ]);
+  });
+});

package/src/services/AjvService.ts

@@ -0,0 +1,116 @@
+import "./Ajv.js";
+
+import {deepClone, getValue, nameOf, prototypeOf, setValue, Type} from "@tsed/core";
+import {constant, inject, injectable} from "@tsed/di";
+import {getJsonSchema, JsonEntityStore, JsonSchema, JsonSchemaObject} from "@tsed/schema";
+import {Ajv, ErrorObject} from "ajv";
+
+import {AjvValidationError} from "../errors/AjvValidationError.js";
+import {AjvErrorObject, ErrorFormatter} from "../interfaces/IAjvSettings.js";
+import {defaultErrorFormatter} from "../utils/defaultErrorFormatter.js";
+import {getPath} from "../utils/getPath.js";
+
+export interface AjvValidateOptions extends Record<string, any> {
+  schema?: JsonSchema | Partial<JsonSchemaObject>;
+  type?: Type<any> | any;
+  collectionType?: Type<any> | any;
+}
+
+export class AjvService {
+  readonly name = "ajv";
+  protected errorFormatter = constant<ErrorFormatter>("ajv.errorFormatter", defaultErrorFormatter);
+  protected returnsCoercedValues = constant<boolean>("ajv.returnsCoercedValues");
+  protected ajv = inject(Ajv);
+
+  async validate(value: any, options: AjvValidateOptions | JsonSchema): Promise<any> {
+    let {schema: defaultSchema, type, collectionType, ...additionalOptions} = this.mapOptions(options);
+
+    const schema = defaultSchema || getJsonSchema(type, {...additionalOptions, customKeys: true});
+
+    if (schema) {
+      const localValue = this.returnsCoercedValues ? value : deepClone(value);
+      const validate = this.ajv.compile(schema);
+
+      const valid = await validate(localValue);
+      const {errors} = validate;
+
+      if (!valid && errors) {
+        throw this.mapErrors(errors, {
+          type,
+          collectionType,
+          async: true,
+          value: localValue
+        });
+      }
+
+      if (this.returnsCoercedValues) {
+        return localValue;
+      }
+    }
+
+    return value;
+  }
+
+  protected mapOptions(options: AjvValidateOptions | JsonSchema): AjvValidateOptions {
+    if (options instanceof JsonSchema) {
+      return {
+        schema: options.toJSON({customKeys: true})
+      };
+    }
+
+    return options;
+  }
+
+  protected mapErrors(errors: ErrorObject[], options: any) {
+    const {type, collectionType, value} = options;
+
+    const message = errors
+      .map((error: AjvErrorObject) => {
+        if (collectionType) {
+          error.collectionName = nameOf(collectionType);
+        }
+
+        const dataPath = getPath(error);
+
+        if (!error.data) {
+          if (dataPath) {
+            error.data = getValue(value, dataPath.replace(/^\./, ""));
+          } else if (error.schemaPath !== "#/required") {
+            error.data = value;
+          }
+        }
+
+        if (dataPath && dataPath.match(/pwd|password|mdp|secret/)) {
+          error.data = "[REDACTED]";
+        }
+
+        if (type) {
+          error.modelName = nameOf(type);
+          error.message = this.mapClassError(error, type);
+        }
+
+        return this.errorFormatter.call(this, error, {});
+      })
+      .join("\n");
+
+    return new AjvValidationError(message, errors);
+  }
+
+  protected mapClassError(error: AjvErrorObject, targetType: Type<any>) {
+    const propertyKey = getValue(error, "params.missingProperty");
+
+    if (propertyKey) {
+      const store = JsonEntityStore.from<JsonEntityStore>(prototypeOf(targetType), propertyKey);
+
+      if (store) {
+        setValue(error, "params.missingProperty", store.name || propertyKey);
+
+        return error.message?.replace(`'${propertyKey}'`, `'${store.name || propertyKey}'`);
+      }
+    }
+
+    return error.message;
+  }
+}
+
+injectable(AjvService).type("validator:service");

package/src/utils/defaultErrorFormatter.spec.ts

@@ -0,0 +1,73 @@
+import {defaultErrorFormatter} from "./defaultErrorFormatter.js";
+
+describe("defaultErrorFormatter", () => {
+  it("should extract data and format error (data = undefined)", () => {
+    expect(
+      defaultErrorFormatter({
+        keyword: "maximum",
+        dataPath: "/length",
+        schemaPath: "#/properties/length/maximum",
+        params: {comparison: "<=", limit: 250},
+        message: "should be <= 250",
+        data: undefined,
+        modelName: "RandomStringModel"
+      } as any)
+    ).toEqual('RandomStringModel.length should be <= 250. Given value: "undefined"');
+  });
+
+  it("should extract data and format error (modelName = '' &  collectionName)", () => {
+    expect(
+      defaultErrorFormatter({
+        keyword: "maximum",
+        dataPath: "/0",
+        schemaPath: "#/properties/length/maximum",
+        params: {comparison: "<=", limit: 250},
+        message: "should be <= 250",
+        data: undefined,
+        modelName: undefined,
+        collectionName: "Array"
+      } as any)
+    ).toEqual('[0] should be <= 250. Given value: "undefined"');
+  });
+
+  it("should extract data and format error (modelName = '')", () => {
+    expect(
+      defaultErrorFormatter({
+        keyword: "maximum",
+        dataPath: "/length",
+        schemaPath: "#/properties/length/maximum",
+        params: {comparison: "<=", limit: 250},
+        message: "should be <= 250",
+        data: undefined,
+        modelName: undefined
+      } as any)
+    ).toEqual('Value.length should be <= 250. Given value: "undefined"');
+  });
+
+  it("should extract data and format error", () => {
+    expect(
+      defaultErrorFormatter({
+        keyword: "maximum",
+        dataPath: "/length",
+        schemaPath: "#/properties/length/maximum",
+        params: {comparison: "<=", limit: 250},
+        message: "should be <= 250",
+        data: 251,
+        modelName: "RandomStringModel"
+      } as any)
+    ).toEqual("RandomStringModel.length should be <= 250. Given value: 251");
+  });
+  it("should extract data and format error(2)", () => {
+    expect(
+      defaultErrorFormatter({
+        instancePath: "/length",
+        schemaPath: "#/properties/length/maximum",
+        keyword: "maximum",
+        params: {comparison: "<=", limit: 250},
+        message: "must be <= 250",
+        data: {length: 251},
+        modelName: "RandomStringModel"
+      } as any)
+    ).toEqual('RandomStringModel.length must be <= 250. Given value: {"length":251}');
+  });
+});

package/src/utils/defaultErrorFormatter.ts

@@ -0,0 +1,33 @@
+import {AjvErrorObject} from "../interfaces/IAjvSettings.js";
+import {getInstancePath, getPath} from "./getPath.js";
+
+export function defaultErrorFormatter(error: AjvErrorObject & {dataPath: string}) {
+  const value = JSON.stringify(error.data === undefined ? "undefined" : error.data);
+  const join = (list: any[]): string => list.filter(Boolean).join("").trim();
+
+  const [, indexPath, ...paths] = getInstancePath(error).split(".");
+  const deepPaths = paths.length ? "." + paths.join(".") : "";
+
+  error.dataPath = getPath(error);
+
+  if (error.collectionName) {
+    const modelName = error.modelName || "";
+
+    switch (error.collectionName) {
+      case "Array":
+        return join([`${modelName}[${indexPath}]${deepPaths}`, ` ${error.message}. Given value: ${value}`]);
+      case "Map":
+        return join([`Map<${indexPath}, ${modelName}>${deepPaths}`, ` ${error.message}. Given value: ${value}`]);
+      case "Set":
+        return join([`Set<${indexPath}, ${modelName}>${deepPaths}`, ` ${error.message}. Given value: ${value}`]);
+    }
+  }
+
+  return join([
+    !error.modelName && "Value",
+    `${error.modelName || ""}`,
+    (!error?.params?.missingProperty && error.dataPath) ||
+      (error?.params?.missingProperty && (error.instancePath || "").replace(/\//g, ".")),
+    ` ${error.message}. Given value: ${value}`
+  ]);
+}

package/src/utils/getPath.ts

@@ -0,0 +1,13 @@
+import {getValue} from "@tsed/core";
+
+export function getPath(error: any) {
+  if (error.params && error.params.missingProperty) {
+    return `.${error.params.missingProperty}`;
+  }
+
+  return getInstancePath(error);
+}
+
+export function getInstancePath(error: any) {
+  return getValue(error, "dataPath", getValue(error, "instancePath", "")).replace(/\//gi, ".");
+}