Collection Helpers

Look up, update, and remove objects in an array signal by identity. Each item is matched by its id, resolved through the signal’s id option, which defaults to the first present of id, _id, hash, or key.

Identity

getId

signal.getId(item);

Resolves an item’s id through the signal’s id resolver. A primitive item is its own id.

Parameters

Returns

The resolved id, or undefined if none is present.

Usage

const users = signal([{ id: 'u1', name: 'Alice' }]);

users.getId(users.peek()[0]); // 'u1'
users.getId('u1');            // 'u1', a primitive is its own id

getIds

signal.getIds(item);

Returns every id value present on an object, in id, _id, hash, key order. Unlike getId, this ignores the signal’s resolver and reports all candidate keys.

Parameters

Returns

An array of the id values found. A primitive returns a single-element array of itself.

Usage

const users = signal([{ _id: '1', id: 'u1', name: 'Alice' }]);

users.getIds(users.peek()[0]); // ['u1', '1']

hasId

signal.hasId(item, id);

Reports whether an item resolves to the given id.

Parameters

Returns

true if the item’s resolved id matches id.

Lookup

getItem

signal.getItem(id);

Returns the item in the array matching id. Subscribes the running reaction through the underlying read.

Parameters

Returns

The matching item, or undefined if none matches.

Example

getItemIndex

signal.getItemIndex(id);

Returns the array index of the item matching id.

Parameters

Returns

The index of the matching item, or -1 if none matches.

Mutation

setItemProperty

signal.setItemProperty(id, property, value);

Sets a single property on the array item matching id, notifying dependents only when the value changes.

Parameters

Usage

const users = signal([
  { id: 'u1', name: 'Alice' },
  { id: 'u2', name: 'Bob' },
]);

users.setItemProperty('u1', 'status', 'active');

Example

setProperty

signal.setProperty(property, value);

On an object, sets the property. On an array, sets the property on every item.

Parameters

Usage

const profile = signal({ name: 'Alice', status: 'idle' });

profile.setProperty('status', 'active');

On an array, it sets the property on every item.

const todos = signal([
  { id: 't1', done: true },
  { id: 't2', done: false },
]);

todos.setProperty('done', false); // every item now done: false

replaceItem

signal.replaceItem(id, item);

Swaps the item matching id for a new one. No-ops if no item matches.

Parameters

Usage

const users = signal([
  { id: 'u1', name: 'Alice' },
  { id: 'u2', name: 'Bob' },
]);

users.replaceItem('u1', { id: 'u1', name: 'Alex' });

Example

removeItem

signal.removeItem(id);

Removes the item matching id from the array. No-ops if no item matches.

Parameters

Usage

const users = signal([
  { id: 'u1', name: 'Alice' },
  { id: 'u2', name: 'Bob' },
]);

users.removeItem('u1');

Example

By Index

setIndexProperty

signal.setIndexProperty(index, property, value);

Sets a property on the array item at index, notifying once if the value changed. Keys by position rather than id, so use setItemProperty when you have one.

Parameters

Usage

const users = signal([
  { id: 'u1', name: 'Alice' },
  { id: 'u2', name: 'Bob' },
]);

users.setIndexProperty(0, 'status', 'active');

Toggling

toggleItemProperty

signal.toggleItemProperty(id, property);

Flips a boolean field on the array item matching id, notifying when it changes.

Parameters

Usage

const todos = signal([
  { id: 't1', done: false },
  { id: 't2', done: true },
]);

todos.toggleItemProperty('t1', 'done'); // t1.done is now true

toggleProperty

signal.toggleProperty(property);

On an object, flips the property. On an array, flips the property on every item.

Parameters

Usage

const panel = signal({ open: false });
panel.toggleProperty('open'); // open is now true

const todos = signal([
  { id: 't1', done: true },
  { id: 't2', done: false },
]);
todos.toggleProperty('done'); // every item's done is flipped