entries

The entries utility returns an array of an object's own enumerable string-keyed property [key, value] pairs. It is a type-safe wrapper around the native Object.entries(), providing significantly better type inference for the resulting tuples.

Implementation

View Source Code

import { assert } from '../function/assert';
import { IS_OBJECT_ERROR_MSG, isObject } from '../typed/isObject';
import type { Obj } from '../types';

type Entries<T> = { [K in keyof T]: [K, T[K]] }[keyof T][];

/**
 * Returns an array of a given object's own enumerable string-keyed property [key, value] pairs.
 *
 * @example
 * ```ts
 * const obj = { a: 1, b: 2, c: 3 };
 * entries(obj); // logs [['a', 1], ['b', 2], ['c', 3]]
 * ```
 *
 * @param item - The object whose properties are to be returned.
 *
 * @returns an array of the object's own enumerable string-keyed property [key, value] pairs.
 */
export function entries<T extends Obj>(item: T): Entries<T> {
  assert(isObject(item), IS_OBJECT_ERROR_MSG, { args: { item }, type: TypeError });

  return Object.entries(item) as Entries<T>;
}

Features

• Isomorphic: Works in both Browser and Node.js.
• Type-safe: Tuples are correctly typed as [keyof T, T[keyof T]] rather than [string, any].
• Enumerable Only: Consistent with native behavior, only includes own enumerable properties.

API

function entries<T extends object>(obj: T): [keyof T, T[keyof T]][];

Parameters

• obj: The object whose entries should be extracted.

Returns

• An array of [key, value] pairs.

Examples

Basic Usage

import { entries } from '@vielzeug/toolkit';

const settings = {
  theme: 'dark',
  notifications: true,
  retries: 3,
};

const settingPairs = entries(settings);
/*
[
  ['theme', 'dark'],
  ['notifications', true],
  ['retries', 3]
]
*/

Iterating with Better Types

import { entries, map } from '@vielzeug/toolkit';

const counts = { a: 10, b: 20 };

// key and value are properly typed in the callback
const summary = map(entries(counts), ([key, val]) => {
  return `${key.toUpperCase()}: ${val}`;
});
// ['A: 10', 'B: 20']

Implementation Notes

• Internally calls Object.entries(obj).
• Does not include properties from the prototype chain.
• If the argument is not an object, it may throw depending on the environment (similar to native Object.entries).

See Also

• keys: Extract only the keys from an object.
• values: Extract only the values from an object.
• path: Retrieve a value at a specific path.