@aricma/itemids

ItemIds (object)

Be faster in creating and updating react state, with ItemIds.

During the last year(2019-2020) I had to write a bunch of different components which had all slightly different logic with the same kind of state. I extracted the shared logic and put it in a object.

Usage

# with npm
npm install @aricma/itemids

# with yarn
yarn add @aricma/itemids

ItemIds can be use anywhere where their is selection:

• ImageGalleries
• DropDown
• Steps
• Checkbox
• Radio
• Tags
• Collapse
• Tiles
• d3 charts

example for react state:

function Gallery({ images }) {
    // STATE HANDLER HOOK
    const { selection, toggle } = useGalleryState();
    
    return (
        <div>
            {
                images.map(({ id, name, src }) => {
                    const isSelected = selection.has(id)
                    return (
                        <Image
                            key={index}
                            isSelected={isSelected} // for styling in Image
                            alt={name}
                            src={src}
                            onClick={ toggle(id) }
                        />
                    )
                })
            }
        </div>
    )
}

function useGalleryState() {
    // STATE
    const [selection, setSelection] = useState(ItemIds()); // [] -> [1,2,3] the ids of the images
    
    // ACTIONS
    function toggle(id) {
        return function() {
            setSelection(prevSelection => prevSelection.toggle(id))
        }
    }
    
    return { selection, toggle }
}

example for react effects:

function useGalleryState(initialSelection) {
    // STATE
    const [selection, setSelection] = useState(ItemIds(initialSelection));

    // ACTIONS
    // ...
    
    // EFFECTS
    useEffect(() => {
        if(!selection.isEqualTo(initialelection)) {
            setSelection(prevSelection => prevSelection.set(initialelection))
        }
    }, [initialSelection])
    
    return { selection, toggle }
}

API

ItemIds is a function returning an array object. ItemIds has some "util" methods on it. The methods on the returned object however are extensions to the Js Array object.

Checkout the .test files to see in detail how the methods on ItemIds can be used.

// create a new ItemIds object
// ItemIds is an extended Array. so everything that you would do with Arrays can be done with ItemIds
let itemIds = ItemIds(); // []
itemIds = ItemIds([1,2,3]); // [1,2,3]


// constructor methods or utils
// these methods are helpful for validating the input of an ItemIds object

// every ItemIds object has a name="ItemIds" property
// ItemIds.isItemIds iss checking for that value
ItemIds.isItemIds([]); // false
ItemIds.isItemIds(itemIds); // true

// ids should either be string or number but not NaN
ItemIds.isItemId(1); // true
ItemIds.isItemId(true); // false

ItemIds.isItemIdList([1,"2",3]); // true
ItemIds.isItemIdList([1,2, {}]); // false

ItemIds.unify([1,2,2,3]); // [1,2,3]


// methods
// these methods are helpful setting and updating the "state"
// all methods on the ItemIds object are returning "this" so they can be piped
ItemIds() // []

// set
// is good for custom actions and also for testing your state with e.g. jest
.set([2]) // [2]
.set(prev => [1,prev[0],3]) // [1,2,3]
.set() // [] reset
.set([1,2,3]) // [1,2,3]

// add
.add(1) // [1]
.add([2,3]) // [1,2,3]

// remove
.remove(1) // [2,3]
.remove([2,3]) // []

// toggle
// is a shortcut for when you want the logic to listen for a "click" event 
.toggle(1) // [1]
.toggle([1,2]) // [2]
.toggle([1,2,3]) // [1,3]

// toggleAll
// is taking all possible ids as argument
// is perfect for an "select all" button 
.toggleAll([1,2,3]) // [1,2,3]
.toggleAll([1,2,3]) // []

// has
// is especially helpful with styling the already selected
.set([1,2,3])
.has(1) // true
.has([1,2]) // true
.has([1,2,4]) // false

// isEqualTo
// is very helpful in useEffects when updating the state based on changes from the outside
.isEqualTo([1,2,3]) // true
.isEqualTo([1,2,3,4]) // false

Changelog

• v2.1.0: ItemIds does no longer allow duplicate values
• v2.0.0: all custom properties on the object are now hidden. Now you can write tests much easier.

// jest
// NOW
test("some initial state test", () => {
    expect(ItemIds()).toEqual([]) 
});

// BEFORE v2.0.0
test("some initial state test", () => {
    const state = ItemIds();
    
    expect(Array.isArray(state)).toBeTruthy()
    expect(state.length).toBe(0)
});

• v1.1.0: until here the package was broken and not installable XD

Feedback && Support

If this package is in any way helpful to you, I would love to hear about your use cases. You can contact me via the contact form on my website. I am eager to hear your stories.

If you have experienced any bugs or just want to request a feature, please do so via the issue board on github.

I can and will not implement every function some dude is demanding! But if your feature is a good one or a recurring request, why not ;).