object

Functional utilities for objects.

Documentation

Features

• Opt-in mutability with remmi
• Reference preservation (merge(obj, { foo: true }) === obj)
• Pipe-friendly (pipe(merge({ foo: true })(obj))
• Graceful failure handling (get(), getOr(), getOrElse(), getOrThrow())

Installation

npm install @monstermann/object

pnpm add @monstermann/object

yarn add @monstermann/object

bun add @monstermann/object

Tree-shaking

Installation

npm install -D @monstermann/unplugin-object

pnpm -D add @monstermann/unplugin-object

yarn -D add @monstermann/unplugin-object

bun -D add @monstermann/unplugin-object

Usage

// vite.config.tsimportobjectfrom"@monstermann/unplugin-object/vite";exportdefaultdefineConfig({plugins: [object()],});

// rollup.config.jsimportobjectfrom"@monstermann/unplugin-object/rollup";exportdefault{plugins: [object()],};

// rolldown.config.jsimportobjectfrom"@monstermann/unplugin-object/rolldown";exportdefault{plugins: [object()],};

// webpack.config.jsconstobject=require("@monstermann/unplugin-object/webpack");module.exports={plugins: [object()],};

// rspack.config.jsconstobject=require("@monstermann/unplugin-object/rspack");module.exports={plugins: [object()],};

// esbuild.config.jsimport{build}from"esbuild";importobjectfrom"@monstermann/unplugin-object/esbuild";build({plugins: [object()],});

Object

assign

functionObject.assign<Textendsobject,Uextendsobject>(target: T,source: U,): Textendsunknown ? Merge<T,U> : never

Merges properties from source object into target object, creating a new object.

Looser version of merge - assign allows you to redefine keys and add new properties.

Example

import{Object}from"@monstermann/object";Object.assign({a: 1,b: 2},{b: 3,c: 4});// { a: 1, b: 3, c: 4 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.assign({b: 3,c: 4}));// { a: 1, b: 3, c: 4 }

clone

functionObject.clone<Textendsobject>(target: T): T

Creates a shallow copy of an object, unless marked as mutable with markAsMutable inside a mutation context (see @monstermann/remmi).

Example

import{Object}from"@monstermann/object";constoriginal={a: 1,b: 2};constcopy=Object.clone(original);// { a: 1, b: 2 }

import{Object}from"@monstermann/object";constoriginal={a: 1,b: 2};constcopy=pipe(original,Object.clone());// { a: 1, b: 2 }

entries

functionObject.entries<Textendsobject>(target: T): Entries<T>

Returns an array of key-value pairs from target object.

Example

import{Object}from"@monstermann/object";Object.entries({a: 1,b: 2,c: 3});// [["a", 1], ["b", 2], ["c", 3]]

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.entries());// [["a", 1], ["b", 2], ["c", 3]]

evolve

functionObject.evolve<Textendsobject,UextendsEvolver<T>>(target: T,evolver: U,): T

Creates a new object with multiple properties transformed by their corresponding functions in the evolver object.

Example

import{Object}from"@monstermann/object";Object.evolve({a: 1,b: 2,c: 3},{a: (x)=>x*2,c: (x)=>x+1,},);// { a: 2, b: 2, c: 4 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.evolve({a: (x)=>x*2,c: (x)=>x+1,}),);// { a: 2, b: 2, c: 4 }

forEach

functionObject.forEach<Textendsobject>(target: T,fn: ForEachCallback<T>,): T

Executes fn function for each key-value pair in target object and returns the original object.

Example

import{Object}from"@monstermann/object";Object.forEach({a: 1,b: 2},([key,value])=>console.log(key,value));// { a: 1, b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.forEach(([key,value])=>console.log(key,value)),);// { a: 1, b: 2 }

fromEntries

functionObject.fromEntries(): <constEntriesextendsIterableContainer<Entry>,>(entries: Entries,)=>Simplify<FromEntries<Entries>>

Creates an object from an array of key-value pairs (entries). Each entry should be a tuple of [key, value].

Example

import{Object}from"@monstermann/object";Object.fromEntries([["a",1],["b",2],["c",3],]);// { a: 1, b: 2, c: 3 }

import{Object}from"@monstermann/object";pipe([["a",1],["b",2],["c",3],],Object.fromEntries(),);// { a: 1, b: 2, c: 3 }

get

functionObject.get<Textendsobject,UextendskeyofAllUnionFields<T>,>(target: T,key: U): AllUnionFields<T>[U]

Returns the value of key property from target object, or undefined if not found.

Example

import{Object}from"@monstermann/object";Object.get({a: 1,b: 2},"a");// 1Object.get({a: 1,b: 2},"c");// undefined

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.get("a"));// 1pipe({a: 1,b: 2},Object.get("c"));// undefined

getOr

functionObject.getOr<Textendsobject,UextendskeyofAllUnionFields<T>,V,>(target: T,key: U,or: V,): Exclude<AllUnionFields<T>[U]|V,null|undefined>

Returns the value of key property from target object, or the or value if not found or nullish.

Example

import{Object}from"@monstermann/object";Object.getOr({a: 1,b: 2},"a",0);// 1Object.getOr({a: 1,b: 2},"c",0);// 0

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.getOr("a",0));// 1pipe({a: 1,b: 2},Object.getOr("c",0));// 0

getOrElse

functionObject.getOrElse<Textendsobject,UextendskeyofAllUnionFields<T>,V,>(target: T,key: U,orElse: (target: NoInfer<T>)=>V,): Exclude<AllUnionFields<T>[U]|V,null|undefined>

Returns the value of key property from target object, or the result of calling orElse function with target if not found or nullish.

Example

import{Object}from"@monstermann/object";Object.getOrElse({a: 1,b: 2},"a",()=>0);// 1Object.getOrElse({a: 1,b: 2},"c",(obj)=>Object.keys(obj).length);// 2

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.getOrElse("a",()=>0),);// 1pipe({a: 1,b: 2},Object.getOrElse("c",(obj)=>Object.keys(obj).length),);// 2

getOrThrow

functionObject.getOrThrow<Textendsobject,UextendskeyofAllUnionFields<T>,>(target: T,key: U,): Exclude<AllUnionFields<T>[U],null|undefined>

Returns the value of key property from target object, or throws an error if not found or null/undefined.

Example

import{Object}from"@monstermann/object";Object.getOrThrow({a: 1,b: 2},"a");// 1Object.getOrThrow({a: 1,b: 2},"c");// throws FnError

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.getOrThrow("a"));// 1pipe({a: 1,b: 2},Object.getOrThrow("c"));// throws FnError

hasKey

functionObject.hasKey<Textendsobject,UextendsKeysOfUnion<T>>(target: T,key: U,): target is HasKey<T,U>

Checks if target object has the specified key property.

Example

import{Object}from"@monstermann/object";Object.hasKey({a: 1,b: 2},"a");// trueObject.hasKey({a: 1,b: 2},"c");// false

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.hasKey("a"));// truepipe({a: 1,b: 2},Object.hasKey("c"));// false

hasProp

functionObject.hasProp<Textendsobject,UextendsKeysOfUnion<T>,>(target: T,key: U): target is HasProp<T,U>

Checks if target object has the specified key property with a non-null and non-undefined value.

Example

import{Object}from"@monstermann/object";Object.hasProp({a: 1,b: null},"a");// trueObject.hasProp({a: 1,b: null},"b");// false

import{Object}from"@monstermann/object";pipe({a: 1,b: null},Object.hasProp("a"));// truepipe({a: 1,b: null},Object.hasProp("b"));// false

is

functionObject.is(target: unknown,): target is Record<PropertyKey,unknown>

Checks if target is a plain object.

Example

import{Object}from"@monstermann/object";Object.is({a: 1});// trueObject.is([]);// falseObject.is(null);// falseObject.is("hello");// false

import{Object}from"@monstermann/object";pipe({a: 1},Object.is());// truepipe([],Object.is());// falsepipe(null,Object.is());// falsepipe("hello",Object.is());// false

isEmpty

functionObject.isEmpty<Textendsobject>(target: T): boolean

Checks if target object has no enumerable properties.

Example

import{Object}from"@monstermann/object";Object.isEmpty({});// trueObject.isEmpty({a: 1});// false

import{Object}from"@monstermann/object";pipe({},Object.isEmpty());// truepipe({a: 1},Object.isEmpty());// false

isShallowEqual

functionObject.isShallowEqual<Textendsobject,UextendsT>(target: T,source: U,): target is U

Performs a shallow equality comparison between target and source objects.

Example

import{Object}from"@monstermann/object";Object.isShallowEqual({a: 1,b: 2},{a: 1,b: 2});// trueObject.isShallowEqual({a: 1,b: 2},{a: 1,b: 3});// false

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.isShallowEqual({a: 1,b: 2}));// truepipe({a: 1,b: 2},Object.isShallowEqual({a: 1,b: 3}));// false

keys

functionObject.keys<Textendsobject>(target: T): KeysOfUnion<T>[]

Returns an array of target object's enumerable property names.

Example

import{Object}from"@monstermann/object";Object.keys({a: 1,b: 2,c: 3});// ["a", "b", "c"]

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.keys());// ["a", "b", "c"]

map

functionObject.map<Textendsobject,UextendskeyofT>(target: T,key: U,transform: (value: NoInfer<T>[U])=>T[U],): T

functionObject.map<Textendsobject,UextendskeyofT>(target: T,key: U,transform: (value: NoInfer<T>[U])=>T[U],): T

Creates a new object with the key property transformed by the transform function.

Example

import{Object}from"@monstermann/object";Object.map({a: 1,b: 2},"a",(x)=>x*2);// { a: 2, b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.map("a",(x)=>x*2),);// { a: 2, b: 2 }

mapAssign

functionObject.mapAssign<Textendsobject,Uextendsobject>(target: T,map: (target: NoInfer<T>)=>U,): Textendsunknown ? Merge<T,U> : never

Merges target object with the result of calling map function on target, creating a new object.

Looser version of mapMerge - mapAssign allows you to redefine keys and add new properties.

Example

import{Object}from"@monstermann/object";Object.mapAssign({a: 1,b: 2},(obj)=>({c: obj.a+obj.b}));// { a: 1, b: 2, c: 3 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.mapAssign((obj)=>({c: obj.a+obj.b})),);// { a: 1, b: 2, c: 3 }

mapMerge

functionObject.mapMerge<Textendsobject>(target: T,map: (target: NoInfer<T>)=>Partial<NoInfer<T>>,): T

Merges target object with the result of calling map function on target, creating a new object with existing keys updated.

Example

import{Object}from"@monstermann/object";Object.mapMerge({a: 1,b: 2},(obj)=>({a: obj.a*2}));// { a: 2, b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.mapMerge((obj)=>({a: obj.a*2})),);// { a: 2, b: 2 }

matches

functionObject.matches<Textendsobject,UextendsT>(target: T,props: Partial<U>,): target is Matches<T,U>

Checks if all properties in props object have equal values in target object.

Example

import{Object}from"@monstermann/object";Object.matches({a: 1,b: 2,c: 3},{a: 1,b: 2});// trueObject.matches({a: 1,b: 2,c: 3},{a: 1,b: 3});// false

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.matches({a: 1,b: 2}));// truepipe({a: 1,b: 2,c: 3},Object.matches({a: 1,b: 3}));// false

merge

functionObject.merge<Textendsobject>(target: T,source: Partial<NoInfer<T>>,): T

Merges properties from source object into target object.

Example

import{Object}from"@monstermann/object";Object.merge({a: 1,b: 2},{a: 3,c: 4});// { a: 3, b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.merge({a: 3,c: 4}));// { a: 3, b: 2 }

omit

functionObject.omit<Textendsobject,KextendsKeysOfUnion<T>>(target: T,keys: Iterable<K>,): DistributedOmit<T,K>

Creates a new object excluding the properties specified in the keys iterable.

Example

import{Object}from"@monstermann/object";Object.omit({a: 1,b: 2,c: 3},["a","c"]);// { b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.omit(["a","c"]));// { b: 2 }

pick

functionObject.pick<Textendsobject,KextendsKeysOfUnion<T>>(target: T,keys: Iterable<K>,): DistributedPick<T,K>

Creates a new object containing only the properties specified in the keys iterable.

Example

import{Object}from"@monstermann/object";Object.pick({a: 1,b: 2,c: 3},["a","c"]);// { a: 1, c: 3 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.pick(["a","c"]));// { a: 1, c: 3 }

propIs

functionObject.propIs<Textendsobject,UextendskeyofAllUnionFields<T>,constVextendsAllUnionFields<T>[U],>(target: T,key: U,value: V): target is PropIs<T,U,V>

Checks if the key property of target object is equal to the specified value using strict equality.

Example

import{Object}from"@monstermann/object";Object.propIs({a: 1,b: 2},"a",1);// trueObject.propIs({a: 1,b: 2},"a",2);// false

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.propIs("a",1));// truepipe({a: 1,b: 2},Object.propIs("a",2));// false

set

functionObject.set<Textendsobject,KextendskeyofT>(target: T,key: K,value: T[K],): T

Creates a new object with the key property set to value.

Example

import{Object}from"@monstermann/object";Object.set({a: 1,b: 2},"a",3);// { a: 3, b: 2 }

import{Object}from"@monstermann/object";pipe({a: 1,b: 2},Object.set("a",3));// { a: 3, b: 2 }

test

functionObject.test<Textendsobject,UextendskeyofAllUnionFields<T>,>(target: T,key: U,predicate: (value: AllUnionFields<T>[U])=>boolean,): target is Test<T,U,AllUnionFields<T>[U]>

Checks if the key property of target object passes the predicate function test.

Example

import{Object}from"@monstermann/object";Object.test({a: 5,b: 2},"a",(x)=>x>3);// trueObject.test({a: 1,b: 2},"a",(x)=>x>3);// false

import{Object}from"@monstermann/object";pipe({a: 5,b: 2},Object.test("a",(x)=>x>3),);// truepipe({a: 1,b: 2},Object.test("a",(x)=>x>3),);// false

testAll

functionObject.testAll<Textendsobject,UextendsTestAllPredicates<T>,>(target: T,props: U): target is TestAllResult<T,U>

Checks if all properties in target object pass their corresponding predicate functions in props object.

Example

import{Object}from"@monstermann/object";Object.testAll({a: 5,b: 2},{a: (x)=>x>3,b: (x)=>x>0});// trueObject.testAll({a: 1,b: 2},{a: (x)=>x>3,b: (x)=>x>0});// false

import{Object}from"@monstermann/object";pipe({a: 5,b: 2},Object.testAll({a: (x)=>x>3,b: (x)=>x>0}));// truepipe({a: 1,b: 2},Object.testAll({a: (x)=>x>3,b: (x)=>x>0}));// false

values

functionObject.values<Textendsobject>(target: T,): AllUnionFields<T>extends infer U ? U[keyofU][] : never

Returns an array of target object's enumerable property values.

Example

import{Object}from"@monstermann/object";Object.values({a: 1,b: 2,c: 3});// [1, 2, 3]

import{Object}from"@monstermann/object";pipe({a: 1,b: 2,c: 3},Object.values());// [1, 2, 3]