Commonly shared utility functions between official FormKit packages.
You can add this package by using npm install @formkit/utils or yarn add @formkit/utils.
Performs a recursive Object.assign
-like operation.
assignDeep<A extends Record<PropertyKey, any>, B extends Record<PropertyKey, any>>(a: A, b: B): A & B;
a — An object to be assigned.b — An object to get values from.A & B
This converts kebab-case to camelCase. It ONLY converts from kebab to camel.
camel(str: string): string;
str — String to be camel cased.string
Perform a recursive clone on a given object. Only intended to be used for simple objects like arrays and POJOs.
clone<T extends Record<string, unknown> | unknown[] | null>(obj: T, explicit?: string[]): T;
obj — Object to be cloned.explicit optional — Array of items to be explicity cloned.T
Clones anything. If the item is scalar, no worries, it passes it back. If it is an object, it performs a (fast/loose) clone operation.
cloneAny<T>(obj: T): T;
obj — The value to be cloned.T
Given 2 arrays, return them as a combined array with no duplicates.
dedupe<T extends any[] | Set<any>, X extends any[] | Set<any>>(arr1: T, arr2?: X): any[];
arr1 — First array.arr2 optional — Second array.any[]
Determines if a value is empty or not.
empty(value: any): boolean;
value — The value to check if it's empty.boolean
Compare two values for equality, optionally at depth.
eq(valA: any, valB: any, deep?: boolean, explicit?: string[]): boolean;
valA — First value.valB — Second value.deep optional — If it will compare deeply if it's an object.explicit optional — An array of keys to explicity check.boolean
A regular expression to test for a valid date string.
eqRegExp(x: RegExp, y: RegExp): boolean;
x — A RegExp to compare.y — A RegExp to compare.Escape a string for use in regular expressions.
escapeExp(string: string): string;
string — String to be escaped.string
Return a new (shallow) object with any desired props removed.
except(obj: Record<string, any>, toRemove: Array<string | RegExp>): Record<string, any>;
obj — The starting object.toRemove — The array of properties to remove. Accepts strings or regular expressions.Record<string, any>
Recursively merge data from additional into original returning a new object.
extend(original: Record<string, any>, additional: Record<string, any> | string | null, extendArrays?: boolean, ignoreUndefined?: boolean): Record<string, any> | string | null;
original — The original array.additional — The array to merge.extendArrays optional — If it will extend/concatenate array values instead of replacing them.ignoreUndefined optional — If it will preserve values from the original object even if the additional object has those values set to undefined.Record<string, any> | string | null
NO_SIDE_EFFECTS
Get a specific value via dot notation.
getAt(obj: any, addr: string): unknown;
obj — An object to fetch data from.addr — An "address" in dot notation.unknown
Checks if the given property exists on the given object.
has(obj: {
[index: string]: any;
[index: number]: any;
}, property: string | symbol | number): boolean;
obj — An object to check.property — The property to check.boolean
Defines an object as an initial value.
init<T extends object>(obj: T): T & {
__init?: true;
};
obj — Object to be added an initial value.T & { __init?: true }
Checks if an object is a simple array or record.
isObject(o: unknown): o is Record<PropertyKey, unknown> | unknown[];
o — Value to be checked.boolean
Attempts to determine if an object is a POJO (Plain Old JavaScript Object). Mostly lifted from is-plain-object: https://github.com/jonschlinkert/is-plain-object Copyright (c) 2014-2017, Jon Schlinkert.
isPojo(o: any): o is Record<string, any>;
o — The value to be checked.boolean
Determine if the given string is fully quoted.
isQuotedString(str: string): boolean;
str — The string to check.boolean
hello - false
"hello" - true
'world' - true
"hello"=="world" - false
"hello'this'" - false
"hello"'there' - false
"hello""there" - false
'hello === world' - true
Determines if an object is an object.
isRecord(o: unknown): o is Record<PropertyKey, unknown>;
o — The value to be checked.boolean
This converts camel-case to kebab case. It ONLY converts from camel to kebab.
kebab(str: string): string;
str — String to be kebabed.string
Filters out values from an object that should not be considered "props" of a core node, like "value" and "name".
nodeProps(...sets: Array<Record<string, any>>): Record<string, any>;
sets — The arrays to get values filtered out of.Record<string, any>
Given a FormKit input type, returns the correct lowerCased() type.
nodeType(type: string): 'list' | 'group' | 'input';
type — String to return to check for correct type'list' | 'group' | 'input'
Given a function only 1 call will be made per call stack. All others will be discarded.
oncePerTick<T extends CallableFunction>(fn: T): T;
fn — The function to be called once per tick.Extracts a set of keys from a given object. Importantly, this will extract values even if they are not set on the original object — they will just have an undefined value.
only(obj: Record<string, any>, include: Array<string | RegExp>): Record<string, any>;
obj — The object to get values from.include — The array of items to get.Record<string, any>
Parse a string for comma-separated arguments.
parseArgs(str: string): string[];
str — String to parse arguments from.string[]
Given a string date format, return a regex to match against.
regexForFormat(format: string): RegExp;
format — String to be transformed to RegExp.RegExp
regexForFormat('MM') // returns '(0[1-9]|1[012])'
Remove extra escape characters.
rmEscapes(str: string): string;
str — String to remove extra escape characters from.string
Creates a new set of the specified type and uses the values from an Array or an existing Set.
setify<T>(items: Set<T> | T[] | null | undefined): Set<T>;
items — An array or a Set.Set<T>
import { setify } from '@formkit/utils'
const tk = setify(['a', 'b'])
// Set(2) {'a', 'b'}
Shallowly clones the given object.
shallowClone<T>(obj: T, explicit?: string[]): T;
obj — Object to be shallowly cloned.explicit optional — The array of keys to be explicity cloned.T
Turn any string into a URL/DOM-safe string.
slugify(str: string): string;
str — String to be slugified to a URL
-safe string.string
Spreads an object or an array, otherwise returns the same value.
spread<T>(obj: T, explicit?: string[]): T;
obj — The object to be spread.explicit optional — The array of items to be explicity spread.T
Generates a random string.
token(): string;
string
import { token } from '@formkit/utils'
const tk = token()
// 'jkbyqnphqm'
Determines if the value of a prop that is either present (true) or not present (undefined). For example, the prop disabled should disable by just existing, but what if it is set to the string "false" — then it should not be disabled.
undefine(value: unknown): true | undefined;
value — Value to check for undefined.true | undefined
Uses a global mutation observer to wait for a given element to appear in the DOM.
whenAvailable(childId: string, callback: (el: Element) => void, root?: Document | ShadowRoot): void;
childId — The id of the child node.callback — The callback to call when the child node is found.root optionalThe date token strings that can be used for date formatting.
export type FormKitDateTokens = 'MM' | 'M' | 'DD' | 'D' | 'YYYY' | 'YY';