# ts-transformer-ajv

> TypeScript transformer to validate types in runtime using JSON Schema and AJV

Latest version **1.0.2** (published 2020-04-26) · GPL-3.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install ts-transformer-ajv
pnpm add ts-transformer-ajv
yarn add ts-transformer-ajv
bun add ts-transformer-ajv
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2020-04-26 |
| First published | 2020-04-26 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 23.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Rogério Munhoz |
| Maintainers | rjmunhoz |
| Keywords | typescript, ttypescript, json-schema, transformer, transform, validation, json |

## Links

- npm: https://www.npmjs.com/package/ts-transformer-ajv
- Repository: https://github.com/rjmunhoz/ts-transformer-ajv
- Homepage: https://github.com/rjmunhoz/ts-transformer-ajv#readme
- Issues: https://github.com/rjmunhoz/ts-transformer-ajv/issues
- npm.io page: https://npm.io/package/ts-transformer-ajv

## Dependencies (5)

- [json5](https://npm.io/package/json5.md) ^2.1.2
- [@types/json5](https://npm.io/package/@types/json5.md) 0.0.30
- [@types/express](https://npm.io/package/@types/express.md) ^4.17.3
- [@expresso/validator](https://npm.io/package/@expresso/validator.md) ^1.1.5
- [typescript-json-schema](https://npm.io/package/typescript-json-schema.md) ^0.42.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.0.2 (latest) — 2020-04-26
- 1.0.1 — 2020-04-26
- 1.0.0 — 2020-04-26

## README

ts-transformer-ajv
---

This is a custom typescript transformer wich allows you to use [AJV](https://npmjs.org/package/ajv) easilly, without having to wtie both TS type definitinos and JSON Schema definitions.

## Installation

You'll need to install [AJV](https://npmjs.org/package/ajv) to use this.

Also, you'll need a way to load the transformer. I recommend using [ttypescript](https://npmjs.org/package/ttypescript),
so the instructions below assume you are using that.

From the terminal, run these commands:

- `npm install -D ttypescript ts-transformer-ajv`
- `npm install ajv`

On your tsconfig.json, add a new property and fill it like this:

```json5
{
  "compilerOptions": {
    // ...
    "plugins": [
      { "transform": "ts-transformer-ajv" }
    ]
  },
}
```

Now, instead of running `tsc` to build your app, just use `ttsc`, and *voilà*!

## Usage

ts-transform-ajv offers you two functions to validate objects agaist a given type: the compiled validator function, and an inline validate function. Their usage is described below:

### Compiled validator function - `getValidatorFromType`

This uses AJV's `compile` function to generate a static function that validates objects against the generated JSON Schema. Use it as follows:

```typescript
import { getValidatorFromType } from 'ts-transformer-ajv'

type LoginParams = {
    app: string
}

type LoginBody = {
    username: string
    password: string
}

type LoginQuery = {
    id: boolean
}

type ValidAnswer = {
    answer: number
}

const validateParams = getValidatorFromType<LoginParams>({ required: true }, { useDefaults: true })
const validateBody = getValidatorFromType<LoginBody>({ required: true })
const validateQuery = getValidatorFromType<LoginQuery>({ required: true })

validateParams({ app: 'teste' })
validateBody({ username: 'string', password: 'string' })
validateQuery({ id: false })
```

The return value is the result of calling `ajv.compile`, so you can check either the typings, or [AJV's documentation](https://npmjs.org/package/ajv) to see what the API looks like.

### Inline validation - `validateTypeWithAjv`

Allows you to validate an object against a given type using `ajv.validate`. Since we're now calling the validate function directly, the return value is an object with the following type:

```typescript
type ValidationResult = {
    isValid: boolean,
    errors: Ajv.ValidateFunction['errors']
}
```

You can use this function like so:

```typescript
import util from 'util'
import readline from 'readline'
import { validateTypeWithAjv } from 'ts-transformer-ajv'

type LoginParams = {
    app: string
}

type LoginBody = {
    username: string
    password: string
}

type LoginQuery = {
    id: boolean
}

type ValidAnswer = {
    answer: number
}

const { isValid: isParamsValid, errors: paramErrors } = validateTypeWithAjv<LoginParams>({ app: 'test' })
const { isValid: isBodyValid, errors: bodyErrors } = validateTypeWithAjv<LoginBody>({ username: 'string', password: 'string' })
const { isValid: isQueryValid, errors: queryErrors } = validateTypeWithAjv<LoginQuery>({}, { required: true })

const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
})

rl.question('Type a number: ', answer => {
    const { isValid, errors } = validateTypeWithAjv<ValidAnswer>({ answer }, { coerceTypes: true })

    if (isValid) {
        rl.close()
        return console.log('Nice number!')
    }

    rl.close()
    console.log(util.inspect(errors))
    console.log('Hm... You don\'t know numbers very wel, do you? :think:')
})
```

## Configuration

You can pass both functions two configuration objects: an object defining options for [typescript-json-schema](https://npmjs.org/package/typescript-json-schema), and another one passing options to [AJV](https://npmjs.org/package/ajv).
Please, refer to their documentations to check what are the available options and what they do.

To acomplish typescript-like behaviour, you must pass `{ required: true }` to the schema generator options, so it'll consider non-optional keys in the type as required.

## Extra JSON Schema Properties

It's true that JSON Schema supports much more validation options than typescript does. For example: it accepts `max` and `min` for numbers
or `maxLength` and `minLength` for strings.

To solve that problem, `typescript-json-schema` uses JSDoc annotations. You can check them out on [typescript-json-schema's documentation](https://www.npmjs.com/package/typescript-json-schema#annotations).

## Contributing

From the terminal, run the following steps (assuming you've got `node` and `npm` figured out):

- `git clone git@github.com:rjmunhoz/ts-transformer-ajv`
- `cd ts-transformer-ajv`
- `npm i`

After that, you're ready to make your changes.

Use [gitmoji](https://github.com/carloscuesta/gitmoji) on your commit titles, please :)

After making your changes, run `npm run:build` to see if everything is OK.

~~After that, run `npm test` to run the test files~~
Automated tests are broken until the testing library is updated.
For now, please `cd` into the `usage` folder, run `npm i && npm run go` and make sure everything is working as expected.

Commit, push, and open a Pull Request

## Thanks

This project was only possible because of the effort the community has put on writing awesome
documentation, tools and examples for the TypeScript Transformer API.

During development, I depended largely on the instructions and documentation
found on the [Typescript Transformer Handbook](https://github.com/madou/typescript-transformer-handbook) by [madou](https://github.com/madou/).

Also, the inspiration to creating this came from [ts-transform-json-schema](https://github.com/marionebl/ts-transform-json-schema)

Last, but not least, huge thanks to [dsherret](https://github.com/dsherret) for making [ts-ast-viewer](https://github.com/dsherret/ts-ast-viewer). This tool
**saved my life** during my dives into the TypeScript AST.

---
_Source: https://npm.io/package/ts-transformer-ajv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._