Foreach-prop NPM

foreach-prop

Array-like methods for objects

:warning: Some javascript implementations don't follow the object key order. Keep that in mind when you use keyOf, lastKeyOf, findKey and find methods.

Content

Install

npm i foreach-prop

CDN

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/foreach-prop@latest/dist/each-prop.umd.js"></script>

for production

<script src="https://cdn.jsdelivr.net/npm/foreach-prop@latest/dist/each-prop.umd.min.js"></script>

more options...

unpkg

<script src="https://unpkg.com/foreach-prop@latest/dist/each-prop.umd.js"></script>

for production

<script src="https://unpkg.com/foreach-prop@latest/dist/each-prop.umd.min.js"></script>

more options...

Usage

example

import { map } from "foreach-prop";

const object = {
  key1: "str",
  key2: 1,
};

const result = map(object, (value, key, extra1) => {
  return key + extra1;
}, " $$");

console.log(result);

{
  key1: "key1 $$",
  key2: "key2 $$",
}

See the API section for more details.

Node.js

const { forEach } = require("foreach-prop");
forEach(object, callback);

Browser

After adding the script tag, eachProp object will be available globally, containing all methods detailed in the API section.

eachProp.forEach(object, callback);

API

forEach

Similar to Array.prototype.forEach. It calls the provided callback function for every key-value-pair in the object. Once initiated there is no way to stop the execution of this function, if you intend to stop the iteration at some point have a look at findKey method.

forEach(object, function callback(value, key, ...extra) => void, ...extra): void;

Any extra argument will be passed down to the callback function.

The callback function inherits the this value from the function call, so if you want a specific this value in your callback function, you can call it using the call method of the Function.prototype.

forEach.call(thisArg, object, callback, ...extra);

map

Similar to Array.prototype.map. It calls the provided callback function for every key-value-pair in the object and returns a new object.

map(object, function callback(value, key, ...extra) => any, ...extra): object;

Any extra argument will be passed down to the callback function.

map.call(thisArg, object, callback, ...extra);

keyOf

Similar to Array.prototype.indexOf. It returns the key of the first value that equals the provided one, or null if not found.

keyOf(object, value): string | null;

lastKeyOf

Similar to Array.prototype.lastIndexOf. It returns the key of the last value that equals the provided one, or null if not found.

lastKeyOf(object, value): string | null;

includes

added in: v0.2.0

Similar to Array.prototype.includes. It returns whether or not a value is present in an object.

includes(object, value): boolean;

findKey

Similar to Array.prototype.findIndex. It calls the provided callback function for every key-value-pair in the object and returns the key once the provided callback function return a truthy value. It returns null if nothing found.

findKey(object, function callback(value, key, ...extra) => any, ...extra): string | null;

Any extra argument will be passed down to the callback function.

findKey.call(thisArg, object, callback, ...extra);

find

added in: v0.1.0

Similar to Array.prototype.find. It calls the provided callback function for every key-value-pair in the object and returns the value once the provided callback function return a truthy value. It returns undefined if nothing found.

find(object, function callback(value, key, ...extra) => any, ...extra): any;

Note that the returned value may be undefined even if the condition is met and the value is undefined.

example

const undef;
// undef is undefined
const object = { key1: undef };
// object.key1 is also undefined

const value = find(object, (val, key) => {
  return key === "key1"
});

console.log(value);
// it logs undefined
// because undef is undefined

undefined

Any extra argument will be passed down to the callback function.

find.call(thisArg, object, callback, ...extra);

filter

Similar to Array.prototype.filter. It calls the provided callback function for every key-value-pair in the object and returns a new object containing the key-value-pairs corresponding to those where the provided callback function returned a truthy value.

filter(object, function callback(value, key, ...extra) => any, ...extra): object;

Any extra argument will be passed down to the callback function.

filter.call(thisArg, object, callback, ...extra);

reduce

Similar to Array.prototype.reduce but with a major difference: if no initial value provided it defaults to undefined.

reduce(object, function callback(current, value, key, ...extra) => any, initial?, ...extra): any;

Any extra argument will be passed down to the callback function.

reduce.call(thisArg, object, callback, initial?, ...extra);

some

added in: v0.2.0

Similar to Array.prototype.some. It returns whether at least one of the key-value-pairs satisfy the provided callback function.

some(object, function callback(value, key, ...extra) => any, ...extra): boolean;

Any extra argument will be passed down to the callback function.

some.call(thisArg, object, callback, ...extra): boolean;

every

added in: v0.2.0

Similar to Array.prototype.every. It returns whether all key-value-pairs satisfy the provided callback function.

every(object, function callback(value, key, ...extra) => any, ...extra): boolean;

Any extra argument will be passed down to the callback function.

every.call(thisArg, object, callback, ...extra): boolean;

create

added in: v2.1.0

Similar to new Array(). It creates a new object with the given keys. If a value is provided, every property will be populated with the given value or undefined otherwise.

create(keys: Array<string | number>, value?: any): object;

example

const object = create(['a', 'b'], true);
console.log(object);

{ a: true, b: true }

fill

added in: v2.1.0

Similar to Array.prototype.fill with a difference, it returns a new object instead of modifying the given one. Every property in the new object will be set to the provided value.