feat: _firstKey, _firstValue and related optimized functions

Author: kirillgroshkov

packages/js-lib/src/array/array.util.test.ts

@@ -17,6 +17,7 @@ import {
   _find,
   _findLast,
   _first,
+  _firstFromIterable,
   _firstLast,
   _firstLastOrUndefined,
   _firstOrUndefined,
@@ -460,6 +461,33 @@ test('_first', () => {
   expect(_first([1])).toBe(1)
 })
 
+test('_firstFromIterable', () => {
+  expect(_firstFromIterable([])).toBeUndefined()
+  expect(_firstFromIterable([1, 2, 3])).toBe(1)
+  expect(_firstFromIterable(new Set([1, 2, 3]))).toBe(1)
+  expect(_firstFromIterable(new Set<number>())).toBeUndefined()
+  expect(_firstFromIterable(new Map([['a', 1]]).values())).toBe(1)
+  expect(
+    _firstFromIterable(
+      new Map([
+        ['a', 1],
+        ['b', 2],
+      ]).keys(),
+    ),
+  ).toBe('a')
+
+  function* gen(): Generator<string> {
+    yield 'x'
+    yield 'y'
+  }
+
+  expect(_firstFromIterable(gen())).toBe('x')
+
+  function* emptyGen(): Generator<string> {}
+
+  expect(_firstFromIterable(emptyGen())).toBeUndefined()
+})
+
 test('_min', () => {
   expect(_minOrUndefined([])).toBeUndefined()
   expect(_minOrUndefined([3])).toBe(3)

packages/js-lib/src/array/array.util.ts

@@ -468,6 +468,19 @@ export function _firstOrUndefined<T>(array: readonly T[]): T | undefined {
   return array[0]
 }
 
+/**
+ * Returns the first item of an iterable (Set, Map.values(), generator, etc.),
+ * or `undefined` if the iterable is empty.
+ *
+ * Avoids the `Array.from(iter)[0]` pattern that materialises the entire iterable.
+ * `for...of` with an early return advances the iterator exactly once; if the
+ * iterator implements `return()` (generators, etc.), it is invoked for cleanup.
+ */
+export function _firstFromIterable<T>(iter: Iterable<T>): T | undefined {
+  for (const item of iter) return item
+  return undefined
+}
+
 export function _minOrUndefined<T>(array: readonly T[]): NonNullable<T> | undefined {
   let min: NonNullable<T> | undefined
   for (const item of array) {

packages/js-lib/src/is.util.ts

@@ -45,11 +45,19 @@ export function _isPrimitive(v: any): v is Primitive {
 }
 
 export function _isEmptyObject(obj: AnyObject): boolean {
-  return Object.keys(obj).length === 0
+  // for...in with early return avoids allocating the full Object.keys array.
+  // Object.hasOwn matches Object.keys() semantics (own enumerable keys only).
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return false
+  }
+  return true
 }
 
 export function _isNotEmptyObject(obj: AnyObject): boolean {
-  return Object.keys(obj).length > 0
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return true
+  }
+  return false
 }
 
 /**
@@ -74,7 +82,10 @@ export function _isEmpty(obj: any): boolean {
   }
 
   if (typeof obj === 'object') {
-    return Object.keys(obj).length === 0
+    for (const k in obj) {
+      if (Object.hasOwn(obj, k)) return false
+    }
+    return true
   }
 
   return false

packages/js-lib/src/object/object.util.test.ts

@@ -11,6 +11,9 @@ import {
   _filterObject,
   _filterUndefinedValues,
   _findKeyByValue,
+  _firstEntry,
+  _firstKey,
+  _firstValue,
   _get,
   _has,
   _hasProp,
@@ -683,6 +686,29 @@ test('_findKeyByValue', () => {
   expect(char).toBe(CHAR.B)
 })
 
+test('_firstKey', () => {
+  expect(_firstKey({ a: 1, b: 2 })).toBe('a')
+  expect(_firstKey({ x: 1 })).toBe('x')
+  expect(_firstKey({})).toBeUndefined()
+  // V8 sorts integer-like keys ascending first, then string keys in insertion order
+  expect(_firstKey({ 2: 'b', 1: 'a' })).toBe('1')
+  expect(_firstKey({ b: 1, 1: 'a' })).toBe('1')
+})
+
+test('_firstValue', () => {
+  expect(_firstValue({ a: 1, b: 2 })).toBe(1)
+  expect(_firstValue({ x: 'only' })).toBe('only')
+  expect(_firstValue({})).toBeUndefined()
+  expect(_firstValue({ 2: 'b', 1: 'a' })).toBe('a')
+})
+
+test('_firstEntry', () => {
+  expect(_firstEntry({ a: 1, b: 2 })).toEqual(['a', 1])
+  expect(_firstEntry({ x: 'only' })).toEqual(['x', 'only'])
+  expect(_firstEntry({})).toBeUndefined()
+  expect(_firstEntry({ 2: 'b', 1: 'a' })).toEqual(['1', 'a'])
+})
+
 test('_deepFreeze', () => {
   const o = {
     a: {

packages/js-lib/src/object/object.util.ts

@@ -242,6 +242,47 @@ export function _findKeyByValue<T extends AnyObject>(obj: T, v: ValueOf<T>): key
   return Object.entries(obj).find(([_, value]) => value === v)?.[0] as keyof T
 }
 
+/**
+ * Returns the first key of the object, or `undefined` if the object is empty.
+ *
+ * Performance-optimised: uses `for...in` with an early return to avoid
+ * allocating the full `Object.keys(obj)` array. The `Object.hasOwn` filter
+ * matches `Object.keys()` semantics (own enumerable string keys only) and
+ * satisfies the `guard-for-in` lint rule; cost is a single check before
+ * the early return. Iteration order matches `Object.keys()` for plain
+ * objects (integer-like keys ascending first, then string keys in
+ * insertion order).
+ */
+export function _firstKey<T extends AnyObject>(obj: T): keyof T | undefined {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return k as keyof T
+  }
+  return undefined
+}
+
+/**
+ * Returns the first value of the object, or `undefined` if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstValue<T extends AnyObject>(obj: T): ValueOf<T> | undefined {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return obj[k] as ValueOf<T>
+  }
+  return undefined
+}
+
+/**
+ * Returns the first [key, value] tuple of the object,
+ * or `undefined` if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstEntry<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>] | undefined {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return [k as keyof T, obj[k] as ValueOf<T>]
+  }
+  return undefined
+}
+
 export function _objectNullValuesToUndefined<T extends AnyObject>(
   obj: T,
   opt: MutateOptions = {},