SHIFT + D

Filter by package

  • Overview
  • Ancestor variants
  • Composition
  • Edge
  • Features
  • Linear numeric
  • Logic
  • Prose
  • Source transform
  • SPA links
  • Utilities

Pickable

Updated on August 22, 2024Source codeTests

Pickable is a class that enriches an array, allowing it to:

  • Store the index-based location of items that have been picked
  • Retrieve the items that have been picked
  • Store a status (ready, picked, or omitted)
  • Replace existing picks using different strategies, like FIFO or LIFO
  • Omit specific picks, or all picks

Construct a Pickable instance

The Pickable constructor accepts two parameters:

Parameter
Type
Required
Description
array
Array
yes
The array that will be made pickable.
options
Object
no
Options for the Pickable instance. See the Pickable constructor options section for more guidance.

Pickable constructor options

Option
Type
Default
Description
initialPicks
Number, Array
[]

The Pickable instance's initial index-based picks.

initialPicks should be a number or an array of numbers.

State and methods

Property
Type
Description
Parameters
Return value
array
Getter/Setter
See return value
N/A

A shallow copy (Array) of the array passed to the Pickable constructor.

If you assign a value directly to array, a setter will pass the new value to setArray.

picks
Getter/Setter
See return value
N/A

An array of index-based locations (Number) stored by the Pickable instance. Defaults to the initialPicks option passed to the constructor.

If you assign a value directly to picks, a setter will pass the new value to setPicks.

picks are stored in the order that they were picked, not in order of lowest-to-highest index.

first
Getter
See return value
N/A
The first pick, i.e. the lowest index in picks.
last
Getter
See return value
N/A
The last pick, i.e. the highest index in picks
oldest
Getter
See return value
N/A
The first index in picks
newest
Getter
See return value
N/A
The last index in picks
multiple
Getter
See return value
N/A
A boolean indicating whether or not picks contains more than one index
items
Getter
See return value
N/A
The items (can be any type) located at the picks indices in array
status
Getter
See return value
N/A
The status (String) of the Pickable instance. status is ready after the instance is constructed, and changes to picked a successful pick, or omitted after a successful omission.
setArray(array)
Function
Sets the Pickable instance's array
The new array (Array)
The Pickable instance
setPicks(picks)
Function
An alias for the pick method, but it doesn't support the optional options argument.
The new picks (Number or Array)
The Pickable instance
pick(indexOrIndices[, options])
Function

Picks a specific item or more than one item, identified by their index-based positions in the array.

See the How Pickable picks section for more information on how options affect picking.

The index-based position (Number) of the item that should be picked, or an array of index-based positions for multiple picks. Also accepts an optional options argument.
The Pickable instance
omit([indexOrIndices])
Function

Omits (removes from picks) a specific item or more than one item, identified by their index-based positions in the array.

When called with no arguments, omit omits every pick from picks, leaving only an empty array.

Optional: the index-based position (Number) of the item that should be picked, or an array of index-based positions for multiple picks.
The Pickable instance

How Pickable picks

In general, whenever the setPicks or pick methods are called, the Pickable instance computes the new picks and stores their index-based locations in its picks property.

Picks are stored in the order that they were picked, not in order of lowest-to-highest index. Duplicate picks are ignored.

import { Pickable } from '@baleada/logic'

const pickable = new Pickable(myArray)

pickable.pick(4)
pickable.pick(2)
pickable.pick(420)
pickable.pick(42)

pickable.picks // -> [4, 2, 420, 42]
pickable.first // -> 2
pickable.last // -> 420
pickable.oldest // -> 4
pickable.newest // -> 42

The only other thing you need to know about how your Pickable instance picks is what options are available for the pick method, and how those options affect the way Pickable computes the final picks.

pick accepts an optional options object as its second argument. Here's a breakdown of the options object:

Option
Type
Default
Description
replace
String
none

When replace is set to none, Pickable will append the new index or indices to its existing picks.

When replace is set to all, Pickable will clear out all the existing picks, and replace them with the new index or indices passed to the pick method.

When replace is set to fifo, Pickable will add the new picks, then remove the oldest picks until the picks array reaches its previous length.

When replace is set to lifo, Pickable removes the most recent picks to make room for the new picks, so that the array maintains its previous length.

allowsDuplicates
Boolean
false
When allowsDuplicates is set to true, Pickable will allow duplicate picks to be stored in picks.

Using with TypeScript

The Pickable constructor accepts one generic type that you can use to enforce a type for the items in array. By default, TypeScript will infer the item type from the initial array you pass to the constructor, but you can specify the type manually if needed.

const withInferredTypes = new Pickable([1, 2, 3])
withInferredTypes.array = ['a', 'b', 'c'] // Type error

const withManualTypes = new Pickable<string | number>([1, 2, 3])
withManualTypes.array = ['a', 'b', 'c'] // No type error

API design compliance

Spec
Compliance status
Notes
Access functionality by constructing an instance
Constructor accepts two parameters: a piece of state, and an options object.
Constructor does not access the DOM
Takes the form of a JavaScript Object
State and methods are accessible through properties of the object
Methods always return the instance
Stores the constructor's state in a public getter named after the state's type
array
Has a public method you can use to set a new value for that public getter
setArray
Has a setter for that getter so you can assign a new value directly
Any other public getters that should be set by you in some cases also have setters and set<Property> methods
picks, setPicks
Has at least one additional getter property that you can't (and shouldn't) set directly
status, first, last, oldest, newest, items, multiple
Has one or more public methods that expose core functionality
pick, omit
Either has no side effects or has side effects that can be cleaned up with a stop method
no side effects
Uses the sentence template to decide what state type should be accepted by a constructor
"An array can be picked."
Constructor does not accept options that only customize the behavior of public methods, it allows those options to be passed to the method itself as a parameter.
pick(indexOrIndices[, options])
Named after its core action, proper-cased and suffixed with able

NavigateableRecognizeable

Edit doc on GitHub

ON THIS PAGE

PickableConstruct a Pickable instancePickable constructor optionsState and methodsHow Pickable picksUsing with TypeScriptAPI design compliance