foreach-prop

Array-like methods for objects

⚠️ Some javascript implementations don't follow the user object value-key order. Keep that in mind when you use keyOf, lastKeyOf, findKey, findLastKey and find functions.

Content

• Install
• CDN
• Usage
• API
  • function create
  • function fill
  • function includes
  • function some
  • function every
  • function forEach
  • function map
  • function filter
  • function keyOf
  • function lastKeyOf
  • function findKey
  • function findLastKey
  • function find
  • function reduce

Install

npm i foreach-prop

CDN

jsDelivr

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

for production

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

more options...

unpkg

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

for production

<script src="https://unpkg.com/foreach-prop@latest/dist/umd/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

function 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.

function create(
  keys: K[],
  value?: V
): Record<K, V>;

example

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

{ a: true, b: true }

function 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.

function fill(
  object: Record<K, V> | V[],
  value: N
): Record<K, N>;

function includes

added in: v0.2.0

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

function includes(
  object: Record<string, V> | V[],
  value: unknown
): boolean;

function 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.

function some(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): boolean;

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.

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

function every

added in: v0.2.0

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

function every(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): boolean;

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.

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

function 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.

function forEach(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => void,
  ...extra: X[]
): 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);

function 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 with the callback return as value.

function map(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => N,
  ...extra: X[]
): Record<K, N>;

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.

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

function 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.

function filter(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): Partial<Record<K, V>>;

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.

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

function keyOf

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

function keyOf(
  object: Record<K, unknown>,
  value: unknown
): K | null;

function lastKeyOf

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

function lastKeyOf(
  object: Record<K, unknown>,
  value: unknown
): K | null;

function 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.

function findKey(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): K | null;

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.

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

function findLastKey

added in: v3.0.0

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

function findLastKey(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): K | null;

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.

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

function 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.

function find(
  object: Record<K, V> | V[],
  callback: (value: V, key: K, ...extra: X[]) => unknown,
  ...extra: X[]
): V | undefined;

Note that the returned value may be undefined even if the condition is met but 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.

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.

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

function reduce

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

function reduce(
  object: Record<K, V> | V[],
  callback: (current: R, value: V, key: K, ...extra: X[]) => R,
  initial?: R,
  ...extra: X[]
): R;

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.

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

License

MIT © 2019 Manuel Fernández