toggle

Toggles an item's existence in an array

Usage

If the item matching the condition already exists in the list it will be removed. If it does not it will be added.

import * as 
import _
_ from 'radashi'

const 
const gods: string[]
gods = ['ra', 'zeus', 'loki']

import _
_.
toggle<string>(array: readonly string[], item: string, toKey?: ((item: string, idx: number) => number | string | symbol) | null | undefined, options?: {
    strategy?: "prepend" | "append";
}): string[]
export toggle
Either adds or removes an item from an array, based on whether it
already exists in the array. If multiple items match the given
item, all matching items will be removed.
Note that the given array is not mutated. A copy of the array
is returned with the given item either added or removed.


"toKey" parameter

You may define a toKey callback, which is a function that
converts an item into a value that can be checked for equality.
When called with the given item, an index of -1 will be passed.



"strategy" option

You may define a strategy option, which determines where the
item should be added in the array.


@see ― https://radashi.js.org/reference/array/toggle
@example 
toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
toggle([1, 2, 3], 2) // => [1, 3]

toggle(
  [
    { id: 1 },
    { id: 2 },
  ],
  { id: 3 },
  (obj) => obj.id,
  { strategy: 'prepend' }
)
// => [{ id: 3 }, { id: 1 }, { id: 2 }]
@version ― 12.1.0
toggle(
const gods: string[]
gods, 'ra') // => ['zeus', 'loki']
import _
_.
toggle<string>(array: readonly string[], item: string, toKey?: ((item: string, idx: number) => number | string | symbol) | null | undefined, options?: {
    strategy?: "prepend" | "append";
}): string[]
export toggle
Either adds or removes an item from an array, based on whether it
already exists in the array. If multiple items match the given
item, all matching items will be removed.
Note that the given array is not mutated. A copy of the array
is returned with the given item either added or removed.


"toKey" parameter

You may define a toKey callback, which is a function that
converts an item into a value that can be checked for equality.
When called with the given item, an index of -1 will be passed.



"strategy" option

You may define a strategy option, which determines where the
item should be added in the array.


@see ― https://radashi.js.org/reference/array/toggle
@example 
toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
toggle([1, 2, 3], 2) // => [1, 3]

toggle(
  [
    { id: 1 },
    { id: 2 },
  ],
  { id: 3 },
  (obj) => obj.id,
  { strategy: 'prepend' }
)
// => [{ id: 3 }, { id: 1 }, { id: 2 }]
@version ― 12.1.0
toggle(
const gods: string[]
gods, 'vishnu') // => ['ra', 'zeus', 'loki', 'vishnu']

toggle(list, item, toKey)

You can pass an optional toKey function to determine the identity of non-primitive values. Helpful when working with more complex data types.

import * as 
import _
_ from 'radashi'

const 
const ra: {
    name: string;
}
ra = { 
name: string
name: 'Ra' }
const 
const zeus: {
    name: string;
}
zeus = { 
name: string
name: 'Zeus' }
const 
const loki: {
    name: string;
}
loki = { 
name: string
name: 'Loki' }
const 
const vishnu: {
    name: string;
}
vishnu = { 
name: string
name: 'Vishnu' }

const 
const gods: {
    name: string;
}[]
gods = [
const ra: {
    name: string;
}
ra, 
const zeus: {
    name: string;
}
zeus, 
const loki: {
    name: string;
}
loki]

import _
_.
toggle<{
    name: string;
}>(array: readonly {
    name: string;
}[], item: {
    name: string;
}, toKey?: ((item: {
    name: string;
}, idx: number) => number | string | symbol) | null | undefined, options?: {
    strategy?: "prepend" | "append";
}): {
    name: string;
}[]
export toggle
Either adds or removes an item from an array, based on whether it
already exists in the array. If multiple items match the given
item, all matching items will be removed.
Note that the given array is not mutated. A copy of the array
is returned with the given item either added or removed.


"toKey" parameter

You may define a toKey callback, which is a function that
converts an item into a value that can be checked for equality.
When called with the given item, an index of -1 will be passed.



"strategy" option

You may define a strategy option, which determines where the
item should be added in the array.


@see ― https://radashi.js.org/reference/array/toggle
@example 
toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
toggle([1, 2, 3], 2) // => [1, 3]

toggle(
  [
    { id: 1 },
    { id: 2 },
  ],
  { id: 3 },
  (obj) => obj.id,
  { strategy: 'prepend' }
)
// => [{ id: 3 }, { id: 1 }, { id: 2 }]
@version ― 12.1.0
toggle(
const gods: {
    name: string;
}[]
gods, 
const ra: {
    name: string;
}
ra, 
g: {
    name: string;
}
g => 
g: {
    name: string;
}
g.
name: string
name) // => [zeus, loki]
import _
_.
toggle<{
    name: string;
}>(array: readonly {
    name: string;
}[], item: {
    name: string;
}, toKey?: ((item: {
    name: string;
}, idx: number) => number | string | symbol) | null | undefined, options?: {
    strategy?: "prepend" | "append";
}): {
    name: string;
}[]
export toggle
Either adds or removes an item from an array, based on whether it
already exists in the array. If multiple items match the given
item, all matching items will be removed.
Note that the given array is not mutated. A copy of the array
is returned with the given item either added or removed.


"toKey" parameter

You may define a toKey callback, which is a function that
converts an item into a value that can be checked for equality.
When called with the given item, an index of -1 will be passed.



"strategy" option

You may define a strategy option, which determines where the
item should be added in the array.


@see ― https://radashi.js.org/reference/array/toggle
@example 
toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
toggle([1, 2, 3], 2) // => [1, 3]

toggle(
  [
    { id: 1 },
    { id: 2 },
  ],
  { id: 3 },
  (obj) => obj.id,
  { strategy: 'prepend' }
)
// => [{ id: 3 }, { id: 1 }, { id: 2 }]
@version ― 12.1.0
toggle(
const gods: {
    name: string;
}[]
gods, 
const vishnu: {
    name: string;
}
vishnu, 
g: {
    name: string;
}
g => 
g: {
    name: string;
}
g.
name: string
name) // => [ra, zeus, loki, vishnu]

toggle(list, item, toKey, options)

By default, toggle will append the item if it does not exist. If you need to prepend the item instead you can override the strategy in the options argument.

import * as 
import _
_ from 'radashi'

const 
const gods: string[]
gods = ['ra', 'zeus', 'loki']

import _
_.
toggle<string>(array: readonly string[], item: string, toKey?: ((item: string, idx: number) => number | string | symbol) | null | undefined, options?: {
    strategy?: "prepend" | "append";
}): string[]
export toggle
Either adds or removes an item from an array, based on whether it
already exists in the array. If multiple items match the given
item, all matching items will be removed.
Note that the given array is not mutated. A copy of the array
is returned with the given item either added or removed.


"toKey" parameter

You may define a toKey callback, which is a function that
converts an item into a value that can be checked for equality.
When called with the given item, an index of -1 will be passed.



"strategy" option

You may define a strategy option, which determines where the
item should be added in the array.


@see ― https://radashi.js.org/reference/array/toggle
@example 
toggle([1, 2, 3], 4) // => [1, 2, 3, 4]
toggle([1, 2, 3], 2) // => [1, 3]

toggle(
  [
    { id: 1 },
    { id: 2 },
  ],
  { id: 3 },
  (obj) => obj.id,
  { strategy: 'prepend' }
)
// => [{ id: 3 }, { id: 1 }, { id: 2 }]
@version ― 12.1.0
toggle(
const gods: string[]
gods, 'vishnu', 
g: string
g => 
g: string
g, { 
strategy?: "prepend" | "append"
strategy: 'prepend' }) // => ['vishnu', 'ra', 'zeus', 'loki']