# duckfficer

> Zero-dependencies, light-weight library for modeling, validating & sanitizing data

Latest version **2.5.0** (published 2021-09-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install duckfficer
pnpm add duckfficer
yarn add duckfficer
bun add duckfficer
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.5.0 |
| Published | 2021-09-27 |
| First published | 2020-08-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 175.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Martin Rafael |
| Maintainers | tin_r |
| Keywords | json, value, object, duck, sanitize, type, typing, schema, validation, validating, validator, cast, casting, modeling |

## Links

- npm: https://www.npmjs.com/package/duckfficer
- Repository: https://github.com/devtin/duckfficer
- Homepage: https://duckfficer.js.org
- Issues: https://github.com/devtin/duckfficer/issues
- npm.io page: https://npm.io/package/duckfficer

## 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

- 2.5.0 (latest) — 2021-09-27
- 2.4.1 — 2021-08-07
- 2.4.0 — 2021-08-05
- 2.3.0 — 2021-02-12
- 2.2.4 — 2021-02-11
- 2.2.3 — 2020-11-08
- 2.2.2 — 2020-10-28
- 2.2.1 — 2020-10-22
- 2.2.0 — 2020-10-16
- 2.1.1 — 2020-09-15
- 2.1.0 — 2020-09-02
- 2.0.0 — 2020-09-02
- 1.2.0 — 2020-08-24
- 1.1.1 — 2020-08-24
- 1.1.0 — 2020-08-23
- … 1 more at https://npm.io/package/duckfficer/versions

## README

<p align="center"><img align="center" width="480" src="https://repository-images.githubusercontent.com/228456718/f4767e00-61e6-11ea-964a-7b02d8dcb48f"/></p>

<div align="center"><h1 align="center">duckfficer</h1></div>

<p align="center">
<a href="https://www.npmjs.com/package/duckfficer" target="_blank"><img src="https://img.shields.io/npm/v/duckfficer.svg" alt="Version"></a>
<a href="https://htmlpreview.github.io/?https://github.com/devtin/duckfficer/blob/master/coverage/lcov-report/index.html"><img src="https://img.shields.io/badge/coverage-99%25-green" alt="Coverage 99%"></a>
<a href="/test/features"><img src="https://github.com/devtin/duckfficer/workflows/test/badge.svg"></a>
<a href="https://opensource.org/licenses" target="_blank"><img src="https://img.shields.io/badge/License-MIT-brightgreen.svg"></a>
</p>

<p align="center">
Zero-dependencies, light-weight library (~4.6KB minified + gzipped)<br>
for modeling, validating & sanitizing data
</p>

## Manifesto

Performing duck-type validation and data sanitation is not what I came to this world for... I want a utility helping me
simplify that task.

This utility must:

- Check whether certain value has the shape of a predefined schema-type
- When a given value does not match the schema, it must offer a full report of what is wrong with the given
  value vs what the schema is expecting! (see: [https://duckfficer.js.org/#/guide?id=error-handling-and-lifecycle](https://duckfficer.js.org/#/guide?id=error-handling-and-lifecycle))
- Be easy to extend and share schemas within each other (see: [https://duckfficer.js.org/#/guide?id=nesting-schemas](https://duckfficer.js.org/#/guide?id=nesting-schemas))
- Provide a built-in set of types for most common usages (see: [https://duckfficer.js.org/#/types](https://duckfficer.js.org/#/types))
- Allow custom types as well as a cast and transform hooks (see: [https://duckfficer.js.org/#/types?id=custom](https://duckfficer.js.org/#/types?id=custom))


Let's put hands on it!

**Index**

- [Installation](#installation)
- [About](#about)
- [At a glance](#at-a-glance)
- [Documentation](https://devtin.github.io/duckfficer)

## Installation

```sh
$ npm i duckfficer
# or
$ yarn add duckfficer
```

## At-a-glance

```js
const { Schema } = require('duckfficer')

// lets create a schema first
const User = new Schema({
  firstName: String,
  lastName: String,
  get fullName () {
    return this.firstName + ' ' + this.lastName
  },
  dob: Date,
  contact: {
    phoneNumber: {
      type: Number,
      autoCast: true // transforms String that look like a number into a Number
    },
    emails: {
      default () {
        return []
      },
      type: Array,
      arraySchema: {
        type: String,
        regex: [/^[a-z0-9._]+@[a-z0-9-]+\.[a-z]{2,}$/, '{ value } is not a valid e-mail address']
      }
    }
  }
})

User.parse({
  firstName: 'Fulano de Tal',
  contact: {
    emails: ['fulanito']
  }
})
  .catch(err => {
    console.log(err.message) // => Data is not valid
    console.log(err.errors.length) // => 4
    console.log(err.errors[0].message) // => Property lastName is required
    console.log(err.errors[0].field.fullPath) // => lastName
    console.log(err.errors[1].message) // => Property dob is required
    console.log(err.errors[1].field.fullPath) // => dob
    console.log(err.errors[2].message) // => Property contact.phoneNumber is required
    console.log(err.errors[2].field.fullPath) // => contact.phoneNumber
    console.log(err.errors[3].message) // => fulanito is not a valid e-mail address
    console.log(err.errors[3].field.fullPath) // => contact.emails.0
  })

User.parse({
  firstName: 'Fulano',
  lastName: 'de Tal',
  dob: '1/1/2020',
  contact: {
    phoneNumber: '3051234567',
    emails: [
      'personal@email.com',
      'work@email.com'
    ]
  }
})
  .then(obj => {
    console.log(obj.dob instanceof Date) // => true
    console.log(typeof obj.contact.phoneNumber) // => number
    console.log(obj) // =>
    /*
      {
        firstName: 'Fulano',
        lastName: 'de Tal',
        dob: 2020-01-01T05:00:00.000Z,
        contact: {
          phoneNumber: 3051234567,
          emails: [ 'personal@email.com', 'work@email.com' ]
        }
      }
    */
  })
```


[Read the documentation](https://devtin.github.io/duckfficer)

* * *

## License

[MIT](https://opensource.org/licenses/MIT)

&copy; 2019-2020 Martin Rafael <tin@devtin.io>

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