@naturalcycles/js-lib 15.75.0 → 15.76.1

package/dist/array/array.util.d.ts

@@ -217,6 +217,20 @@ export declare function _first<T>(array: readonly T[]): T;
  * Returns first item of the array (or undefined if array is empty).
  */
 export declare function _firstOrUndefined<T>(array: readonly T[]): T | undefined;
+/**
+ * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
+ * Throws 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 declare function _firstFromIterable<T>(iter: Iterable<T>): T;
+/**
+ * Returns the first item of an iterable (or undefined if the iterable is empty).
+ * See `_firstFromIterable` for the iteration semantics.
+ */
+export declare function _firstOrUndefinedFromIterable<T>(iter: Iterable<T>): T | undefined;
 export declare function _minOrUndefined<T>(array: readonly T[]): NonNullable<T> | undefined;
 /**
  * Filters out nullish values (undefined and null).

package/dist/array/array.util.js

@@ -403,6 +403,28 @@ export function _first(array) {
 export function _firstOrUndefined(array) {
     return array[0];
 }
+/**
+ * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
+ * Throws 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(iter) {
+    for (const item of iter)
+        return item;
+    throw new Error('_firstFromIterable called on empty iterable');
+}
+/**
+ * Returns the first item of an iterable (or undefined if the iterable is empty).
+ * See `_firstFromIterable` for the iteration semantics.
+ */
+export function _firstOrUndefinedFromIterable(iter) {
+    for (const item of iter)
+        return item;
+    return undefined;
+}
 export function _minOrUndefined(array) {
     let min;
     for (const item of array) {

package/dist/is.util.js

@@ -33,10 +33,20 @@ export function _isPrimitive(v) {
         typeof v === 'symbol');
 }
 export function _isEmptyObject(obj) {
-    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) {
-    return Object.keys(obj).length > 0;
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return true;
+    }
+    return false;
 }
 /**
  * Object is considered empty if it's one of:
@@ -58,7 +68,11 @@ export function _isEmpty(obj) {
         return obj.size === 0;
     }
     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;
 }

package/dist/object/object.util.d.ts

@@ -87,6 +87,46 @@ export declare function _mapKeys<T extends AnyObject>(obj: T, mapper: ObjectMapp
  */
 export declare function _mapObject<OUT = unknown, IN extends AnyObject = AnyObject>(obj: IN, mapper: ObjectMapper<IN, KeyValueTuple<string, any> | typeof SKIP>): OUT;
 export declare function _findKeyByValue<T extends AnyObject>(obj: T, v: ValueOf<T>): keyof T | undefined;
+/**
+ * Returns the first key of a non-empty object.
+ * Throws 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 declare function _firstKey<T extends AnyObject>(obj: T): keyof T;
+/**
+ * Returns the first key of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export declare function _firstKeyOrUndefined<T extends AnyObject>(obj: T): keyof T | undefined;
+/**
+ * Returns the first value of a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export declare function _firstValue<T extends AnyObject>(obj: T): ValueOf<T>;
+/**
+ * Returns the first value of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export declare function _firstValueOrUndefined<T extends AnyObject>(obj: T): ValueOf<T> | undefined;
+/**
+ * Returns the first [key, value] tuple of a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export declare function _firstEntry<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>];
+/**
+ * Returns the first [key, value] tuple of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export declare function _firstEntryOrUndefined<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>] | undefined;
 export declare function _objectNullValuesToUndefined<T extends AnyObject>(obj: T, opt?: MutateOptions): T;
 /**
  * Deep copy object (by json parse/stringify, since it has unbeatable performance+simplicity combo).

package/dist/object/object.util.js

@@ -191,6 +191,82 @@ export function _mapObject(obj, mapper) {
 export function _findKeyByValue(obj, v) {
     return Object.entries(obj).find(([_, value]) => value === v)?.[0];
 }
+/**
+ * Returns the first key of a non-empty object.
+ * Throws 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(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return k;
+    }
+    throw new Error('_firstKey called on empty object');
+}
+/**
+ * Returns the first key of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstKeyOrUndefined(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return k;
+    }
+    return undefined;
+}
+/**
+ * Returns the first value of a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstValue(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return obj[k];
+    }
+    throw new Error('_firstValue called on empty object');
+}
+/**
+ * Returns the first value of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstValueOrUndefined(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return obj[k];
+    }
+    return undefined;
+}
+/**
+ * Returns the first [key, value] tuple of a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstEntry(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return [k, obj[k]];
+    }
+    throw new Error('_firstEntry called on empty object');
+}
+/**
+ * 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 _firstEntryOrUndefined(obj) {
+    for (const k in obj) {
+        if (Object.hasOwn(obj, k))
+            return [k, obj[k]];
+    }
+    return undefined;
+}
 export function _objectNullValuesToUndefined(obj, opt = {}) {
     return _mapValues(obj, (_k, v) => (v === null ? undefined : v), opt);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.75.0",
+  "version": "15.76.1",
   "dependencies": {
     "tslib": "^2"
   },
@@ -20,7 +20,7 @@
     "@typescript/native-preview": "beta",
     "crypto-js": "^4",
     "dayjs": "^1",
-    "@naturalcycles/dev-lib": "20.48.0"
+    "@naturalcycles/dev-lib": "18.4.2"
   },
   "exports": {
     ".": "./dist/index.js",

package/src/array/array.util.ts

@@ -468,6 +468,28 @@ export function _firstOrUndefined<T>(array: readonly T[]): T | undefined {
   return array[0]
 }
 
+/**
+ * Returns the first item of a non-empty iterable (Set, Map.values(), generator, etc.).
+ * Throws 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 {
+  for (const item of iter) return item
+  throw new Error('_firstFromIterable called on empty iterable')
+}
+
+/**
+ * Returns the first item of an iterable (or undefined if the iterable is empty).
+ * See `_firstFromIterable` for the iteration semantics.
+ */
+export function _firstOrUndefinedFromIterable<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) {

package/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

package/src/object/object.util.ts

@@ -242,6 +242,84 @@ 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 a non-empty object.
+ * Throws 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 {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return k as keyof T
+  }
+  throw new Error('_firstKey called on empty object')
+}
+
+/**
+ * Returns the first key of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstKeyOrUndefined<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 a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstValue<T extends AnyObject>(obj: T): ValueOf<T> {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return obj[k] as ValueOf<T>
+  }
+  throw new Error('_firstValue called on empty object')
+}
+
+/**
+ * Returns the first value of the object (or undefined if the object is empty).
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstValueOrUndefined<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 a non-empty object.
+ * Throws if the object is empty.
+ * See `_firstKey` for the iteration-order contract.
+ */
+export function _firstEntry<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>] {
+  for (const k in obj) {
+    if (Object.hasOwn(obj, k)) return [k as keyof T, obj[k] as ValueOf<T>]
+  }
+  throw new Error('_firstEntry called on empty object')
+}
+
+/**
+ * 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 _firstEntryOrUndefined<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 = {},