Object Utilities

The Object utilities provide a set of functions for working with objects in JavaScript. These functions help in manipulating, transforming, and querying objects efficiently.

Functions

keys

function keys(obj)

Return keys from an object.

Parameters

Returns

An array of the object’s keys, or undefined if the input is not an object.

Example

import { keys } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3 };
console.log(keys(obj)); // ['a', 'b', 'c']

values

function values(obj)

Return values from an object.

Parameters

Returns

An array of the object’s values, or undefined if the input is not an object.

Example

import { values } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3 };
console.log(values(obj)); // [1, 2, 3]

filterObject

function filterObject(obj, callback)

Filter an object based on a callback function.

Parameters

Returns

A new object with the key-value pairs that passed the test.

Example

import { filterObject } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3, d: 4 };
const result = filterObject(obj, (value) => value % 2 === 0);
console.log(result); // { b: 2, d: 4 }

mapObject

function mapObject(obj, callback)

Transform an object’s values based on a callback function.

Parameters

Returns

A new object with transformed values.

Example

import { mapObject } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3 };
const result = mapObject(obj, (value) => value * 2);
console.log(result); // { a: 2, b: 4, c: 6 }

trackWrites

function trackWrites(value, callback, { strategy = 'auto', returnPaths = true, keyed = true, keys = ['id', '_id', 'hash', 'key'], onWrite, clone, equality } = {})

Runs a callback against a value and reports whether the callback changed it, with the changed fields as dot paths. Useful for running a user callback against a data structure and determining mutations.

Strategy - The default strategy ‘auto’ will use snapshot for small data structures and proxy for larger. Snapshot improves debugging by passing you a real copy, while proxy preserves performance at the cost of passing you a proxyObject inside your callback. Keyed paths (the default) come from the snapshot diff, so when they are wanted 'auto' yields to snapshot even for a large value — an explicit 'proxy' strategy keeps the no-clone path at the cost of positional paths.

Parameters

Options

Returns

{ changed, paths, result } — whether the value changed, the changed fields as dot paths, and the callback’s return value.

Notes

paths is a covering set resolvable through get. The snapshot strategy reports net leaf differences via detectChanges and id-addresses keyed arrays by default (field[#id]). The proxy strategy reports the paths written (pruned so a written parent subsumes its children) and these are always positional — the proxy only sees the index a write went through. A wholesale change to a non-container value reports path ''. Under the proxy strategy the tracked wrapper is only valid inside the callback — using one after it returns throws.

Example

import { trackWrites, get } from '@semantic-ui/utils';

const doc = { meta: { count: 0 } };
const { changed, paths } = trackWrites(doc, (value) => {
  value.meta.count++;
});
console.log(changed); // true
console.log(paths); // ['meta.count']

// paths resolve against the value, e.g. for state sync
paths.forEach((path) => sync(path, get(doc, path)));

// keyed paths by default — a field edit across a collection reads back per
// record, not by index, with zero configuration
const db = { todos: [{ id: 'a', complete: false }, { id: 'b', complete: false }] };
const completeAll = trackWrites(db, (d) => {
  for (const todo of d.todos) { todo.complete = true; }
});
console.log(completeAll.paths); // ['todos[#a].complete', 'todos[#b].complete']

// the proxy strategy is the positional opt-out (no element identity)
trackWrites(db, mutator, { strategy: 'proxy' }); // paths like ['todos.0.complete']

// skip path collection on hot paths
trackWrites(doc, mutator, { returnPaths: false }); // { changed, result }

trackReads

function trackReads(value, callback, { returnPaths = true, keyed = true, keys = ['id', '_id', 'hash', 'key'], onRead } = {})

Runs a callback against a value and reports which paths it read — the read companion to trackWrites. Where trackWrites answers “what did this change”, trackReads answers “what did this depend on”: collecting a computed function’s dependencies, deriving a memoization key from the values it touched, auditing least-privilege access, or learning what to prefetch.

Proxy only - Reads are observable only through a proxy (there is no before/after to diff, so unlike trackWrites there is no snapshot strategy). The value is wrapped read-only: the callback may read any depth, but a write through the wrapper throws, so the input is never mutated. The wrapper is only valid inside the callback — using one after it returns throws.

Parameters

Options

Returns

{ reads, structure, result } — the value paths read, the container shapes read, and the callback’s return value.

Notes

Two dependency kinds come back, kept apart because they invalidate on different writes:

• reads — value paths (todos[#id].done), resolvable through get, pruned so a deeper read subsumes its ancestors. Pairs with detectChanges changed.
• structure — container paths whose shape was read: an array’s .length, iteration, spread, or Object.keys. Pairs with detectChanges added/removed.

Surfacing structure separately is the array-growth case: reading an array’s length leaves no value path behind, so a value-only dependency set would silently miss a push. Reading a method (.reduce) is not itself a dependency — the property reads that method then performs are. An exotic (Date/Map/Set/RegExp) is a single read with no recursion into its internals. A frozen subtree is immutable, so it has no dependencies and is read only at its boundary.

Example

import { trackReads, get } from '@semantic-ui/utils';

const state = { todos: [{ id: 'a', done: false }, { id: 'b', done: true }] };
const { reads, structure } = trackReads(state, (value) =>
  value.todos.map((todo) => todo.done));
console.log(reads);     // ['todos[#a].done', 'todos[#b].done']
console.log(structure); // ['todos']

// reads resolve back through get(), e.g. for a memoization key — and the keyed
// paths survive a reorder of the list
reads.map((path) => get(state, path)); // [false, true]

// pair with the write side: re-run when a read value changes (changed) or when
// a read container grows or shrinks (added/removed)
// reads     ↔ detectChanges.changed
// structure ↔ detectChanges.added / removed

// onRead streams each read live, typed, for dependency collectors
trackReads(state, (value) => value.todos.length, {
  onRead: (path, type) => console.log(type, path), // 'value' todos, 'structure' todos
});

// positional opt-out, and hot-path streaming without collection
trackReads(state, reader, { keyed: false });        // paths like ['todos.0.done']
trackReads(state, reader, { returnPaths: false, onRead });

elementKey

function elementKey(item, keys = ['id', '_id', 'hash', 'key'])

The identity of an array element — the value of the first present field in keys, or undefined for a scalar or an object carrying none of them. The same convention as reactivity’s Signal.id and the renderer’s getItemID, and what the keyed detectChanges mode and the keyed get / set / unset grammar match on.

Parameters

Returns

The identity value, or undefined when none of the fields are present.

Example

import { elementKey } from '@semantic-ui/utils';

console.log(elementKey({ id: 'a', _id: 'x' })); // 'a'
console.log(elementKey({ name: 'n' }));         // undefined
console.log(elementKey({ sku: 's1' }, ['sku'])); // 's1'

detectChanges

function detectChanges(before, after, {
  keyed = true,
  keys = ['id', '_id', 'hash', 'key'],
  equality = isEqual,
  ignoreKeys = null,
  collapseKeys = null,
} = {})

Structural diff between two values, reported as dot paths from before to after — added (in after only), removed (in before only), and changed (in both, different values).

Parameters

Options

Returns

{ added, removed, changed } — arrays of dot paths.

Notes

Objects recurse to leaf paths. Values that can’t be walked (Map, Set, Date, class instances) compare by deep equality and report their own path. Differing non-container roots report path ''.

By default, an array whose elements are each uniquely keyed (see elementKey) diffs by identity instead of position. It emits field[#identity] paths — field[#z] for a whole-element add, remove, or replace, field[#b].qty for a field change — so a prepend or reorder is one add by key, not a positional cascade of index rewrites. Any array that isn’t cleanly keyed (a scalar or unkeyed element, a duplicate key, or a key value carrying ., [, ], or a leading #) falls back to the positional walk, so an emitted keyed path always parses back through get / set / unset. Pass { keyed: false } for the legacy positional output, where arrays diff by index and a shifted array reports every moved position.

collapseKeys gives a plain-object key the same whole-value treatment a Map or Date already gets — the walk stops at the key and reports it as one path instead of descending. This is for a subtree whose own keys aren’t addressable wire paths, like a map keyed by dynamic contacts[#id].field strings that would mis-parse if emitted nested. A wholesale add or remove of the key still reports as add or remove, and a change anywhere inside reports the key as changed. ignoreKeys is the complement — those keys leave the changeset entirely.

Example

import { detectChanges } from '@semantic-ui/utils';

const before = { name: 'a', temp: true, count: 1 };
const after = { name: 'b', count: 1, nickname: 'al' };

console.log(detectChanges(before, after));
// { added: ['nickname'], removed: ['temp'], changed: ['name'] }

// arrays of keyed objects diff by identity — a prepend plus an edit is one add
const cartBefore = { lineItems: [{ id: 'a', qty: 1 }, { id: 'b', qty: 1 }] };
const cartAfter = { lineItems: [{ id: 'z', qty: 9 }, { id: 'a', qty: 1 }, { id: 'b', qty: 5 }] };
console.log(detectChanges(cartBefore, cartAfter));
// { added: ['lineItems[#z]'], removed: [], changed: ['lineItems[#b].qty'] }

// scalar arrays (no element identity) fall back to the positional walk
console.log(detectChanges({ items: [1, 2, 3] }, { items: [1, 9] }));
// { added: [], removed: ['items.2'], changed: ['items.1'] }

// { keyed: false } restores the positional cascade for keyed objects too
console.log(detectChanges(cartBefore, cartAfter, { keyed: false }));
// { added: ['lineItems.2'], removed: [], changed: ['lineItems.0.id', 'lineItems.0.qty', 'lineItems.1.id'] }

// equality swaps the comparator — '1' and 1 are not a change under ==
console.log(detectChanges({ a: 1 }, { a: '1' }, { equality: (x, y) => x == y }));
// { added: [], removed: [], changed: [] }

// ignoreKeys drops a field at any depth; collapseKeys reports a subtree whole
console.log(detectChanges(
  { name: 'a', _overrides: { 'contacts[#1].field': true }, updatedAt: 1 },
  { name: 'b', _overrides: { 'contacts[#1].field': false }, updatedAt: 2 },
  { ignoreKeys: ['updatedAt'], collapseKeys: ['_overrides'] },
));
// { added: [], removed: [], changed: ['name', '_overrides'] }

extend

function extend(obj, ...sources)

Extend an object with properties from other objects, properly handling getter/setters.

Parameters

Returns

The extended object.

Example

import { extend } from '@semantic-ui/utils';

const obj1 = { a: 1, b: 2 };
const obj2 = { c: 3 };
const obj3 = { d: 4 };
const result = extend(obj1, obj2, obj3);
console.log(result); // { a: 1, b: 2, c: 3, d: 4 }

assignInPlace

function assignInPlace(target, source, { preserveExistingKeys = false, preserveGetters = false, returnChanged = false } = {})

Mutates the target object in place so its contents match the source, without replacing the object reference. Deletes keys not present in source (unless preserveExistingKeys is true), then assigns all source properties.

Parameters

Options

Returns

The mutated target object. If returnChanged is true, returns a boolean indicating whether any properties were added, removed, or changed.

Example

import { assignInPlace } from '@semantic-ui/utils';

const config = { host: 'localhost', port: 3000, debug: true };
assignInPlace(config, { host: 'production.app', port: 443 });
console.log(config); // { host: 'production.app', port: 443 } — debug removed

// Preserve existing keys
const settings = { theme: 'light', lang: 'en' };
assignInPlace(settings, { theme: 'dark', fontSize: 14 }, { preserveExistingKeys: true });
console.log(settings); // { theme: 'dark', lang: 'en', fontSize: 14 }

// Preserve computed properties
const view = { name: 'Alice' };
Object.defineProperty(view, 'greeting', { get() { return `Hi, ${this.name}`; }, enumerable: true });
assignInPlace(view, { name: 'Bob' }, { preserveGetters: true });
console.log(view.greeting); // 'Hi, Bob' — getter intact

// Detect changes
const state = { count: 5 };
assignInPlace(state, { count: 5 }, { returnChanged: true }); // false
assignInPlace(state, { count: 10 }, { returnChanged: true }); // true

deepExtend

function deepExtend(obj, ...sources, options)

Deep extends an object with properties from other sources, recursively merging nested plain objects and cloning non-plain objects.

Parameters

Options

Returns

The modified target object with deep merged properties.

Example

import { deepExtend } from '@semantic-ui/utils';

const target = {
  user: { name: 'Alice', age: 30 },
  settings: { theme: 'light' }
};

const source = {
  user: { role: 'admin' },
  settings: { notifications: true }
};

deepExtend(target, source);
console.log(target);
// {
//   user: { name: 'Alice', age: 30, role: 'admin' },
//   settings: { theme: 'light', notifications: true }
// }

pick

function pick(obj, ...keys)

Create a new object with only the specified keys from the original object.

Parameters

Returns

A new object with only the specified keys.

Example

import { pick } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3, d: 4 };
const result = pick(obj, 'a', 'c');
console.log(result); // { a: 1, c: 3 }

arrayFromObject

function arrayFromObject(obj)

Convert an object to an array of key-value pairs.

Parameters

Returns

An array of key-value pair objects.

Example

import { arrayFromObject } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3 };
const result = arrayFromObject(obj);
console.log(result); // [{ key: 'a', value: 1 }, { key: 'b', value: 2 }, { key: 'c', value: 3 }]

get

function get(obj, path = '', keys = ['id', '_id', 'hash', 'key'])

Access a nested object field from a string path, like ‘a.b.c’.

Parameters

Returns

The value at the specified path, or undefined if not found.

Notes

A bracket segment whose body starts with # selects an array element by identity (items[#id]) rather than by position (items[0]). Identity is matched String-coerced (a number id of 7 matches [#7]), see elementKey. Returns the element when the path ends at the key, or undefined when no element matches.

Example

import { get } from '@semantic-ui/utils';

const obj = { a: { b: { c: 42 } } };
console.log(get(obj, 'a.b.c')); // 42
console.log(get(obj, 'a.b.d')); // undefined

const doc = { items: [{ id: 'a', n: 1 }, { id: 'b', n: 2 }] };
console.log(get(doc, 'items[#b].n')); // 2 (selected by identity, not position)

set

function set(obj, path, value, keys = ['id', '_id', 'hash', 'key'])

Set a nested object field from a string path, the write twin of get. Creates missing intermediates — arrays when the next segment is a numeric index, objects otherwise.

Parameters

Returns

The same object reference.

Notes

Paths from trackWrites and detectChanges apply back directly. Prototype-climbing segments (__proto__, constructor, prototype) are refused, and a non-string or empty path is a no-op.

A [#id] segment addresses an array element by identity (see elementKey): a present key replaces the element in place (or writes the field through it), an absent key appends a new element (a field write through an absent key is a no-op). The prototype-pollution guard is intentionally not extended to keyed bodies — a [#__proto__] value is only ===-compared against element identities, it is never used as a property name, so it appends an inert element rather than touching Object.prototype.

Example

import { set, get, trackWrites } from '@semantic-ui/utils';

console.log(set({}, 'a.b.c', 1)); // { a: { b: { c: 1 } } }
console.log(set({}, 'items.0.name', 'first')); // { items: [{ name: 'first' }] }

// sync changes between objects
const { paths } = trackWrites(source, mutator);
paths.forEach((path) => set(replica, path, get(source, path)));

// keyed addressing — replace by identity, append when absent
const doc = { items: [{ id: 'a', n: 1 }] };
set(doc, 'items[#a]', { id: 'a', n: 100 }); // replaces in place
set(doc, 'items[#b]', { id: 'b', n: 2 });   // appends, no element had id 'b'

unset

function unset(obj, path, keys = ['id', '_id', 'hash', 'key'])

Remove a nested object field from a string path, the delete twin of get and set.

Parameters

Returns

The same object reference.

Notes

A missing path is a no-op. A removed array index leaves a hole rather than splicing, so sibling index paths stay valid when applying several removals at once. Prototype-climbing segments (__proto__, constructor, prototype) are refused. Pairs with detectChanges — apply removed paths with unset and the rest with set.

A [#id] segment removes the matched array element by identity (see elementKey), splicing it out — there are no sibling index paths to keep valid, so the splice is safe.

Example

import { unset, set, get, detectChanges } from '@semantic-ui/utils';

const obj = { a: { b: 1, c: 2 } };
unset(obj, 'a.b');
console.log(obj); // { a: { c: 2 } }

// apply a full diff
const diff = detectChanges(before, after);
[...diff.added, ...diff.changed].forEach((path) => set(replica, path, get(after, path)));
diff.removed.forEach((path) => unset(replica, path));

keyedPath

function keyedPath(obj, path, keys = ['id', '_id', 'hash', 'key'])

The keyed spelling of a positional path — rewrites each positional array segment (items.0 or items[1]) to its [#id] form where the addressed element carries a path-safe identity, resolved against obj at call time. A positional address is only stable while the array doesn’t move, the keyed address survives a reorder — the same identity detectChanges emits in its keyed mode.

Parameters

Returns

The keyed spelling as a new string, or the input path itself (the same reference) when nothing rewrites — so keyedPath(obj, path) === path cheaply tells you the address was already stable.

Notes

Only a segment whose element carries a path-safe identity (see elementKey) rewrites. Keyless arrays, inner value lists, unresolvable paths, and already-keyed spellings pass through unchanged. A leading index (the root itself being an array) stays positional, since get and set can’t parse a leading bracket. The emitted [#id] paths apply back through get/set/unset and match the keyed output of detectChanges.

Example

import { keyedPath, get } from '@semantic-ui/utils';

const doc = { items: [{ id: 'a', qty: 1 }, { id: 'b', qty: 2 }] };
console.log(keyedPath(doc, 'items.0.qty')); // 'items[#a].qty'
console.log(keyedPath(doc, 'items[1]'));    // 'items[#b]'

// keyless and unresolvable paths pass through — same reference when nothing rewrites
const path = 'plain.0.n';
console.log(keyedPath({ plain: [{ n: 1 }] }, path) === path); // true

// the keyed address survives a reorder that shifts every positional index
const target = keyedPath(doc, 'items.1.qty'); // 'items[#b].qty'
doc.items.unshift({ id: 'z', qty: 9 });
console.log(get(doc, 'items.1.qty')); // 1 (positional now hits a)
console.log(get(doc, target));        // 2 (keyed still hits b)

proxyObject

function proxyObject(sourceObj = noop, referenceObj = {})

Create a proxy object that combines properties from a source object and a reference object.

Parameters

Returns

A proxy object combining properties from both objects.

Example

import { proxyObject } from '@semantic-ui/utils';

const source = () => ({ a: 1, b: 2 });
const reference = { c: 3 };
const proxy = proxyObject(source, reference);
console.log(proxy.a); // 1
console.log(proxy.c); // 3

onlyKeys

function onlyKeys(obj, keysToKeep)

Create a new object with only the specified keys from the original object.

Parameters

Returns

A new object with only the specified keys.

Example

import { onlyKeys } from '@semantic-ui/utils';

const obj = { a: 1, b: 2, c: 3, d: 4 };
const result = onlyKeys(obj, ['a', 'c']);
console.log(result); // { a: 1, c: 3 }

hasProperty

function hasProperty(obj, prop)

Check if an object has a non-inherited property.

Parameters

Returns

True if the object has the property, false otherwise.

Example

import { hasProperty } from '@semantic-ui/utils';

const obj = { a: 1, b: 2 };
console.log(hasProperty(obj, 'a')); // true
console.log(hasProperty(obj, 'toString')); // false

reverseKeys

function reverseKeys(obj)

Reverse the keys and values of an object.

Parameters

Returns

A new object with reversed keys and values.

Example

import { reverseKeys } from '@semantic-ui/utils';

const obj = { a: '1', b: ['2', '3'] };
const result = reverseKeys(obj);
console.log(result); // { '1': 'a', '2': 'b', '3': 'b' }

These object utilities provide a robust set of tools for working with objects in JavaScript, enhancing productivity and code readability.

Performs a weighted search across an array of objects, with matches prioritized by where they occur in the text.

Search Priority Results are sorted by match quality, with highest priority given to exact start of string matches (e.g., searching “cat” matching “category”), followed by word-start matches (e.g., “category” in “my category”), then substring matches anywhere, and finally partial word matches. When searching multiple words, matches are weighted by how many words were found in the text.

Parameters

Options

Understanding Matches When returnMatches is true, each result is a spread copy of the original object with an added matches array property. The original objects are never mutated. Each match has the shape { field, type, score, value } where type is one of 'startsWith', 'wordStartsWith', 'anywhere', or 'anyWord'.

Returns

Array of matching objects sorted by relevance. When returnMatches is true, each result is a shallow copy with an additional matches property containing an array of match details.

Example

import { weightedObjectSearch } from '@semantic-ui/utils';

const items = [
  { title: 'Hello World', desc: 'A greeting' },
  { title: 'World News', desc: 'Current events' }
];

// Basic search
const results = weightedObjectSearch('world', items, {
  propertiesToMatch: ['title', 'desc']
});

// With match details (does not mutate originals)
const detailed = weightedObjectSearch('world', items, {
  propertiesToMatch: ['title', 'desc'],
  returnMatches: true,
});
// detailed[0].matches → [{ field: 'title', type: 'startsWith', score: 1, value: 'World News' }]