@keysdown/form-wrapper 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Keys Down
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,529 @@
+<h1 align="center">
+  Form Wrapper (Beta)
+</h1>
+
+> A package that allows you to easily manage forms, with Form Wrapper it is possible to perform validations with error messages, in addition to managing the state of the forms.
+
+> This package is currently in Beta and is being tested in live applications, feel free to help in the development and maturation of the package.
+
+## Installation
+
+```shell
+npm install @keysdown/form-wrapper --save
+```
+
+## Basic example
+
+Basic example using Vue.
+
+```vue
+
+<template>
+  <form @submit.prevent="submit">
+    <input type="text" v-model="form.first_name"/>
+    <input type="text" v-model="form.last_name"/>
+    <input type="text" v-model="form.username"/>
+    <button type="submit" :disabled="form.awaiting"/>
+  </form>
+</template>
+
+<script setup lang="ts">
+  import axios from 'axios'
+  import {ref} from 'vue'
+  import Form from '@keysdown/form-wrapper'
+
+  const form = ref(Form({
+    first_name: null,
+    last_name: null,
+    username: null
+  }))
+
+  const submit = () => {
+    form.value.setAwaiting(true)
+
+    axios.post('some-api', form.value.values())
+        .then(({data}) => {
+          form.value.reset()
+
+          // ...
+        })
+        .catch(({errors}) => {
+          form.value.errors.fill(errors)
+          
+          form.value.setAwaiting(false)
+        })
+  }
+</script>
+```
+
+## Basic example with validation
+
+Basic example with validation using Vue.
+
+```vue
+<template>
+  <form @submit.prevent="submit">
+    <input type="text" v-model="form.first_name"/>
+    <input type="text" v-model="form.last_name"/>
+    <input type="text" v-model="form.username"/>
+    <button type="submit" :disabled="form.awaiting"/>
+  </form>
+</template>
+
+<script setup lang="ts">
+  import axios from 'axios'
+  import {ref} from 'vue'
+  import Form from '@keysdown/form-wrapper'
+
+  const form = ref(Form({
+    first_name: {
+      value: null,
+      rules: ['required'],
+      messages: {
+        required: 'The first name field is required.'
+      }
+    },
+    last_name: {
+      value: null,
+      rules: ['required'],
+      messages: {
+        required: 'The last name field is required.'
+      }
+    },
+    username: {
+      value: null,
+      rules: ['required', 'min:6'],
+      messages: {
+        required: 'The username field is required.',
+        min: 'The username field must have at least 6 characters'
+      }
+    }
+  }))
+
+  const submit = () => {
+    form.value.validate()
+        .then((form) => {
+          form.setAwaiting(true)
+
+          axios.post('some-api', form.values())
+              .then(({data}) => {
+                form.reset()
+
+                // ...
+              })
+              .catch(({errors}) => {
+                form.errors.fill(errors)
+
+                form.setAwaiting(false)
+              })
+        })
+        .catch((form) => {
+          console.log('error')
+        })
+  }
+</script>
+```
+
+
+## Form methods
+
+### addField(field, value)
+
+Method used to add a single field to the form.
+
+```js
+form.addField('username', null)
+
+form.addField('username', {
+    validation: {
+        rules: ['required'],
+        messages: {
+            required: 'The username field is required.'
+        }
+    }
+})
+```
+
+### addFields(fields)
+
+Method used to add multiple fields to the form.
+
+```js
+form.addFields({
+    full_name: null,
+    username: null
+})
+
+form.addFields({
+    full_name: {
+        validation: {
+            rules: ['required'],
+            messages: {
+                required: 'The full name field is required.'
+            }
+        }
+    },
+    username: {
+        validation: {
+            rules: ['required'],
+            messages: {
+                required: 'The username field is required.'
+            }
+        }
+    }
+})
+```
+
+### fill(data, updateOriginalValues = false)
+
+Method used when you want to fill in several form fields at once.
+
+```js
+const form = Form({
+    username: null
+})
+
+console.log(form.values()) // {username: null}
+
+form.fill({
+    username: 'keysdown'
+})
+
+console.log(form.values()) // {username: 'keysdown'}
+```
+
+### removeField(field)
+
+Method used when you want to remove a field from the form.
+
+```js
+const form = Form({
+    username: null
+})
+
+console.log(form.values()) // {username: null}
+
+form.removeField('username')
+
+console.log(form.values()) // {}
+```
+
+### removeFields(fields)
+
+Method used to remove multiple fields to the form.
+
+```js
+const form = Form({
+    username: null
+})
+
+console.log(form.values()) // {username: null}
+
+form.removeFields(['username'])
+
+console.log(form.values()) // {}
+```
+
+### reset()
+
+Method used to reset all form values to original state.
+
+```js
+const form = Form({
+    username: null
+})
+
+form.username = 'keysdown'
+
+console.log(form.values()) // {username: 'keysdown'}
+
+form.reset()
+
+console.log(form.values()) // {username: null}
+```
+
+### setAwaiting(awaiting = true)
+
+Method used to change the form loading state.
+
+```js
+const form = Form({
+    username: null
+})
+
+console.log(form.awaiting) // false
+
+form.setAwaiting()
+
+console.log(form.awaiting) // true
+
+form.setAwaiting(false)
+
+console.log(form.awaiting) // false
+```
+
+### validate(field = null)
+
+Method used to validate the entire form or a specific field.
+
+```js
+ const form = Form({
+    username: {
+        value: null,
+        rules: ['required'],
+        messages: {
+            required: 'The username field is required.'
+        }
+    }
+})
+
+form.validate('username')
+    .then(() => {
+        //...
+    })
+    .catch(() => {
+        //...
+    })
+
+form.validate()
+    .then((form) => {
+        form.setAwaiting(true)
+
+        // ...
+    })
+    .catch((form) => {
+        console.log('error')
+    })
+```
+
+### validateField(field)
+
+Method used to validate a specific field.
+
+```js
+ const form = Form({
+    username: {
+        value: null,
+        rules: ['required'],
+        messages: {
+            required: 'The username field is required.'
+        }
+    }
+})
+
+form.validateField('username')
+    .then(() => {
+        //...
+    })
+    .catch(() => {
+        //...
+    })
+
+// Same as:
+
+form.validate('username')
+    .then(() => {
+        //...
+    })
+    .catch(() => {
+        //...
+    })
+```
+
+### validateForm()
+
+Method used to validate the entire form.
+
+```js
+ const form = Form({
+    username: {
+        value: null,
+        rules: ['required'],
+        messages: {
+            required: 'The username field is required.'
+        }
+    }
+})
+
+form.validateForm()
+    .then((form) => {
+        //...
+    })
+    .catch((form) => {
+        //...
+    })
+
+// Same as:
+
+form.validate()
+    .then((form) => {
+        form.setAwaiting(true)
+
+        // ...
+    })
+    .catch((form) => {
+        console.log('error')
+    })
+```
+
+### values()
+
+Method used to access all form values in json format.
+
+```js
+ const form = Form({
+    username: null
+})
+
+form.username = 'keysdown'
+
+axios.post('some-api', form.values())
+```
+
+### valuesAsFormData()
+
+Method used to access all form values as form data.
+
+```js
+ const form = Form({
+    username: null
+})
+
+form.username = 'keysdown'
+
+axios.post('some-api', form.valuesAsFormData(), {
+    headers: {
+        'Content-Type': 'multipart/form-data'
+    }
+})
+```
+
+## Validation
+
+There is a property in the form object dedicated to validations, you can access everything related to validations through the `validation` property:
+
+```js
+form.validation.errors.all()
+
+form.validation.messages.all()
+
+form.validation.rules.all()
+```
+
+You can also use the following shortcuts:
+
+```js
+form.errors.all()
+
+form.messages.all()
+
+form.rules.all()
+```
+
+### Validation collections
+
+Both errors, messages and rules work using collections, the methods for managing collections are as follows:
+
+#### all()
+
+Returns all items in the collection.
+
+```js
+form.errors.all()
+form.messages.all()
+form.rules.all()
+```
+
+#### first(key)
+
+Returns the first item in the collection.
+
+```js
+form.errors.first('username')
+form.messages.first('username')
+form.rules.first('username')
+```
+
+#### any()
+
+Returns true if the collection has any items and false if it is empty.
+
+```js
+form.errors.any()
+form.messages.any()
+form.rules.any()
+```
+
+#### fill(items)
+
+Inserts values into a collection, replacing any previous values.
+
+```js
+form.errors.fill({
+    username: [
+        'The username field is required.'
+    ]
+})
+
+form.messages.fill({
+    username: {
+        required: 'The username field is required.'
+    }
+})
+
+form.rules.fill({
+    username: ['required']
+})
+```
+
+#### push(key, data)
+
+Inserts a single value into an item in a collection.
+
+```js
+form.errors.push('username', 'The username field is required.')
+
+form.messages.push('username', {
+    required: 'The username field is required.'
+})
+
+form.rules.push('username', 'required')
+```
+
+#### has(key)
+
+Checking if the collection has an item with the key.
+
+```js
+form.errors.has('username')
+form.messages.has('username')
+form.rules.has('username')
+```
+
+#### unset(key)
+
+Remove an item from the collection.
+
+```js
+form.errors.unset('username')
+form.messages.unset('username')
+form.rules.unset('username')
+```
+
+#### clear(key)
+
+Clears the entire collection, making it empty.
+
+```js
+form.errors.clear()
+form.messages.clear()
+form.rules.clear()
+```
+
+### Validation rules
+
+There are some predefined validation rules that you can use in the form:
+
+#### required
+
+Used when a field is required

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@keysdown/form-wrapper",
+  "version": "0.0.2",
+  "description": "JavaScript wrapper for forms",
+  "type": "module",
+  "main": "./dist/form-wrapper.umd.js",
+  "module": "./dist/form-wrapper.es.js",
+  "exports": {
+    ".": {
+      "import": "./dist/form-wrapper.es.js",
+      "require": "./dist/form-wrapper.umd.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3",
+    "vite": "^5.4.1"
+  }
+}

package/src/core/Errors.ts

@@ -0,0 +1,21 @@
+import {Collection} from '../utils/collections'
+
+export class Errors extends Collection<string[]> {
+    public push(
+        item: string,
+        data: any,
+    ): this {
+        const currentItem = this.get(item) || []
+
+        this.collection = {
+            ...this.collection,
+            [item]: [...currentItem, data]
+        }
+
+        return this
+    }
+
+    public get(key: string): string[] | null {
+        return super.get(key, [])
+    }
+}

package/src/core/Form.ts

@@ -0,0 +1,197 @@
+import {Field, FieldDeclaration, Fields, RawFields} from '../types/fields.ts'
+import {generateFieldDeclaration} from '../utils/fields.ts'
+import {Values} from '../types/values.ts'
+import {Validation} from './Validation.ts'
+import {Rule} from '../utils/validations.ts'
+import {objectToFormData} from '../utils/helpers.ts'
+import {ErrorMessage} from '../types/messages.ts'
+
+export class Form {
+    [key: string]: any
+
+    public awaiting: boolean = false
+
+    public originalValues: Values = {}
+
+    public validation: Validation = new Validation()
+
+    public constructor(
+        fields: Fields | RawFields
+    ) {
+        this.addFields(fields)
+    }
+
+    public addField(
+        field: string,
+        value: Field
+    ): this {
+        if (typeof value === 'object' && 'value' in value) {
+            const fieldDeclaration: FieldDeclaration = generateFieldDeclaration(value)
+
+            this[field] = fieldDeclaration.value
+
+            this.originalValues[field] = fieldDeclaration.value
+
+            this.validation.messages.push(field, fieldDeclaration.validation.messages)
+
+            this.validation.rules.push(field, fieldDeclaration.validation.rules)
+        } else {
+            this[field] = value
+
+            this.originalValues[field] = value
+        }
+
+        return this
+    }
+
+    public addFields(
+        fields: Fields | RawFields
+    ): this {
+        Object.keys(fields).forEach((field: string) => {
+            this.addField(field, fields[field])
+        })
+
+        return this
+    }
+
+    public get errors() {
+        return this.validation.errors
+    }
+
+    public fill(
+        data: { [key: string]: any },
+        updateOriginalValues: boolean = false
+    ): this {
+        Object.keys(data).forEach((field: string) => {
+            let value = data[field]
+
+            if (updateOriginalValues) {
+                this.originalValues[field] = value
+            }
+
+            this[field] = value
+        })
+
+        return this
+    }
+
+    public get messages() {
+        return this.validation.messages
+    }
+
+    public removeField(
+        field: string
+    ): this {
+        delete this[field]
+
+        delete this.originalValues[field]
+
+        this.validation.messages.unset(field)
+
+        this.validation.rules.unset(field)
+
+        return this
+    }
+
+    public removeFields(
+        fields: string[]
+    ): this {
+        fields.forEach((field: string) => {
+            this.removeField(field)
+        })
+
+        return this
+    }
+
+    public reset(): this {
+        this.validation.errors.clear()
+
+        Object.keys(this.originalValues).forEach((field: string) => {
+            this[field] = this.originalValues[field]
+        })
+
+        return this
+    }
+
+    public get rules() {
+        return this.validation.rules
+    }
+
+    public setAwaiting(
+        awaiting: boolean = true
+    ): this {
+        this.awaiting = awaiting
+
+        return this
+    }
+
+    public validate(
+        field: string | null = null
+    ): Promise<this | void> {
+        return field ? this.validateField(field) : this.validateForm()
+    }
+
+    public validateField(
+        field: string
+    ): Promise<void> {
+        this.validation.errors.unset(field)
+
+        const rules = this.validation.rules.get(field)
+
+        if (rules && rules.length > 0) {
+            const validations = rules.map((
+                    rule: string
+                ) => {
+                    const ruleParts = rule.split(':')
+
+                    const ruleName: string = ruleParts[0]
+                    const ruleAttributes: string[] = ruleParts.length === 2 ? ruleParts[1].split(',') : []
+
+                    if (ruleName in Rule) {
+                        return Rule[ruleName](this[field], ruleAttributes)
+                            .catch((error?: string) => {
+                                const errorMessage: ErrorMessage | null = this.validation.messages.get(field)
+
+                                if (errorMessage && ruleName in errorMessage) {
+                                    this.validation.errors.push(field, errorMessage[ruleName])
+                                }
+
+                                return Promise.reject(error)
+                            })
+                    }
+
+                    return Promise.reject(new Error(`There is no validation rule called "${rule}"`))
+                }
+            )
+
+            return Promise.all(validations).then(() => {
+            })
+        }
+
+        return Promise.resolve()
+    }
+
+    public validateForm(): Promise<this> {
+        const validations = Object.keys(this.originalValues).map(
+            (field: string) => this.validateField(field)
+        )
+
+        return Promise.all(validations)
+            .then(() => Promise.resolve(this))
+            .catch(() => Promise.reject(this))
+    }
+
+    public values(): Values {
+        const values: Values = {}
+
+        Object.keys(this.originalValues).forEach((field: string): void => {
+            values[field] = this[field]
+        })
+
+        return values
+    }
+
+    public valuesAsFormData() {
+        return objectToFormData(this.values())
+    }
+}

package/src/core/Messages.ts

@@ -0,0 +1,5 @@
+import { Collection } from '../utils/collections'
+import {ErrorMessage} from '../types/messages.ts'
+
+export class Messages extends Collection<ErrorMessage> {
+}

package/src/core/Rules.ts

@@ -0,0 +1,4 @@
+import { Collection } from '../utils/collections'
+
+export class Rules extends Collection<string[]> {
+}

package/src/core/Validation.ts

@@ -0,0 +1,11 @@
+import {Messages} from './Messages.ts'
+import {Rules} from './Rules.ts'
+import {Errors} from './Errors.ts'
+
+export class Validation {
+    public errors: Errors = new Errors()
+
+    public messages: Messages = new Messages()
+
+    public rules: Rules = new Rules()
+}

package/src/main.ts

@@ -0,0 +1,9 @@
+import {Form} from './core/Form.ts'
+
+const createForm = (data: any) => new Form(data)
+
+export {
+    createForm
+}
+
+export default Form

package/src/types/collections.ts

@@ -0,0 +1,3 @@
+export interface Items<T> {
+    [key: string]: T
+}

package/src/types/fields.ts

@@ -0,0 +1,19 @@
+import { Validation } from './validations'
+
+export interface Field {
+    validation?: object,
+    value: any
+}
+
+export interface FieldDeclaration {
+    validation: Validation,
+    value: any
+}
+
+export interface Fields {
+    [key: string]: Field
+}
+
+export interface RawFields {
+    [key: string]: any
+}

package/src/types/messages.ts

@@ -0,0 +1,3 @@
+export type ErrorMessage = {
+    [key: string]: string
+}

package/src/types/rules.ts

@@ -0,0 +1,3 @@
+export interface Rules {
+    [key: string]: (value: any, attributes: string[]) => Promise<any>
+}

package/src/types/validations.ts

@@ -0,0 +1,4 @@
+export interface Validation {
+    rules: string[],
+    messages: object
+}

package/src/types/values.ts

@@ -0,0 +1,3 @@
+export interface Values {
+    [key: string]: any
+}

package/src/utils/collections.ts

@@ -0,0 +1,78 @@
+import {Items} from '../types/collections'
+
+export class Collection<T> {
+    public collection: Items<T> = {}
+
+    public all(): Items<T> {
+        return this.collection
+    }
+
+    public first(
+        key: string
+    ): T | null {
+        const data = this.get(key)
+
+        if (data) {
+            return Array.isArray(data) ? data[0] : data
+        }
+
+        return null
+    }
+
+    public any(): boolean {
+        return Object.keys(this.collection).length > 0
+    }
+
+    public fill(
+        items: Items<T>
+    ): this {
+        this.collection = items
+
+        return this
+    }
+
+    public push(
+        key: string,
+        data: any
+    ): this {
+        this.collection = {
+            ...this.collection,
+            [key]: data
+        }
+
+        return this
+    }
+
+    public has(
+        key: string
+    ): boolean {
+        return this.collection.hasOwnProperty(key)
+    }
+
+    public get(
+        item: string,
+        defaultValue: T | null = null
+    ): T | null {
+        if (!this.has(item)) {
+            return defaultValue
+        }
+
+        return this.collection[item]
+    }
+
+    public unset(
+        key: string
+    ): this {
+        if (this.has(key)) {
+            delete this.collection[key]
+        }
+
+        return this
+    }
+
+    public clear(): this {
+        this.collection = {}
+
+        return this
+    }
+}

package/src/utils/fields.ts

@@ -0,0 +1,23 @@
+import {FieldDeclaration} from '../types/fields'
+
+const generateValidationRules = (
+    rules: string | string[]
+): string[] => {
+    return typeof rules === 'string' ?
+        rules.split('|') :
+        rules
+}
+
+export const generateFieldDeclaration = (
+    value: any
+): FieldDeclaration => {
+    return {
+        validation: {
+            rules: value.validation?.rules ?
+                generateValidationRules(value.validation.rules) :
+                [],
+            messages: value.validation?.messages || {}
+        },
+        value: value.value || null
+    }
+}

package/src/utils/helpers.ts

@@ -0,0 +1,31 @@
+export const isObject = (value: any): boolean => {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export const objectToFormData = (
+    values: Record<string, any>,
+    context?: FormData,
+    namespace: string | null = null
+): FormData => {
+    const formData: FormData = context || new FormData()
+
+    Object.keys(values).forEach((key: string): void => {
+        const value = values[key]
+
+        key = namespace ? `${namespace}[${key}]` : key
+
+        if ([undefined, null].indexOf(value) > -1) {
+            return
+        }
+
+        if ((isObject(value) && !(value instanceof File)) || Array.isArray(value)) {
+            objectToFormData(value, formData, key)
+
+            return
+        }
+
+        formData.append(key, value)
+    })
+
+    return formData
+}

package/src/utils/validations.ts

@@ -0,0 +1,17 @@
+import {Rules} from '../types/rules.ts'
+
+export const required = (
+    value: string
+): Promise<any> => new Promise((resolve, reject) => {
+    if (value === undefined || value === null) {
+        reject()
+    }
+
+    let str = String(value).replace(/\s/g, "");
+
+    str.length > 0 ? resolve(value) : reject()
+})
+
+export const Rule: Rules = {
+    required
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/vite.config.js

@@ -0,0 +1,17 @@
+import {resolve} from 'path'
+import {defineConfig} from 'vite'
+
+export default defineConfig({
+    build: {
+        lib: {
+            entry: resolve(__dirname, 'src/main.ts'),
+            name: 'FormWrapper',
+            fileName: (format) => `form-wrapper.${format}.js`
+        },
+        rollupOptions: {
+            output: {
+                exports: 'named'
+            },
+        },
+    },
+})