# @elieandraos/clockwork

> Minimal model-based javascript validation library

Latest version **1.0.21** (published 2023-09-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @elieandraos/clockwork
pnpm add @elieandraos/clockwork
yarn add @elieandraos/clockwork
bun add @elieandraos/clockwork
```

## Health

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

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.21 |
| Published | 2023-09-25 |
| First published | 2021-12-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 81.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Elie Andraos |
| Maintainers | elieandraos |
| Keywords | javascript, validation, rules, standalone, isolated, state, data, laravel-like |

## Links

- npm: https://www.npmjs.com/package/@elieandraos/clockwork
- Repository: https://github.com/elieandraos/clockwork
- Homepage: https://github.com/elieandraos/clockwork#readme
- Issues: https://github.com/elieandraos/clockwork/issues
- npm.io page: https://npm.io/package/@elieandraos/clockwork

## Dependencies (2)

- [date-fns](https://npm.io/package/date-fns.md) ^2.27.0
- [dot-prop](https://npm.io/package/dot-prop.md) ^6.0.1

## Alternatives

- [@reckona/mreact-store](https://npm.io/package/@reckona/mreact-store.md) — 976 weekly downloads
- [regular-state](https://npm.io/package/regular-state.md) — 410 weekly downloads
- [@pacote/flux-actions](https://npm.io/package/@pacote/flux-actions.md) — 65 weekly downloads
- [@pilotlab/lux-debug](https://npm.io/package/@pilotlab/lux-debug.md) — 39 weekly downloads
- [vue-persist-state](https://npm.io/package/vue-persist-state.md) — 19 weekly downloads

## Recent versions

- 1.0.21 (latest) — 2023-09-25
- 1.0.20 — 2023-09-25
- 1.0.19 — 2022-04-07
- 1.0.18 — 2022-03-24
- 1.0.17 — 2022-03-22
- 1.0.16 — 2022-03-22
- 1.0.15 — 2021-12-23
- 1.0.14 — 2021-12-22
- 1.0.13 — 2021-12-22
- 1.0.12 — 2021-12-22
- 1.0.11 — 2021-12-22
- 1.0.10 — 2021-12-21
- 1.0.9 — 2021-12-21
- 1.0.8 — 2021-12-21
- 1.0.7 — 2021-12-21
- … 6 more at https://npm.io/package/@elieandraos/clockwork/versions

## README

![GitHub Workflow Status](https://img.shields.io/github/workflow/status/elieandraos/clockwork/CI%20build%20&%20tests)
![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@elieandraos/clockwork)
![Coveralls](https://img.shields.io/coveralls/github/elieandraos/clockwork)
[![CodeFactor](https://www.codefactor.io/repository/github/elieandraos/clockwork/badge)](https://www.codefactor.io/repository/github/elieandraos/clockwork)
![npms.io (quality)](https://img.shields.io/npms-io/quality-score/@elieandraos/clockwork)
![downloads](https://img.shields.io/npm/dt/@elieandraos/clockwork)

- :technologist: Minimal model-based javascript validation library
- :bricks: Can be used with any javascript framework
- :green_heart: Offers 30+ built-in validation rules
- :children_crossing: Easy to use api, inspired from the Laravel validation syntax
- :test_tube: High test coverage

# Installation
```shell
npm install @elieandraos/clockwork --save
```

# Usage
```javascript
import Clockwork from '@elieandraos/clockwork'
const validator = new Clockwork()
```

# Basic validation
Clockwork validates a given data object against a given rules object
```javascript
// define the data and rules objects
validator
   .setData({
      name: '',
      email: ''
   })
   .setRules({
        name: 'required',
        email: 'required'
    })

if ( validator.passes() ) {
    // ... do something when input data are valid
}

// alternately, you could do the inverse
if (validator.fails() ) {
    // ... do something when input data are not valid
}
```

# Complex model validation
- "dot annotations" for nested object properties validation
- multiple rules are separated with a pipe
- rules that accept an additional paramter are suffixed with a semi column followed by the parameter
- rule paramter can be static or from the data object itself

```javascript
validator
   .setData({
      person: {
         name: null,
         age: null,
         email: null
      },
      domain: 'leadwithprimitive.com'
   })
    .setRules({
        'person.name': 'required | alpha',
        'person.age': 'required | integer | min:18',
        'person.email': 'required | email | ends_with:domain' // here domain will be evaluated as 'leadwithprimitive.com'
    })
```

# Accessing the error bag
Clockwork provides 4 helper methods to access any validation error:
```javascript
validator
   .setData({ name: null, age: 10 })
   .setRules({ name: 'required', age: 'min:12' })

if(validator.fails()) {
    validator.hasErrors() // checks if there is any error
    validator.hasErrors('name') // checks if there is any error for the 'name' field
    
    validator.getErrors() // returns all the error messages
    validator.getErrors('name') // returns all the error messages of the 'name' field

    validator.getFirstError() // returns the first error message found
    validator.getFirstError('name') // returns the first error message found of the 'name' field
    
    validator.getErrorBag() // returns the error bag object as it is
}
```

# Custom error messages
Custom error message can be defined with `setCustomErrorMesssages()` method. This method accepts an object of key/value pairs:
- The key is the data property concatenated with the rule name
- The value is the custom message

```javascript
validator
   .setData({ name: null })
   .setRules({ name: 'required' })
   .setCustomErrorMessages({ 'name.required' : 'You must enter your name' })
```

For rules with parameters, add `{param}` to into the error message and it will be parsed.  
```javascript
validator
   .setData({ age: null })
   .setRules({ age: 'min:18' })
   .setCustomErrorMessages({ 'age.min' : 'You must be at least {param} years old' }) // returns: You must be at least 18 years old
```

# Custom rules
Custom rules can be created with the `extend()` method. This method accepts three parameters: 
- The first, is the name of the rule name
- The second, is the closure (should return a boolean) that should be executed when calling the rule
- The third (optional), is the rule's error message (default: 'Invalid')

```javascript
validator
   .setData({ age: null })
   .setRules({ age: 'greater_than:18' })
   .extend( 'greated_than', (value, arg) => {
      return value > arg
   }, 'Age must be greater than {param}')
```

# Built-in rules

| Rules                       | Description                                                                                                                 |
|-----------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| **after**:_date_            | The field under validation must be a value after a given date                                                               |
| **after_or_equal**:_date_   | The field under validation must be a value after or equal a given date                                                      |
| **alpha**                   | The field under validation must be entirely alphabetic characters                                                           |
| **alpha_dash**              | The field under validation may have alpha characters, as well as dashes and underscores                                     |
| **alpha_numeric**           | The field under validation may have alpha-numeric characters                                                                |
| **array**                   | The field under validation must be an array                                                                                 |
| **before**:_date_           | The field under validation must be a value before a given date                                                              |
| **before_or_equal**:_date_  | The field under validation must be a value before or equal a given date                                                     |
| **boolean**                 | The field under validation must be able to be cast as a boolean                                                             |
| **date**                    | The field under validation must be a valid javascript date                                                                  |
| **date_format**:_string_    | The field under validation must match the given format                                                                      |
| **different**:_value_       | The field under validation must not match the given value                                                                   |
| **email**                   | The field under validation must be formatted as an email address                                                            |
| **ends_with**:_string_      | The field under validation must end with the given value                                                                    |
| **is_in**:_value_           | The field under validation must be included in the given value. Accepted values are comma seperated string or array         |
| **integer**                 | The field under validation must be an integer                                                                               |
| **json**                    | The field under validation must be a valid JSON object                                                                      |
| **leap_year**               | The field under validation must be a leap year date                                                                         |
| **max**:_value_             | The field under validation must be less than or equal to a maximum value. Accepted values are string, numerics and array    |
| **matches_regex**:_pattern_ | The field under validation must not match the given regular expression                                                      |
| **multiple_of**:_number_    | The field under validation must a be multiple of the given number                                                           |
| **min**:_value_             | The field under validation must be greater than or equal to a minimum value. Accepted values are string, numerics and array |
| **not_in**:_value_          | The field under validation must not be included in the given value. Accepted values are comma seperated string or array     |
| **numberic**                | The field under validation must be a numeric (integer or decimal)                                                           |
| **required**                | The field under validation must be present in the input data and not empty                                                  |
| **same**:_value_            | The field under validation must match the given value                                                                       |
| **size**:_value_            | The field under validation must have a length matching the given value. Accepted value are string and array                 |
| **sometimes**               | The field will only ve validated if present                                                                                 |
| **starts_with**:_string_    | The field under validation must end with the given value                                                                    |
| **string**                  | The field under validation must be a string                                                                                 |
| **today**                   | The field under validation must be a date equal to today                                                                    |
| **tomorrow**                | The field under validation must be a date equal to tomorrow                                                                 |
| **url**                     | The field under validation must be a valid url                                                                              |
| **uuid**                    | The field under validation must be a valid RFC 4122 (version 1, 3, 4, or 5) universally unique identifier (UUID)            |
| **yesterday**               | The field under validation must be a date equal to yesterday                                                                |


# Frameworks wrapper
- Vue: clockwork-vue https://github.com/elieandraos/clockwork-vue

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