diff --git a/docs/array/toggle.mdx b/docs/array/toggle.mdx index 43eab58c..d81737a5 100644 --- a/docs/array/toggle.mdx +++ b/docs/array/toggle.mdx @@ -16,7 +16,7 @@ _.toggle(gods, 'ra') // => ['zeus', 'loki'] _.toggle(gods, 'vishnu') // => ['ra', 'zeus', 'loki', 'vishnu'] ``` -### toggle(list, item, identity) +### 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. @@ -34,7 +34,7 @@ _.toggle(gods, ra, g => g.name) // => [zeus, loki] _.toggle(gods, vishnu, g => g.name) // => [ra, zeus, loki, vishnu] ``` -### toggle(list, item, identity, options) +### 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. diff --git a/src/array/toggle.ts b/src/array/toggle.ts index 1ffa10aa..03129afb 100644 --- a/src/array/toggle.ts +++ b/src/array/toggle.ts @@ -1,6 +1,19 @@ /** - * If the item matching the condition already exists in the list it - * will be removed. If it does not it will be added. + * 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-org.github.io/reference/array/toggle * @example @@ -23,11 +36,7 @@ export function toggle( array: readonly T[], item: T, - /** - * Converts an item of type T item into a value that can be checked - * for equality. For an item idx will be -1. - */ - toKey?: null | ((item: T, idx: number) => number | string | symbol), + toKey?: ((item: T, idx: number) => number | string | symbol) | null, options?: { strategy?: 'prepend' | 'append' },