Info
This page is automatically generated from source code comments, tests, etc. If there are any mistakes on this page, need to correct them. If you find any mistakes, please report them as an issue.
API
Version: 1.9.1-beta.1
Functions
add
Added from 1.0.0
Adds first argument and second argument.
Signature:
add: {
(a: number, b: number): number;
(a: number): (b: number) => number;
(a: bigint, b: bigint): bigint;
(a: bigint): (b: bigint) => bigint;
}
Parameters
Parameter | Description |
---|---|
a | The first input number |
b | The second input number |
=>
The result of a + b
Example 1
// Basic
add(1, 2) // 3
Example 2
// Bigint
add(1n, 2n) // 3n
Example 3
// Curry
const plus2(2)
plus2(-3) // -1
advance
Added from 1.7.0
Returns return value if argument is function
; otherwise returns the value as it is.
Signature:
advance: <T>(val: T | AnyFn<any, T>) => T
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'function' ? val(): val
Example
advance(1) // 1
advance(() => 1) // 1
and
Added from 1.1.0
Returns true
if both arguments are true; otherwise false
.
Signature:
and: <T, U>(a: T | AnyFn<any, T>, b: U | AnyFn<any, U>) => T extends FalsyLike ? false : U extends FalsyLike ? false : boolean
Parameters
Parameter | Description |
---|---|
a | The first input any value |
b | The second input any value |
=>
The result of !!a && !!bb
(if argument is function, return value)
Remark
If you pass a function as an argument, return value will evaluate.
Example
and(true, true) // true
and(false, true) // false
and(true, false) // false
and(false, false) // false
and(() => 1, () => 2) // true
and(() => 1, () => 0) // false
append
Added from 1.2.0
🔗 prepend 🔗
Returns a new list containing the contents of the given list, followed by the given value.
Signature:
append: <T, U>(val: T, list: U[]) => (T | U)[]
Parameters
Parameter | Description |
---|---|
val | The value to add to the end of the new list |
list | The list of elements to add a new item to |
=>
The result of [...list, val]
Example
append('Tom', ['hello']) // ['hello', 'Tom']
append('Tom', []) // ['Tom']
append(['Tom'], ['hello', 'world']) // ['hello', 'world', ['Tom']]
chunk
Added from 1.4.0
Return an array of elements split into groups the length of size.
Signature:
chunk: <T extends number, U extends readonly unknown[]>(size: T, array: U) => T extends 0 ? U : `${T}` extends `-${number}` ? U : U extends readonly [
] ? U : U extends readonly (infer R)[] ? R[][] : never
Parameters
Parameter | Description |
---|---|
size | The length of each chunk |
array | The array to process |
=>
Returns the new array of chunks
Remark
If array can't be split evenly, the final chunk will be the remaining elements.
Example 1
// Basic
chunk(1, ['a', 'b', 'c', 'd']) // [['a'], ['b'], ['c'], ['d']]
chunk(3, ['a', 'b', 'c', 'd']) // [['a', 'b', 'c'], ['d']]
chunk(5, ['a', 'b', 'c', 'd']) // [['a', 'b', 'c', 'd']]
Example 2
// Illegal size
chunk(0, ['a', 'b', 'c']) // ['a', 'b', 'c']
chunk(-3, ['a', 'b', 'c']) // ['a', 'b', 'c']
chunk(5, []) // []
constructorName
Added from 1.8.0
Safe getter for constructor.name
.
Signature:
constructorName: (val: unknown) => string
Parameters
Parameter | Description |
---|---|
val | Any value |
=>
If val
is null
or undefined
, empty string; otherwise constructor.name
Example
constructorName(null) // ''
constructorName(undefined) // ''
constructorName({}) // 'Object'
constructorName('') // 'String'
curry
Added from 1.9.0
beta
Creates a function that accepts arguments of fn
and either invokes fn
returning its result, if at least arity number of arguments have been provided, or returns a function that accepts the remaining fn
arguments, and so on.
WARNING
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Signature:
curry: <T extends unknown[], R>(fn: (...args: T) => R) => T["length"] extends 0 ? () => R : Curried<T, R>
Parameters
Parameter | Description |
---|---|
fn | The function to curry |
=>
The new curried function
Remark
Maximum number of arity is 19
. Beyond that, the type system will breaks.
Example
const replace = (from: string, to: string, val: string) => val.replace(from, to)
const curriedReplace = curry(replace)
const curriedReplace('hello', 'hi', 'hello world') // 'hi world'
const curriedReplace('hello')('hi', 'hello world') // 'hi world'
const curriedReplace('hello')('hi')('hello world') // 'hi world'
dec
Added from 1.1.0
🔗 inc
Decrements its argument.
Signature:
dec: {
(val: number): number;
(val: bigint): bigint;
}
Parameters
Parameter | Description |
---|---|
val | input number or bigint |
=>
Decremented val
Example
dec(100) // 99
dec(10n) // 9n
defaultTo
Added from 1.4.0
Returns the second argument if it is not null
, undefined
or NaN
; otherwise the first argument is returned.
Signature:
defaultTo: <T extends unknown>(a: T) => <U extends unknown>(b: U) => IsNil<U> extends true ? T : IsNumber<U> extends false ? U : T | U
Parameters
Parameter | Description |
---|---|
a | a will be returned instead of default |
=>
Returns a function that stores the default a
value. The function accept b
argument. if b
is null
, undefined
or NaN
, return a
; otherwise return b
Example
const defaultVal = defaultTo('anonymous')
defaultVal(undefined) // 'anonymous'
defaultVal(null) // 'anonymous'
defaultVal(NaN) // 'anonymous'
defaultVal('Tom') // 'Tom'
divide
Added from 1.0.0
Divide its second argument from its first argument.
Signature:
divide: {
(a: number, b: number): number;
(a: number): (b: number) => number;
(a: bigint, b: bigint): bigint;
(a: bigint): (b: bigint) => bigint;
} & {
(a: typeof _, b: number): (a: number) => number;
(a: typeof _, b: bigint): (a: bigint) => bigint;
}
Parameters
Parameter | Description |
---|---|
a | The first input number |
b | The second input number |
=>
The result of a / b
Remark
Since division is not idempotent, there are two ways to curry.
Example 1
// Number
divide(10, 100) // 0.1
Example 2
// Bigint
divide(1n, 2n) // 3n
Example 3
// First argument curry
const reciprocal = divide(1)
reciprocal(4) // 0.25
Example 4
// Second argument curry
import { _ } from 'fonction'
const half = divide(_, 2)
half(20) // 10
endsWith
Added from 1.0.0
deprecate
Checks if a string ends with the provided substring.
WARNING
This function will remove next major release.
Signature:
endsWith: <T extends string, U extends string | undefined = undefined>(val: T, target?: U | undefined) => EndsWith<U>
Parameters
Parameter | Description |
---|---|
val | Search string |
target | Target string |
=>
The result of target.endsWith(val)
Example 1
// Basic
endsWith('world', 'hello world') // true
endsWith('earth', 'hello world') // false
Example 2
// Curry
const endsWithHtml = endsWith('html')
endsWithHtml('index.html') // true
entries
Added from 1.6.0
deprecate
Returns an array of key/values of the enumerable properties of an object.
WARNING
This function will remove next major release.
Signature:
entries$0: {
<T>(val: {
[key: string]: T;
} | ArrayLike<T>): [string, T][];
(val: Record<string, unknown>): [string, unknown][];
}
Parameters
Parameter | Description |
---|---|
val | Object that contains the properties and methods |
=>
The result of Object.entries(val)
Remark
The order of the output array is not guaranteed to be consistent across different JS platforms.
Example
entries({ a: 'b' }) // [['a', 'b']]
entries(['a', 'b', 'c']) // [['0', 'a'], ['1', 'b'], ['2', 'c']]
entries({}) // []
entries([]) // []
equal
Added from 1.7.0
Returns true
if its arguments are equivalent, false
otherwise. Handles cyclical data structures.
Signature:
equal: <T, U extends T>(a: T, b: U) => boolean
Parameters
Parameter | Description |
---|---|
a | Input any value |
b | Input any value |
=>
Return true
if the reference memory is the same or the property members and their values are the same
Example
equals(-0, 0) // true
equals(NaN, NaN) // true
equals([[[[]]]], [[[[]]]]) // true
equals({ a: { b: [1, 2, 3]}}, { a: { b: [1, 2, 3]}}) // true
F
Added from 1.1.0
🔗 T
A function that always returns false
. Any passed in parameters are ignored.
Signature:
F: AnyFn<unknown, false>
Parameters
=>
false
Example
F() // false
F(1, 'hello', 'world') // false
first
Added from 1.0.0
🔗 last
Returns the first element of the given list or string.
Signature:
first: <T extends string | readonly unknown[]>(val: T) => First<T>
Parameters
Parameter | Description |
---|---|
val | String or any array object |
=>
The first element of the val
Example 1
// String
first('') // ''
first('hello') // 'h'
Example 2
// Array
first('hello', 'new', 'world') // 'hello'
first([]) // undefined
first(['one', 2, 3, 4]) // 'one'
flattenDeep
Added from 1.5.0
Recursively flattens array.
Signature:
flattenDeep: <T extends readonly unknown[]>(val: T) => FlattenDeep<T>
Parameters
Parameter | Description |
---|---|
val | The array to flatten |
=>
The result of val.flat(Infinity)
Example
flattenDeep([]) // []
flattenDeep([1, [2, [3, [4]], 5]]) // [1, 2, 3, 4, 5]
gt
Added from 1.1.0
Returns true
if the first argument is greater than the second; otherwise false
.
Signature:
gt: <T extends Ord>(a: T, b: T) => boolean
Parameters
Parameter | Description |
---|---|
a | The first input value |
b | The second input value |
=>
The result of a > b
Example 1
// Number
gt(2, 1) // true
gt(2, 2) // false
Example 2
// Bigint
gt(2n, 1n) // true
gt(2n, 2n) // false
Example 3
// String
gt('z', 'a') // true
gt('a', 'z') // false
Example 4
// Boolean
gt(true, false) // true
gt(false, true) // false
gt(true, true) // false
gt(false, false) // false
Example 5
// Date
gt(new Date('2000/1/2'), new Date('2000/1/1')) // true
gt(new Date('1999/12/31'), new Date('2000/1/1')) // false
gt(new Date('2000/1/1'), new Date('2000/1/1')) // false
gte
Added from 1.1.0
Returns true
if the first argument is greater than or equal to the second; otherwise false
.
Signature:
gte: <T extends Ord>(a: T, b: T) => boolean
Parameters
Parameter | Description |
---|---|
a | The first input value |
b | The second input value |
=>
The result of a >= b
Example 1
// Number
gte(2, 1) // true
gte(2, 2) // true
gte(2, 3) // false
Example 2
// Bigint
gte(2n, 1n) // true
gte(2n, 2n) // true
gte(2n, 3n) // false
Example 3
// String
gte('z', 'a') // true
gte('a', 'a') // true
gte('a', 'z') // false
Example 4
// Boolean
gte(true, false) // true
gte(true, true) // true
gte(false, false) // true
gte(false, true) // false
Example 5
// Date
gte(new Date('2000/1/2'), new Date('2000/1/1')) // true
gte(new Date('2000/1/1'), new Date('2000/1/1')) // true
gte(new Date('1999/12/31'), new Date('2000/1/1')) // false
has
Added from 1.2.0
🔗 props
Returns whether or not an object has an own property with the specified name.
Signature:
has: <T extends string | number | (string | number)[], U extends Record<PropertyKey, unknown>>(props: T, obj: U) => T extends unknown[] ? boolean : T extends string | number ? U extends Record<T, unknown> ? true : false : never
Parameters
Parameter | Description |
---|---|
props | The name of the property to check for |
obj | The check object |
=>
The result of Object.prototype.hasOwnProperty
Example 1
// Flat
has('hello', { hello: 'world' }) // true
has(0, { 0 : 1}) // true
has('', {}) // false
has('hello', { hi : hello: 'world' }) // false
Example 2
// Nest
hasPath(['hello'], { hello: 'world' }) // true
hasPath([0], { 0: 1 }) // true
hasPath(['hello', 'world'], { hello: { world: '' } } // true
hasPath(['hi'], { hello: '' } ) // false
hasPath(['hi', 'Tom'], { hi: { John: 1 } } ) // false
hasPath
Added from 1.2.0
🔗 has
deprecate
Returns whether or not a path exists in an object. Only the object's own properties are checked.
WARNING
This function will remove next major release.
Signature:
hasPath: <T extends unknown>(path: (string | number)[], obj: Record<PropertyKey, T>) => boolean
Parameters
Parameter | Description |
---|---|
path | The path to use |
obj | The object to check the path in |
=>
Whether the path exists
Example
hasPath(['hello'], { hello: 'world' }) // true
hasPath([0], { 0: 1 }) // true
hasPath(['hello', 'world'], { hello: { world: '' } } // true
hasPath(['hi'], { hello: '' } ) // false
hasPath(['hi', 'Tom'], { hi: { John: 1 } } ) // false
head
Added from 1.2.0
🔗 tail
Returns all but the last element of the given list or string.
Signature:
head: {
(val: string): string;
<T extends unknown[]>(val: T): T;
}
Parameters
Parameter | Description |
---|---|
val | string or any array object |
=>
The result of val.slice(0, -1)
Example 1
// String
head('hello') // 'hell'
head('h') // ''
head('') // ''
Example 2
head([1, 2, 3]) // [1, 2]
head(['hello', 'world']) // ['hello']
head(['hello']) // []
head([]) // []
identity
Added from 1.2.0
Return the parameter supplied to it.
Signature:
identity: <T>(val: T) => T
Parameters
Parameter | Description |
---|---|
val | The value to return |
=>
The result of val
Example
identity(1) // 1
identity({}) // {}
ifElse
Added from 1.6.0
🔗 ifElseFn
Return the onTrue
or the onFalse
value depending upon the result of the condition val
.
Signature:
ifElse: <V, T, F>(val: V | AnyFn<any, V>, onTrue: T | AnyFn<any, T>, onFalse: F | AnyFn<any, F>) => V extends FalsyLike ? F : V extends true ? T : T | F
Parameters
Parameter | Description |
---|---|
val | A predicate value |
onTrue | The val evaluates to a truthy value |
onFalse | The val evaluates to a falsy value |
=>
The result of !!val
? onTrue
: onFalse
(if argument is function, return value)
Remark
If you pass a function as an argument, return value will evaluate.
Example
ifElse(true, 1, 0) // 1
ifElse(false, 1, 0) // 0
ifElse(undefined, 1, 0) // 0
ifElse(() => true, () => 1, () => 0) // 1
ifElseFn
Added from 1.6.0
🔗 ifElse
Creates a function that will process either the onTrue
or the onFalse
function depending upon the result of the condition predicate.
Signature:
ifElseFn: <V, R, T, F>(condition: (val: V) => R, onTrue: T | ((val: V) => T), onFalse: F | ((val: V) => F)) => (val: V) => R extends true ? T : R extends FalsyLike ? F : T | F
Parameters
Parameter | Description |
---|---|
condition | A predicate function |
onTrue | Any value or A function to invoke when the condition evaluates to a truthy value |
onFalse | Any value or A function to invoke when the condition evaluates to a falsy value |
=>
A new function that will process either the onTrue
or the onFalse
function depending upon the result of the condition
predicate
Example
ifElseFn((x: number) => x > 10, 'big', 'small')(20) // 'big'
const fn = ifElseFn((x: number) => x > 10, (x) => x + 1, (x) => x - 1)
fn(11) // 12
fn(9) // 8
inc
Added from 1.1.0
🔗 dec
Increments its argument.
Signature:
inc: {
(val: number): number;
(val: bigint): bigint;
}
Parameters
Parameter | Description |
---|---|
val | Input number or bigint |
=>
Incremented val
Example
inc(100) // 101
inc(10n) // 11n
includes
Added from 1.9.0
Checks if value is in collection.
Signature:
includes: ((collection: string | unknown[], val: unknown) => boolean) & ((collection: string | unknown[]) => (val: unknown) => boolean)
Parameters
Parameter | Description |
---|---|
collection | The collection to inspect |
val | The value to search for |
=>
The result of collection.includes(val)
Example
includes('hello', 'lo') // true
includes([1, 2, 3], 3) // true
isArray
Added from 1.3.0
deprecate
Whatever argument is Array
or not.
WARNING
This function will remove next major release.
Signature:
isArray: (val: unknown) => val is any[]
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of Array.isArray(val)
Example
isArray([]) // true
isArray(['hello', 'world']) // true
isArray({}) // false
isBigint
Added from 1.0.0
deprecate
Whatever argument is type of bigint
or not.
WARNING
This function will remove next major release.
Signature:
isBigint: (val: unknown) => val is bigint
Parameters
Parameter | Description |
---|---|
val | input any value |
=>
The result of typeof val === 'bigint'
Example
isBigint(1n) // true
isBigint(1000) // false
isBoolean
Added from 1.0.0
deprecate
Whatever argument is type of boolean
or not.
WARNING
This function will remove next major release.
Signature:
isBoolean: (val: unknown) => val is boolean
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'boolean'
Example
isBoolean(true) // true
isBoolean('hello') // false
isEmpty
Added from 1.3.0
deprecate
Returns true
if the given value is its type's empty value; otherwise false
.
WARNING
This function will remove next major release.
Signature:
isEmpty: (val: unknown) => val is Empty
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of empty or not
Remark
The definition of Empty - ''
- {}
- []
Example
isEmpty('') // true
isEmpty({}) // true
isEmpty([]) // true
isEmpty('hello world') // false
isEmpty(1000) // false
isFunction
Added from 1.0.0
deprecate
Whatever argument is type of function
or not.
WARNING
This function will remove next major release.
Signature:
isFunction: (val: unknown) => val is AnyFn<any, unknown>
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'function'
Example
isFunction(function) // true
isFunction('hello') // false
isJSONObject
Added from 1.7.0
deprecate
Whatever argument is JSON Object or not.
WARNING
This function will remove next major release.
Signature:
isJSONObject: (val: unknown) => val is Record<PropertyKey, unknown>
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
if val
is JSON Object true
otherwise; false
Example
isJSONObject({ hoge: 'huga'}) // true
isJSONObject(Object()) // true
isJSONObject(new Object()) // true
isJSONObject([]) // false
isJSONObject(new Set()) // false
isLength0
Added from 1.8.0
deprecate
Whatever argument length is 0
or not.
WARNING
This function will remove next major release.
Signature:
isLength0: (val: unknown) => val is 0
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of !val.length
(if not have length
property, false
)
Example
isLength0([]) // true
isLength0([]) // true
isLength0('hello') // false
isLength0(undefined) // false
isNaN
Added from 1.4.0
deprecate
Whatever argument is NaN
or not.
WARNING
This function will remove next major release.
Signature:
isNaN: (val: unknown) => val is number
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of Number.isNaN(val)
Remark
NaN
is primitive number
.
Example
isNaN(NaN) // true
isNaN(100) // false
isNil
Added from 1.6.0
deprecate
Whatever argument is type of undefined
or null
.
WARNING
This function will remove next major release.
Signature:
isNil: (val: unknown) => val is null | undefined
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of type of val
is undefined
or null
Example
isNil(undefined) // true
isNil(null) // true
isNil([]) // false
isNill
Added from 1.0.0
deprecate
Whatever argument is type of undefined
or null
.
WARNING
This function will remove next major release.
Signature:
isNill: (val: unknown) => val is null | undefined
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of type of val
is undefined or null
Example
isNumber(0) // true
isNumber('hello') // false
isNull
Added from 1.0.0
deprecate
Whatever argument is type of null
or not.
WARNING
This function will remove next major release.
Signature:
isNull: (val: unknown) => val is null
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of val === null
Example
isNull(null) // true
isNull(undefined) // false
isNumber
Added from 1.0.0
deprecate
Whatever argument is type of number
or not.
WARNING
This function will remove next major release.
Signature:
isNumber: (val: unknown) => val is number
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'number'
Example
isNumber(0) // true
isNumber('hello') // false
isObject
Added from 1.0.0
deprecate
Whatever argument is type of object
or not.
WARNING
This function will remove next major release.
Signature:
isObject: (val: unknown) => val is Record<string, unknown>
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of object or not
Remark
Definition of Primitive - string
- number
- bigint
- boolean
- symbol
- undefined
- null
Example
isObject([]) // true
isObject('hello') // false
isPrimitive
Added from 1.0.0
deprecate
Whatever argument is primitive
or not.
WARNING
This function will remove next major release.
Signature:
isPrimitive: (val: unknown) => val is Primitive
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of primitive or not
Remark
Definition of Primitive - string
- number
- bigint
- boolean
- symbol
- undefined
- null
Example
isPrimitive(true) // true
isPrimitive([]) // false
isString
Added from 1.0.0
deprecate
Whatever argument is type of string
or not.
WARNING
This function will remove next major release.
Signature:
isString: (val: unknown) => val is string
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'string'
Example
isString('hello world') // true
isString(1000) // false
isSymbol
Added from 1.0.0
deprecate
Whatever argument is type of symbol
or not.
WARNING
This function will remove next major release.
Signature:
isSymbol: (val: unknown) => val is symbol
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'symbol'
Example
isSymbol(Symbol('hello')) // true
isSymbol('hello') // false
isUndefined
Added from 1.0.0
deprecate
Whatever argument is type of undefined
or not.
WARNING
This function will remove next major release.
Signature:
isUndefined: (val: unknown) => val is undefined
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of typeof val === 'undefined'
Example
isUndefined(undefined) // true
isUndefined('hello') // false
K
Added from 1.1.0
K combinator. Returns a function that always returns the given value.
Signature:
K: <T extends unknown>(val: T) => () => T
Parameters
Parameter | Description |
---|---|
val | The value to wrap in a function |
=>
Function wrapped val
Example
const k = K('k')
k() // 'k'
keys
Added from 1.3.0
deprecate
Returns the names of the enumerable string properties and methods of an object.
WARNING
This function will remove next major release.
Signature:
keys$0: <T extends PropertyKey>(val: Record<T, unknown>) => string[]
Parameters
Parameter | Description |
---|---|
val | Object that contains the properties and methods |
=>
The result of Object.keys(val)
Remark
The order of the output array is not guaranteed to be consistent across different JS platforms.
Example
keys({}) // []
keys({ 'a': 'b' }) // ['a']
keys({ 0: 'hello', 1: 'world' }) // ['0', '1']
last
Added from 1.0.0
🔗 first
Returns the last element of the given list or string.
Signature:
last: <T extends string | readonly unknown[]>(val: T) => Last<T>
Parameters
Parameter | Description |
---|---|
val | string or any array object |
=>
The last element of the val
Example 1
// String
last('hello') // 'o'
Example 2
// Array
last('hello', 'new', 'world') // 'world'
last([]) // undefined
last(['one', 2, 3, 4]) // 4
length
Added from 1.2.0
deprecate
Returns length property.
WARNING
This function will remove next major release.
Signature:
length: <T extends {
length: number;
}>(val: T) => T["length"]
Parameters
Parameter | Description |
---|---|
val | Value with length property |
=>
The result of val.length
Example
length('hello') // 5
length(['hello', 'world', 1]) // 3
length({length: 5, text: 'hello'}) // 5
lowerCase
Added from 1.0.1
deprecate
Return lowercase string.
WARNING
This function will remove next major release.
Signature:
lowerCase: <T extends string>(val: T) => Lowercase<T>
Parameters
Parameter | Description |
---|---|
val | Input string value |
=>
Lowercase string
Example
toLower('Hello') // hello
lt
Added from 1.1.0
Returns true
if the first argument is less than the second; otherwise false
.
Signature:
lt: <T extends Ord>(a: T, b: T) => boolean
Parameters
Parameter | Description |
---|---|
a | The first input value |
b | The second input value |
=>
The result of a < b
Example 1
// Number
lt(1, 2) // true
lt(2, 2) // false
Example 2
// Bigint
lt(1n, 2n) // true
lt(2n, 2n) // false
Example 3
// String
lt('a', 'z') // true
lt('a', 'a') // false
Example 4
// Boolean
lt(false, true) // true
lt(true, true) // false
lt(false, false) // false
lt(true, false) // false
Example 5
// Date
lt(new Date('1999/12/31'), new Date('2000/1/1')) // true
lt(new Date('2000/1/1'), new Date('2000/1/1')) // false
lt(new Date('2000/1/2'), new Date('2000/1/1')) // false
lte
Added from 1.1.0
Returns true
if the first argument is less than or equal to the second; otherwise false
.
Signature:
lte: <T extends Ord>(a: T, b: T) => boolean
Parameters
Parameter | Description |
---|---|
a | The first input value |
b | The second input value |
=>
The result of a <= b
Example 1
// Number
lte(1, 2) // true
lte(2, 2) // true
lte(2, 1) // false
Example 2
// Bigint
lte(1n, 2n) // true
lte(2n, 2n) // true
lte(2n, 1n) // true
Example 3
// String
lte('a', 'z') // true
lte('a', 'a') // true
lte('z', 'a') // false
Example 4
// Boolean
lte(true, true) // true
lte(false, false) // true
lte(false, true) // true
lte(true, false) // false
Example 5
// Date
lte(new Date('2000/1/1'), new Date('2000/1/1')) // true
lte(new Date('1999/12/31'), new Date('2000/1/1')) // true
lte(new Date('2000/1/2'), new Date('2000/1/1')) // false
map
Added from 1.6.0
deprecate
Takes a function, applies the function to each, and returns a result of the same shape.
WARNING
This function will remove next major release.
Signature:
map: {
<T extends readonly unknown[], U>(fn: (value: T[number], index: number, list: T) => U, list: T): MapArray<U, T>;
<T extends {
[k: string]: unknown;
}, U>(fn: (val: T[keyof T], prop: keyof T, list: T) => U, list: T): MapObject<U, T>;
}
Parameters
Parameter | Description |
---|---|
fn | The function to be called on every element of the input list. |
list | The list to be iterated over. |
=>
The result of list.map(fn)
or object applied function to value
Example
const triple = (val: number):number => val * 3
map(triple, [1, 2, 3]) // [3, 6, 9]
map(triple, { tom: 1, john: 2, bob: 3 }) // { tom: 3, john: 6, bob: 9}
multiply
Added from 1.0.0
Multiplies first argument and second argument.
Signature:
multiply: {
(a: number, b: number): number;
(a: number): (b: number) => number;
(a: bigint, b: bigint): bigint;
(a: bigint): (b: bigint) => bigint;
}
Parameters
Parameter | Description |
---|---|
a | The first input number |
b | The second input number |
=>
The result of a * b
Example 1
// Basic
multiply(2, 3) // 6
Example 2
// Bigint
multiply(2n, 3n) // 6n
Example 3
// Curry
const double = multiply(2)
double(4) // 8
N
Added from 1.6.0
🔗 NN
Returns the !
of its argument.
Signature:
N: <T>(val: T) => T extends FalsyLike ? true : boolean
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of !val
Remark
The Definition of Falsy - ''
- false
- 0
- NaN
- undefined
- null
Example
N('') // true
N(false) // true
N(0) // true
N(NaN) // true
N(undefined) // true
N(null) // true
N({}) // false
N([]) // false
NN
Added from 1.6.0
🔗 N
Abbreviation for Not Not. Returns the !!
of its argument.
Signature:
NN: <T>(val: T) => T extends FalsyLike ? false : boolean
Parameters
Parameter | Description |
---|---|
val | Input any value |
=>
The result of !!val
Remark
The Definition of Falsy - ''
- false
- 0
- NaN
- undefined
- null
Example
NN('') // false
NN(false) // false
NN(0) // false
NN(NaN) // false
NN(undefined) // false
NN(null) // false
NN({}) // true
NN([]) // true
not
Added from 1.3.0
Returns the function as is with return value !
.
Signature:
not: <T extends AnyFn<any, unknown>>(fn: T) => (...val: Parameters<T>) => boolean
Parameters
Parameter | Description |
---|---|
val | Input any function |
=>
The result is function what return value with !
Example
not(() => true)() // false
const gt10 = (val: number) => val > 10
not(gt10)(11) // false
or
Added from 1.1.0
Returns true if one or both of its arguments are true; otherwise false.
Signature:
or: <T, U>(a: T | AnyFn<any, T>, b: U | AnyFn<any, U>) => T extends FalsyLike ? U extends FalsyLike ? false : boolean : boolean
Parameters
Parameter | Description |
---|---|
a | The first input any value |
b | The second input any value |
=>
The result of !!a || !!bb
(if argument is function, return value)
Remark
If you pass a function as an argument, return value will evaluate.
Example
or(true, true) // true
or(false, true) // true
or(true, false) // true
or(false, false) // false
or(() => 0, () => 1) // true
or(() => 0, () => 0) // false
pipe
Added from 1.8.0
Performs left-to-right function composition.
Signature:
pipe: Pipe
Parameters
Parameter | Description |
---|---|
functions | Multi any functions |
=>
A function
what argument is function[0]
argument
Remark
The first argument may have any arity; the remaining arguments must be unary.
Example
const fn = pipe(add , inc)
fn(1, 1) // 3
prepend
Added from 1.2.0
🔗 append
Returns a new list with the given value at the front, followed by the contents of the list.
Signature:
prepend: <T, U>(val: T, list: U[]) => (T | U)[]
Parameters
Parameter | Description |
---|---|
val | The value to add to the front of the new list |
list | The list of elements to add a new item to |
=>
The result of [val, ...list]
Example
prepend('Tom', ['hello']) // ['Tom', 'hello']
prepend('Tom', []) // ['Tom']
prepend(['Tom'], ['hello', 'world']) // [['Tom'], 'hello', 'world']
product
Added from 1.2.0
Multiplies together all the elements of a list.
Signature:
product: {
(val: [
]): 0;
(val: number[]): number;
(val: bigint[]): bigint;
}
Parameters
Parameter | Description |
---|---|
val | list An array of numbers |
=>
The product of all the numbers in the list
Example
product([1, 2, 3, 4, 5]) // 120
product([1n, 2n, 3n, 4n, 5n]) //120n
product([]) // 0
props
Added from 1.4.0
🔗 has
Returns a function that when supplied an object returns the indicated property of that object, if it exists.
Signature:
props: <T extends string | number, U extends Record<PropertyKey, unknown>>(val: T, obj: U) => U extends Record<T, unknown> ? U[T] : undefined
Parameters
Parameter | Description |
---|---|
val | Input property key |
obj | The object to query |
=>
The result of safety obj[val]
or obj[val[0]][val[1]][val[...x]]
Example
props('x', { x: 'hello' }) // 'hello'
props(1, { 1: 100 }) // 100
props('x', {}) // undefined
replace
Added from 1.5.0
deprecate
Replaces matches for from
in string with to
.
WARNING
This function will remove next major release.
Signature:
replace: <From extends string, To extends string, T extends string>(from: From, to: To, val: T) => Replace<T, From, To>
Parameters
Parameter | Description |
---|---|
from | Holds the pattern string that need to replace |
to | Holds the replacement string |
val | Original string |
=>
The result of val.replace(from, to)
Example
replace('hello Tom', 'Tom', 'Bob') // 'hello Bob'
replace('hogehoge', 'hoge', 'fuga') // 'fugahoge'
replaceAll
Added from 1.5.0
🔗 replace
deprecate
Replaces all matches for from
in string with to
.
WARNING
This function will remove next major release.
Signature:
replaceAll: <From extends string, To extends string, T extends string>(from: From, to: To, val: T) => ReplaceAll<T, From, To>
Parameters
Parameter | Description |
---|---|
from | Holds the pattern string that need to replace |
to | Holds the replacement string |
val | Original string |
=>
The result of val.replaceAll(from, to)
Example
replaceAll('hello Tom', 'Tom', 'Bob') // 'hello Bob'
replaceAll('hogehoge', 'hoge', 'fuga') // 'fugafuga'
reverse
Added from 1.0.0
deprecate
Returns a new list or string with the elements or characters in reverse order.
WARNING
This function will remove next major release.
Signature:
reverse: {
(val: string): string;
(val: ""): "";
<T extends [
]>(val: T): [
];
<T extends unknown[]>(val: T): T;
}
Parameters
Parameter | Description |
---|---|
val | list or string characters |
=>
New list or string characters in reverse order
Example 1
// String
reverse('hello') // 'olleh'
Example 2
// Any Array
reverse(['hello', 'new', 'world']) // ['world', 'new', 'hello']
reverse([0, {}, []]) // [[], {}, 0]
slice
Added from 1.6.0
deprecate
Returns the elements of the given string or array from from
to to
.
WARNING
This function will remove next major release.
Signature:
slice: <T extends string | readonly unknown[]>(from: number, to: number, val: T) => T
Parameters
Parameter | Description |
---|---|
from | The start index |
to | The end index |
val | String or Array |
=>
The result of val.slice(from, to)
Example 1
// String
slice(6, 11 ,'hello world') // 'world'
Example 2
// Array
slice(1, 2 ,[1, 2, 3, 4]) // [2]
startsWith
Added from 1.0.0
🔗 endsWith
deprecate
Checks if a string starts with the provided substring.
WARNING
This function will remove next major release.
Signature:
startsWith: <T extends string, U extends string | undefined = undefined>(val: T, target?: U | undefined) => StartsWith<U>
Parameters
Parameter | Description |
---|---|
val | search string |
target | target string |
=>
The result of target.startsWith(val)
Example 1
// Basic
startsWith('hello', 'hello world') // true
startsWith('good', 'hello world') // false
Example 2
// Curry
const startWithSlash = startsWith('/')
startWithSlash('/path/to') // true
subtract
Added from 1.0.0
Subtracts its second argument from its first argument.
Signature:
subtract: {
(a: number, b: number): number;
(a: number): (b: number) => number;
(a: bigint, b: bigint): bigint;
(a: bigint): (b: bigint) => bigint;
} & {
(a: typeof _, b: number): (a: number) => number;
(a: typeof _, b: bigint): (a: bigint) => bigint;
}
Parameters
Parameter | Description |
---|---|
a | The first input number |
b | The second input number |
=>
The result of a - b
Remark
Since subtraction is not idempotent, there are two ways to curry.
Example 1
// Number
subtract(2, 1) // 1
Example 2
// Bigint
subtract(3n, 2n) //1n
Example 3
// First argument curry
const from5Minus = subtract(5)
from5Minus(10) // -5
Example 4
// Second argument curry
import { _ } from 'fonction'
const minus5 = (_, 5)
minus5(20) // 15
sum
Added from 1.0.0
Adds together all the elements of a list.
Signature:
sum: {
(val: [
]): 0;
(val: number[]): number;
(val: bigint[]): bigint;
}
Parameters
Parameter | Description |
---|---|
val | list An array of numbers |
=>
The sum of all the numbers in the list
Example
sum([1, 2, 3, 4, 5]) // 15
sum([1n, 2n, 3n, 4n, 5n]) // 15n
sum([]) // 0
T
Added from 1.1.0
🔗 F
A function that always returns true
. Any passed in parameters are ignored.
Signature:
T: AnyFn<unknown, true>
Parameters
=>
True
Example
T() // true
T(1, 'hello', 'world') // true
tail
Added from 1.2.0
🔗 head
Returns all but the first element of the given list or string.
Signature:
tail: {
(val: string): string;
<T extends unknown[]>(val: T): T;
}
Parameters
Parameter | Description |
---|---|
val | string or any array object |
=>
The result of val.slice(1, Infinity)
Example 1
// String
tail('hello') // 'ello'
tail('h') // ''
tail('') // ''
Example 2
tail([1, 2, 3]) // [2, 3]
tail(['hello', 'world']) // ['world']
tail(['hello']) // []
tail([]) // []
take
Added from 1.6.0
Return a slice of string or array with n
elements taken from the beginning.
Signature:
take: <T extends string | readonly unknown[]>(howMany: number, val: T) => T
Parameters
Parameter | Description |
---|---|
howMany | The number of elements to take |
val | String or Array to query |
=>
The slice of array
Example 1
// String
take(3, 'hello') // 'hel'
Example 2
// Array
take(3, [1, 2, 3, 4]) // [1, 2, 3]
takeLast
Added from 1.6.0
Return a slice of string or array with n
elements taken from the end.
Signature:
takeLast: <T extends string | readonly unknown[]>(howMany: number, val: T) => T
Parameters
Parameter | Description |
---|---|
howMany | The number of elements to take |
val | String or Array to query |
=>
The slice of array
Example 1
// String
takeLast(3, 'hello') // 'llo'
Example 2
// Array
takeLast(3, [1, 2, 3, 4]) // [2, 3, 4]
tap
Added from 1.9.0
Runs the given function with the supplied value, then returns the value.
Signature:
tap: <T>(fn: Arity1Fn<T, unknown>) => <R extends T>(val: R) => R
Parameters
Parameter | Description |
---|---|
fn | The function to call with val . The return value of fn will be thrown away. |
=>
The result of (val) => fn(val)
Example
tap(console.log)('hello') // hello
// log: hello
test
Added from 1.9.0
deprecate
whether a given string
matches a given regular expression.
WARNING
This function will remove next major release.
Signature:
test: ((regExp: RegExp, val: string) => boolean) & ((regExp: RegExp) => (val: string) => boolean)
Parameters
Parameter | Description |
---|---|
regExp | Any Regular expression |
val | Any string value |
=>
The result is regExp.test(val)
Example
test(new RegExp('^test'), 'testdata') // true
test(/xyz$/, 'testxyz') // true
trim
Added from 1.1.0
deprecate
Removes whitespace from both ends of the string.
WARNING
This function will remove next major release.
Signature:
trim: <T extends string>(val: T) => TrimLeft<TrimRight<T>>
Parameters
Parameter | Description |
---|---|
val | string to trim |
=>
The result of val.trim()
Example
trim(' hello ') // 'hello'
trimLeft
Added from 1.5.0
deprecate
Removes space from left ends of the string.
WARNING
This function will remove next major release.
Signature:
trimLeft: <T extends string>(val: T) => TrimLeft<T>
Parameters
Parameter | Description |
---|---|
val | input string |
=>
The result of val.trimLeft()
Remark
The definition of space - ''
- \n
- \t
Example
trimLeft(' hello') // 'hello'
trimLeft(' \n\thello') // 'hello'
trimRight
Added from 1.5.0
deprecate
Removes space from right ends of the string.
WARNING
This function will remove next major release.
Signature:
trimRight: <T extends string>(val: T) => TrimRight<T>
Parameters
Parameter | Description |
---|---|
val | input string |
=>
The result of val.trimRight()
Remark
The definition of space - ''
- \n
- \t
Example
trimRight('hello ') // 'hello'
trimRight('hello \n\t') // 'hello'
tryCatch
Added from 1.8.0
tryCatch
takes two functions, a tryer
and a catcher
. The returned function evaluates the tryer
; if it does not throw, it simply returns the result. If the tryer
does throw, the returned function evaluates the catcher function and returns its result.
Signature:
tryCatch: <R, E, P = unknown>(tryer: AnyFn<any, R>, catcher?: E | AnyFn<P, E> | undefined) => R | E
Parameters
Parameter | Description |
---|---|
tryer | The function that may throw. |
catcher | The function that will be evaluated if tryer throws. |
=>
- The result of try { tryer() } catch(e) { catcher(e) }
Example
tryCatch(() => { throw Error('error') }) // Error('error')
tryCatch(() => { throw Error('error') }, 0) // 0
tryCatch(() => { throw Error('error') }, (e: Error) => e.message ) // 'error'
uniq
Added from 1.8.0
🔗 equal
Returns a new Array
containing only one copy of each element in the original array. equal
is used to determine equality.
Signature:
uniq: <T extends unknown>(val: readonly T[]) => T[]
Parameters
Parameter | Description |
---|---|
val | Input any array |
=>
The list of unique items
Example
uniq([1, 2, 1, 1]) // [1, 2]
uniq([{}, {}, [], []]) // [{}, []]
uniq([[1, 2, 3], [1, 2, 3]]) // [[1, 2, 3]]
upperCase
Added from 1.0.1
deprecate
Return uppercase string.
WARNING
This function will remove next major release.
Signature:
upperCase: <T extends string>(val: T) => Uppercase<T>
Parameters
Parameter | Description |
---|---|
val | Input string value |
=>
Uppercase string
Example
toUpper('Hello') // HELLO
values
Added from 1.3.0
deprecate
Returns an array of values of the enumerable properties of an object.
WARNING
This function will remove next major release.
Signature:
values$0: <T extends unknown>(val: Record<PropertyKey, T> | ArrayLike<T>) => T[]
Parameters
Parameter | Description |
---|---|
val | Object that contains the properties and methods |
=>
The result of Object.values(val)
Remark
The order of the output array is not guaranteed to be consistent across different platforms.
Example 1
// Object
values({}) // []
values({ 'a': 'b' }) // ['b']
values({ 0: 'hello', 1: 'world' }) // ['hello', 'world']
Example 2
// Array
values([]) // []
values(['hello', 'world']) // ['hello', 'world']
xor
Added from 1.1.0
Returns true if one of the arguments is truthy and the other is falsy; otherwise false.
Signature:
xor: <T, U>(a: T | AnyFn<any, T>, b: U | AnyFn<any, U>) => T extends FalsyLike ? U extends FalsyLike ? false : boolean : boolean
Parameters
Parameter | Description |
---|---|
a | The first input any value |
b | The second input any value |
=>
The result of !a !== !b
(if argument is function, return value)
Example
xor(true, false) // true
xor(false, true) // true
xor(true, true) // false
xor(false, false) // false
xor(() => 1, () => 0) // true
xor(() => 0, () => 0) // false
Types
AnyFn
Added from 1.0.0
Type of any function.
Signature:
type AnyFn<T = any, U = unknown> = (...args: T[]) => U;
Arity1Fn
Added from 1.9.0
Type of arity 1 function.
Signature:
type Arity1Fn<T = any, U = unknown> = (args: T) => U;
Empty
Added from 1.3.0
Alias for Empty values
Signature:
type Empty = "" | [
] | {};
Falsy
Added from 1.3.0
deprecate
Alias for Falsy values.
WARNING
This function will remove next major release.
Signature:
type Falsy = false | "" | 0 | null | undefined;
FalsyLike
Added from 1.6.0
Alias for Falsy values.
Signature:
type FalsyLike = false | "" | 0 | 0n | null | undefined;
Remark
This is not a strict Falsy
. TypeScript type system cannot define NaN
.
Remark
Alias
First
Added from 1.4.0
🔗 Last
Infer the first types.
Signature:
type First<T extends readonly unknown[] | string> = T extends "" ? "" : T extends string ? String2Array<T> extends [
] ? string : String2Array<T>[0] : T extends readonly never[] | [
] ? undefined : T[0];
Parameters
=>
First element of the T
Example 1
// String
First<string> // string
First<''> // ''
First<'hello'> // 'h'
Example 2
// Array
First<[] | never[] | readonly [] | readonly never[]> // undefined
First<['hello', 'world']> // 'hello'
First<string | number[]> // string | number
FlattenDeep
Added from 1.5.0
Infer deep flatted array.
Signature:
type FlattenDeep<T extends readonly unknown[]> = T extends readonly [
infer A,
...infer Rest
] ? A extends readonly unknown[] ? [
...FlattenDeep<A>,
...FlattenDeep<Rest>
] : [
A,
...FlattenDeep<Rest>
] : [
...T
];
Parameters
=>
Deep flatted array
Example
FlattenDeep<[]> // []
FlattenDeep<[[1, [2, [3, [4]], 5]]> // [1, 2, 3, 4, 5]
Last
Added from 1.4.0
🔗 First
Infer the last types.
Signature:
type Last<T extends string | readonly unknown[]> = T extends "" ? "" : T extends string ? String2Array<T> extends [
] ? string : [
never,
...String2Array<T>
][String2Array<T>["length"]] : T extends never[] | readonly never[] ? undefined : T extends unknown[] | readonly unknown[] ? [
never,
...T
][T["length"]] : T extends string ? string : never;
Example 1
// String
Last<string> // string
Last<''> // ''
Last<'hello'> // 'o'
Example 2
// Array
Last<[] | never[] | readonly [] | readonly never[]> // undefined
Last<['hello', 'world']> // 'world'
Last<string | number[]> // string | number
Ord
Added from 1.1.0
Abbreviation for Ordinal.
Signature:
type Ord = string | number | bigint | boolean | Date;
Primitive
Added from 1.0.0
Alias for Primitive values types.
Signature:
type Primitive = string | number | bigint | boolean | symbol | undefined | null;
Replace
Added from 1.5.0
deprecate
Infer the replacement value.
WARNING
This function will remove next major release.
Signature:
type Replace<T extends string, From extends string, To extends string> = From extends "" | To ? T : T extends `${infer L}${From}${infer R}` ? `${L}${To}${R}` : T;
Example
Replace<'hello Tom', 'Tom', 'Bob'> // 'hello Bob'
Replace<'hogehoge', 'hoge', 'fuga'> // 'fugahoge'
ReplaceAll
Added from 1.5.0
🔗 Replace
deprecate
Infer the all replacement value.
WARNING
This function will remove next major release.
Signature:
type ReplaceAll<T extends string, From extends string, To extends string> = From extends "" | To ? T : T extends `${infer L}${From}${infer R}` ? `${L}${ReplaceAll<`${To}${R}`, From, To>}` : T;
Example
ReplaceAll<'hello Tom', 'Tom', 'Bob'> // 'hello Bob'
ReplaceAll<'hogehoge', 'hoge', 'fuga'> // 'fugafuga'
Space
Added from 1.5.0
Alias for Space values.
Signature:
type Space = " " | "\n" | "\t";
Trim
Added from 1.5.0
deprecate
Infer the trimmed string.
WARNING
This function will remove next major release.
Signature:
type Trim<T extends string> = TrimLeft<TrimRight<T>>;
Parameters
=>
Trimmed string
Remark
The definition of space - ''
- \n
- \t
Example
Trim<'\t\n hello \t\n'> // 'hello'
TrimLeft
Added from 1.5.0
deprecate
Infer the string with the left ends of trimmed.
WARNING
This function will remove next major release.
Signature:
type TrimLeft<T extends string> = T extends `${Space}${infer R}` ? TrimLeft<R> : T;
Parameters
=>
String left ends of trimmed
Remark
The definition of space - ''
- \n
- \t
Example
TrimLeft<' \n\thello'> // 'hello'
TrimRight
Added from 1.5.0
deprecate
Infer the string with the right ends of trimmed.
WARNING
This function will remove next major release.
Signature:
type TrimRight<T extends string> = T extends `${infer R}${Space}` ? TrimRight<R> : T;
Parameters
=>
String right ends of trimmed
Remark
The definition of space - ''
- \n
- \t
Example
TrimRight<'hello \n\t'> // 'hello'
Constants
_
Added from 1.6.1
Placeholder to indicate that the argument is not explicitly set.
Signature:
_: unique symbol
Parameters
=>
The results of Symbol('_')
1.9.1-beta.1