From feec0cf224c8c4e3d0a2d9f19907279d86ec1c09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCr=20Adem=20I=C5=9EIKLI?= Date: Sat, 16 Dec 2023 22:45:41 +0100 Subject: [PATCH] Added more docs --- docs/.vitepress/config.mts | 35 +++++++++++---------- docs/learn.md | 52 +++++++++++++++---------------- docs/terminology.md | 63 ++++++++++++++++++++++++++++++++++++++ docs/why.md | 18 +++++++++++ src/Constants.ts | 4 +-- src/Interface.ts | 4 +-- src/Types.ts | 2 +- src/index.ts | 10 +++--- 8 files changed, 136 insertions(+), 52 deletions(-) create mode 100644 docs/terminology.md create mode 100644 docs/why.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index d11ebed..5247adc 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,4 +1,4 @@ -import { defineConfig } from 'vitepress' +import { defineConfig } from "vitepress"; // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -6,23 +6,26 @@ export default defineConfig({ description: "Another data validation library", themeConfig: { // https://vitepress.dev/reference/default-theme-config - nav: [ - { text: 'Home', link: '/' }, - { text: 'Examples', link: '/markdown-examples' } - ], - + // nav: [{ text: "GitHub", link: "https://github.com/axe-api/validator" }], sidebar: [ { - text: 'Examples', + text: "Introduction", + items: [ + { text: "Why?", link: "/why" }, + { text: "Getting started", link: "/learn" }, + { text: "Terminology", link: "/terminology" }, + ], + }, + { + text: "Rules", items: [ - { text: 'Markdown Examples', link: '/markdown-examples' }, - { text: 'Runtime API Examples', link: '/api-examples' } - ] - } + { text: "Why?", link: "/xx" }, + { text: "Getting started", link: "/rr" }, + ], + }, ], - socialLinks: [ - { icon: 'github', link: 'https://github.com/vuejs/vitepress' } - ] - } -}) + { icon: "github", link: "https://github.com/axe-api/validator" }, + ], + }, +}); diff --git a/docs/learn.md b/docs/learn.md index b0b12fe..6b2e1df 100644 --- a/docs/learn.md +++ b/docs/learn.md @@ -14,45 +14,45 @@ $ npm install --save axe-api-validator Using `axe-api-validator` is very simple. -You should just call the `validate()` function with data and rules. +You should just call the `validate()` function with data and the definition. ```js -import validate from "axe-api-validator"; +import { validate } from "axe-api-validator"; const data = { - email: "foo@bar.com", + email: "not-a-valid-email", name: "John", surname: "Doe", }; -const rules = { +const definition = { email: "required|email", name: "required|min:1|max:50", surname: "required|min:1|max:50", }; -const result = await validate(data, rules); +const result = await validate(data, definition); +console.log(result); ``` -## Vue Demo - -```js -import { ref, computed } from "vue"; -import validate from "axe-api-validator"; - -const data = ref({ - email: "", - name: "", - surname: "", -}); - -const rules = { - email: "required|email", - name: "required|min:1|max:10", - surname: "required|min:1|max:10", -}; - -const validation = computed(() => validate(data.value, rules)); +By the example, you would get the following response: + +```json +{ + "isValid": false, + "isInvalid": true, + "fields": { + "email": false, + "name": true, + "surname": true + }, + "errors": { + "email": [ + { + "rule": "required", + "message": "The field field is required." + } + ] + } +} ``` - - diff --git a/docs/terminology.md b/docs/terminology.md new file mode 100644 index 0000000..4f8a6ef --- /dev/null +++ b/docs/terminology.md @@ -0,0 +1,63 @@ +# Terminology + +In this section, we are going to explain the basic terminology. + +## Rule + +A rule is a function that takes at least one argument (value) and validates the data. It should return a `true` or `false` value as a return. + +The following type definition is the definition of a rule function. + +```ts +type RuleFunction = (...args: any[]) => boolean; +``` + +The first parameter of a rule function should be the value that will be validated always. + +```ts +export default (value: any): boolean => { + // Return `true` if the `value` is valid. + return true; +}; +``` + +A rule function always might have more parameters if it needs them. For example, if you want to check the minimum string size, the rule function should have to parameter like the following example. + +```ts +export default (value: any, size: any): boolean => { + // Return `true` if the `value` is valid. + return true; +}; +``` + +A rule should be able to execute directly. + +```ts +import { isRequired } from "axe-validator"; + +const result = isRequired("data"); +``` + +## Definition + +The definition means which rule sets will be executed for data. + +It should be an object like the following example: + +```js +const definition = { + email: "required|email", + name: "required|min:1|max:50", + surname: "required|min:1|max:50", +}; +``` + +For each data property, the rule names should be defined. + +The `|` should be used to be able to use multiple rule names at the same time: + +`required|email|alpha` + +All possible rule parameters should be defined between the `:` operator. + +`required|min:1|max:50|between:1:50` diff --git a/docs/why.md b/docs/why.md new file mode 100644 index 0000000..30d97d8 --- /dev/null +++ b/docs/why.md @@ -0,0 +1,18 @@ +# Why? + +Discovering a data validation library that seamlessly combines ease of use, the ability to store validation rules for future use, and robust internationalization (i18n) support is a formidable challenge. While numerous data validation libraries exist, finding one that fulfills all these criteria is often elusive. Some libraries that do meet these requirements are unfortunately no longer actively maintained. + +Axe Validator was born out of the need for a versatile data validation solution that not only simplifies the validation process but also empowers developers with the flexibility to preserve and reuse validation rules. This library aims to bridge the gap by offering a user-friendly experience, ensuring your validation needs are met comprehensively. + +Why choose Axe Validator? It's more than just a data validation tool; it's a commitment to providing a reliable, well-maintained, and feature-rich solution for developers who value simplicity and effectiveness in their projects. + +## Principles + +I decided on some fundamental rules while building this library: + +- Every validation rule should be an independent function. +- Every validation rule should be able to be used separately +- All validation definition should be able to be stored anywhere (database, memory, configuration files, 3rd party API, etc) to be used later. +- All validation rules should be able to be used in different languages. +- Contribution to the rule set should be easy. +- Should be well-documented. diff --git a/src/Constants.ts b/src/Constants.ts index 66e6079..9dd5e06 100644 --- a/src/Constants.ts +++ b/src/Constants.ts @@ -1,8 +1,8 @@ -import { RuleType, ValidationFunction } from "./Types"; +import { RuleType, RuleFunction } from "./Types"; import rules from "./Rules"; import { IOptions } from "./Interface"; -export const RULE_FUNCTION_MAPS: Record = { +export const RULE_FUNCTION_MAPS: Record = { string: rules.string, boolean: rules.boolean, accepted: rules.accepted, diff --git a/src/Interface.ts b/src/Interface.ts index bd8c6a8..3b16c64 100644 --- a/src/Interface.ts +++ b/src/Interface.ts @@ -1,13 +1,13 @@ import { RuleType, SupportedLanguages, - ValidationFunction, + RuleFunction, ValidationResult, } from "./Types"; export interface IRuleDefinition { name: RuleType; - callback: ValidationFunction; + callback: RuleFunction; params: any[]; } diff --git a/src/Types.ts b/src/Types.ts index e2d8989..2ff0b0b 100644 --- a/src/Types.ts +++ b/src/Types.ts @@ -29,7 +29,7 @@ export type RuleType = | "string" | "url"; -export type ValidationFunction = (...args: any[]) => boolean; +export type RuleFunction = (...args: any[]) => boolean; export type ValidationResult = Record; diff --git a/src/index.ts b/src/index.ts index 97d7ffa..5ffd077 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,7 +7,7 @@ import { getOptions, setOptions } from "./Options"; const validate = ( data: any, - validation: Record, + definition: Record, options?: Partial ): IValidationResult => { const currentOptions: IOptions = { @@ -17,7 +17,7 @@ const validate = ( const { isValid, fields, results } = getResults( data, - validation, + definition, currentOptions ); @@ -31,7 +31,7 @@ const validate = ( const getResults = ( data: any, - validation: Record, + definition: Record, options: IOptions ) => { let isValid = true; @@ -39,10 +39,10 @@ const getResults = ( const results: ValidationResult = {}; // Checking all validations - for (const key in validation) { + for (const key in definition) { fields[key] = true; // Parsing the rules - const rules = toRuleNameArray(validation[key]).map(toRuleDefinition); + const rules = toRuleNameArray(definition[key]).map(toRuleDefinition); // Getting the value by the path const value = getValueViaPath(data, key);