openinf / openinf-util-object

Common JavaScript object type-related utilities

@openinf/util-object

Common JavaScript object type-related utilities

The high-level goal of @openinf/util-object is to serve as a Node.js package containing utilities for common JavaScript object type-related operations primarily enabling users to perform comparisons and analyze object contents. We are constantly working to improve this repository, so please feel free to contribute if you notice any omissions or errors.

Thanks!

Supported Node.js Environments

• v4：Argon (Ar)
• v6：Boron (B)
• v8：Carbon (C)
• v10：Dubnium (Db)
• v12：Erbium (Er)
• v14：Fermium (Fm)
• v16：Gallium (Ga)
• v18：Hydrogen (H)

---

Table of Contents

• Installation
• Usage
• API
• Contributing
• License

---

Installation

@openinf/util-object runs on supported versions of Node.js and is available via npm, pnpm, or yarn.

Using the npm CLI

^{See the official documentation for this command for more information.}

npm i @openinf/util-object

Using the pnpm CLI

^{See the official documentation for this command for more information.}

pnpm add @openinf/util-object

Using the Yarn 1 CLI (Classic)

^{See the official documentation for this command for more information.}

yarn add @openinf/util-object

Usage

import { hasOwn } from '@openinf/util-object';

export class GhFileImporter {
  constructor(options: GhFileImporterOptions) {
    if (!hasOwn(options, 'destDir')) {
      throw new MissingOptionError('destDir');
    }
  }
}

API

map([opt_initial]) ⇒ T

Returns a map-like object. If opt_initial is provided, copies its own properties into the newly created object.

hasOwn(obj, key) ⇒ boolean

Checks if the given key is a property in the map.

ownProperty(obj, key) ⇒ unknown

Returns obj[key] iff key is obj's own property (is not inherited). Otherwise, returns undefined.

deepMerge(target, source, depth) ⇒ Object

Deep merges source into target.

omit(o, props) ⇒ Record<string, (number|RegExp)>

objectsEqualShallow(o1, o2) ⇒ boolean

memo(obj, prop, factory) ⇒ R

Takes an object, a property name, and a factory function. If the value of the property is undefined, it generates a value with the factory function, updates the object originally passed, and returns the value that was returned by the factory function.

map([opt_initial]) ⇒ T

Returns a map-like object. If opt_initial is provided, copies its own properties into the newly created object.

Kind: global function

Param	Type	Description
[opt_initial]	T	This should typically be an object literal.

hasOwn(obj, key) ⇒ boolean

Checks if the given key is a property in the map.

Kind: global function

Param	Type	Description
obj	T	a map like property.
key	string

ownProperty(obj, key) ⇒ unknown

Returns obj[key] iff key is obj's own property (is not inherited). Otherwise, returns undefined.

Kind: global function

Param	Type
obj	Record<string, (number|RegExp)>
key	string

deepMerge(target, source, depth) ⇒ Object

Deep merges source into target.

Kind: global function
Throws:

• Error If source contains a circular reference. Note: Only nested objects are deep-merged, primitives and arrays are not.

Param	Type	Default	Description
target	Object
source	Object
depth	number	10	The maximum merge depth. If exceeded, Object.assign will be used instead.

deepMerge~queue : Array<ITargetSourceDepth>

Kind: inner constant of deepMerge

omit(o, props) ⇒ Record<string, (number|RegExp)>

Kind: global function
Returns: Record<string, (number|RegExp)> - An object with the given properties removed.

Param	Type	Description
o	Record<string, (number|RegExp)>	An object to remove properties from.
props	Array<string>	A list of properties to remove from the Object.

objectsEqualShallow(o1, o2) ⇒ boolean

Kind: global function

Param	Type
o1	!Record<string, (number|RegExp)> | null | undefined
o2	!Record<string, (number|RegExp)> | null | undefined

memo(obj, prop, factory) ⇒ R

Takes an object, a property name, and a factory function. If the value of the property is undefined, it generates a value with the factory function, updates the object originally passed, and returns the value that was returned by the factory function.

Kind: global function

Param	Type
obj	T
prop	string
factory	function

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.

License

This project is licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.

---

Show Your Support

If you like the project (or want to bookmark it) —
— give it a star ⭐️ — it will greatly encourage us.

openinf-util-object's Issues

doc: flaky badge on README

The "TypeScript Types: Included" badge on the README seems to be timing out. I have seen this multiple times for this particular badge and should be corrected. See the screenshot below.

[feature request] prevent including unnecessary files in the deployed package

We should consider adding the "files" stanza to the package.json to create an explicit allowlist and prevent deploying any unnecessary files to the npm registry as part of our package. This would be preferable to using a .npmignore file, which we have been doing so far but is expected to quickly become unmanageable as more files are added.

(JS-0296) Use of a banned type detected

Description

Some builtin types have aliases, some types are considered dangerous or harmful. It's often a good idea to ban certain types to help with consistency and safety.

Occurrences

There are 6 occurrences of this issue in the repository.

See all occurrences on DeepSource → deepsource.io/gh/openinf/util-object/issue/JS-0296/occurrences/

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

• build(deps-dev): bump chai to v4.4.1
• build(deps-dev): bump eslint to v8.57.0
• build(deps-dev): bump eslint-config-prettier to v8.10.0
• build(deps-dev): bump eslint-plugin-import to v2.29.1
• build(deps-dev): bump eslint-plugin-promise to v6.4.0
• chore(deps): bump ruby to v3.3.3
• build(deps-dev): bump chai to v5
• build(deps-dev): bump eslint to v9
• build(deps-dev): bump eslint-config-prettier to v9
• build(deps-dev): bump eslint-plugin-regexp to v2
• build(deps-dev): bump eslint-plugin-simple-import-sort to v12
• chore(deps): bump actions/checkout action to v4
• chore(deps): bump actions/setup-node action to v4
• chore(deps): bump dependabot/fetch-metadata action to v2
• chore(deps): bump github/codeql-action action to v3
• chore(deps): bump pnpm to v9
• chore(deps): bump ubuntu to v22
• 🔐 Create all rate-limited PRs at once 🔐

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• build(deps-dev): bump eslint-import-resolver-node to v0.3.9
• chore(deps): bump actions/setup-node action to v3.8.2
• build(deps-dev): bump jasmine to v5.1.0
• build(deps-dev): bump typescript to v5.5.3
• build(deps-dev): bump typescript-eslint monorepo to v5.62.0 (@typescript-eslint/eslint-plugin, @typescript-eslint/parser)
• chore(deps): bump pnpm to v8.15.8
• chore(deps): bump ruby/setup-ruby action to v1.184.0
• build(deps-dev): bump eslint-plugin-prettier to v5
• build(deps-dev): bump prettier to v3
• build(deps-dev): bump typescript-eslint monorepo to v7 (major) (@typescript-eslint/eslint-plugin, @typescript-eslint/parser)
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

devcontainer

.devcontainer.json

github-actions

.github/workflows/codeql.yml

• actions/checkout v3
• actions/setup-node v3.8.0
• ruby/setup-ruby v1.151.0
• github/codeql-action v2
• github/codeql-action v2

.github/workflows/dependabot-auto-rename.yml

• dependabot/fetch-metadata v1

.github/workflows/semgrep.yml

• actions/checkout v3
• ubuntu 20.04

npm

package.json

• @types/node 20.x.x
• @typescript-eslint/eslint-plugin 5.59.9
• @typescript-eslint/parser 5.59.9
• chai 4.3.7
• eslint 8.42.0
• eslint-config-prettier 8.8.0
• eslint-import-resolver-node 0.3.7
• eslint-plugin-etc 2.0.3
• eslint-plugin-import 2.27.5
• eslint-plugin-prettier 4.2.1
• eslint-plugin-promise 6.1.1
• eslint-plugin-regexp 1.15.0
• eslint-plugin-simple-import-sort 10.0.0
• jasmine 5.0.1
• prettier 2.8.8
• typescript 5.1.3
• pnpm 8.6.3

nvm

.nvmrc

ruby-version

.ruby-version

• ruby 3.2.2

---

• Check this box to trigger a request for Renovate to run again on this repository

[feature request] lint rules: add `@typescript-eslint/eslint-plugin-tslint`

    This dependency should be removed; we want to have errors and warnings to differentiate severity/provide guidance on what to do.

Originally posted by @DerekNonGeneric in #189 (review)

build: remove build products from repo & migrate to babel for transpilation

It is preferable not to check the compiled typescript into our repo — let's remove that javascript from here. Additionally, we should use babel for this transpilation instead of the typescript compiler. We will, however, continue using tsc for type checking and type definition generation.

[feature request] fully implement Ergonomic Dynamic Object Restructuring

As we are already shipping the relevant omit(o, props) function, from the Object.pick, Object.omit TC39 proposal (currently stage 1), we should also be including its inverted counterpart (the pick function from Object.pick) to be correctly balanced and correct.

We may also need to update the signature of the omit(o, props) function we are currently shipping if there is divergence.

[bug] `package.json` specifies wrong URL for some of its fields

The package.json currently specifies the wrong URL for the following fields:

• bugs
• homepage
• repository

This was a rushed package and it shows — plenty of subtle defects like this. Readers/users: please be sure to use this issue tracker until we get this sorted with the next release.

[bug] Object is possibly 'undefined'

These issues were raised via CI run: https://github.com/openinf/util-object/actions/runs/3258038095/jobs/5349784833/

src/index.ts:138:19 - error TS2532: Object is possibly 'undefined'.

138     if (o1[k] !== o2[k]) {
                      ~~

src/index.ts:143:19 - error TS2532: Object is possibly 'undefined'.

143     if (o2[k] !== o1[k]) {
                      ~~


Found 2 errors in the same file, starting at: src/index.ts:138

This may be the (most likely) reason: a013a28#commitcomment-86935693.

Hacktoberfest checklist: prepare project for contributions by following best practices

• Add the “hacktoberfest” topic to your repository to opt-in to Hacktoberfest and indicate you’re looking for contributions.

• Apply the “hacktoberfest” label to issues you want contributors to help within your GitHub or GitLab project.

• Add a CONTRIBUTING.md file with contribution guidelines to your repository.

• Choose issues that have a well-defined scope and are self-contained.

• Adopt a code of conduct to create a greater sense of inclusion and community for contributors.

• Be ready to review pull/merge requests, accepting those that are valid by merging them, leaving an overall approving review, or by adding the “hacktoberfest-accepted” label.

• Reject any spammy requests you receive by labeling them as “spam”, and any other invalid contributions by closing them or labeling them as “invalid”.

Refs: https://hacktoberfest.com/participation/#maintainers

[feature request] migrate towards 🦄 `prevent-abbreviations` rule

[feature request] add new `isPlainObject` predicate function

The isPlainObject predicate function is another common convenience function in the JS Object domain.

• It is quite frequently used and would be very helpful to have.
• It is distinct from the very similar isObject predicate function from @openinf/util-types
• It is distinct from the isObjectLike predicate function, which is often kept private/internal

---

const isPlainObject = ( obj ) => {
	return (
		typeof obj === 'object' &&
		obj !== null &&
		obj.constructor === Object &&
		Object.prototype.toString.call( obj ) === '[object Object]'
	);
};

---

Aside

hopefully not a misnomer due to the existence of plain old Java objects (POJOs), which are also a thing in JS

Open question

would a more rigorous check be necessary to differentiate btwx the two or is it fine?

[feature request] add new `isBaseObject` predicate function

This predicate function seems like it would be useful.

private static boolean isBaseObject(Scriptable s) {
  // A direct instance of Object is the only Object whose prototype's
  // prototype is null.
  Scriptable proto = s.getPrototype();
  return proto != null && proto.getPrototype() == null;
}

Refs: http://cajadores.com/docs/java/com/google/caja/util/RhinoAsserts.html#isBaseObject(org.mozilla.javascript.Scriptable)

[security] Generic Object Injection Sink

Codacy detected an issue:

Message: Generic Object Injection Sink

Currently on:

• Commit: b978219
• File: src/index.ts
• LineNum: 135

[feature request] CodeQL actions workflow

This reflects terribly on project health.

We currently have a wall of blocked deps update PRs and it looks like a massive trainwreck.