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

Name	Type	Description
obj	object	The object to get keys from

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

Name	Type	Description
obj	object	The object to get values from

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

Name	Type	Description
obj	object	The object to filter
callback	function	The callback function to test each key-value pair

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

Name	Type	Description
obj	object	The object to transform
callback	function	The callback function to transform each value

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, 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 preserve performance at the cost of passing you a proxyObject inside your callback

Parameters

Name	Type	Description
value	any	The value the callback may change
callback	function	Receives the value (or its tracked wrapper)
options	object	Optional configuration

Options

Name	Type	Default	Description
strategy	string	’auto’	`'auto'`, `'snapshot'`, or `'proxy'`
returnPaths	boolean	true	Return changed fields as dot paths. Pass `false` to skip collection on hot paths that only read `changed`
onWrite	function	undefined	`(path, target, key)` fires per observed write with the key path from the root. Implies the proxy strategy under `'auto'`
clone	function	clone	Clone used for snapshots
equality	function	isEqual	Equality used when paths are skipped and for exotic snapshots

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 proxy strategy reports the paths written (pruned so a written parent subsumes its children), the snapshot strategy reports net leaf differences via detectChanges. 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)));

// writing the same value is not a change
trackWrites(doc, (value) => {
  value.meta.count = 1;
}); // { changed: false, paths: [], ... }

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

detectChanges

function detectChanges(before, after)

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

Name	Type	Description
before	any	The value to diff from
after	any	The value to diff to

Returns

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

Notes

Objects and arrays recurse to leaf paths and arrays diff by index, so a shifted array reports every moved position. 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 ''.

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'] }

console.log(detectChanges({ items: [1, 2, 3] }, { items: [1, 9] }));
// { added: [], removed: ['items.2'], changed: ['items.1'] }

extend

function extend(obj, ...sources)

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

Parameters

Name	Type	Description
obj	object	The target object to extend
sources	…object	One or more source objects

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

Name	Type	Description
target	object	The object to update in place
source	object	The object whose properties to apply
options	object	Optional configuration

Options

Name	Type	Default	Description
preserveExistingKeys	boolean	false	Keep keys in target that are not in source
preserveGetters	boolean	false	Skip own getter descriptors when deleting keys not in source. Useful when target carries computed properties that shouldn’t be torn down by syncs
returnChanged	boolean	false	Return whether any properties changed instead of the target

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

Name	Type	Description
obj	object	The target object to extend
sources	…object	One or more source objects to merge from
options	object	Optional configuration object

Options

Name	Type	Default	Description
preserveNonCloneable	boolean	false	Preserve custom class instances instead of flattening them

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

Name	Type	Description
obj	object	The source object
keys	…string	The keys to pick

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

Name	Type	Description
obj	object	The object to convert

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 = '')

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

Parameters

Name	Type	Description
obj	object	The object to access
path	string	The path to the desired property

Returns

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

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

set

function set(obj, path, value)

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

Name	Type	Description
obj	object	The object to write into
path	string	The path string (e.g., ‘a.b.c’, ‘items.0.name’, or ‘items[0].name’)
value	any	The value to set at the path

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.

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)));

unset

function unset(obj, path)

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

Parameters

Name	Type	Description
obj	object	The object to remove from
path	string	The path string (e.g., ‘a.b.c’ or ‘items.0’)

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.

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));

proxyObject

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

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

Parameters

Name	Type	Description
sourceObj	function	A function that returns the source object
referenceObj	object	The reference object

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

Name	Type	Description
obj	object	The source object
keysToKeep	array	The keys to keep in the new object

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

Name	Type	Description
obj	object	The object to check
prop	string	The property name to check for

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

Name	Type	Description
obj	object	The object to reverse

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

Name	Type	Description
query	string	The search query
objectArray	array	Array of objects to search
options	object	Search configuration

Options

Name	Type	Default	Description
returnMatches	boolean	false	Include match details in results
matchAllWords	boolean	true	Require all words to match
propertiesToMatch	array	[]	Properties to search within objects

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' }]

On This Page

Functions

keys

Parameters

Returns

Example

values

Parameters

Returns

Example

filterObject

Parameters

Returns

Example

mapObject

Parameters

Returns

Example

trackWrites

Parameters

Options

Returns

Notes

Example

detectChanges

Parameters

Returns

Notes

Example

extend

Parameters

Returns

Example

assignInPlace

Parameters

Options

Returns

Example

deepExtend

Parameters

Options

Returns

Example

pick

Parameters

Returns

Example

arrayFromObject

Parameters

Returns

Example

get

Parameters

Returns

Example

set

Parameters

Returns

Notes

Example

unset

Parameters

Returns

Notes

Example

proxyObject

Parameters

Returns

Example

onlyKeys

Parameters

Returns

Example

hasProperty

Parameters

Returns

Example

reverseKeys

Parameters

Returns