@naturalcycles/js-lib 15.76.0 → 15.76.1

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

@@ -218,14 +218,19 @@ export declare function _first<T>(array: readonly T[]): T;
  */
 export declare function _firstOrUndefined<T>(array: readonly T[]): T | undefined;
 /**
- * Returns the first item of an iterable (Set, Map.values(), generator, etc.),
- * or `undefined` if the iterable is empty.
+ * 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 | undefined;
+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

@@ -404,14 +404,23 @@ export function _firstOrUndefined(array) {
     return array[0];
 }
 /**
- * Returns the first item of an iterable (Set, Map.values(), generator, etc.),
- * or `undefined` if the iterable is empty.
+ * 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;

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

@@ -88,7 +88,8 @@ 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 the object, or `undefined` if the object is empty.
+ * 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
@@ -98,18 +99,34 @@ export declare function _findKeyByValue<T extends AnyObject>(obj: T, v: ValueOf<
  * objects (integer-like keys ascending first, then string keys in
  * insertion order).
  */
-export declare function _firstKey<T extends AnyObject>(obj: T): keyof T | undefined;
+export declare function _firstKey<T extends AnyObject>(obj: T): keyof T;
 /**
- * Returns the first value of the object, or `undefined` if the object is empty.
+ * Returns the first key of the object (or undefined if the object is empty).
  * See `_firstKey` for the iteration-order contract.
  */
-export declare function _firstValue<T extends AnyObject>(obj: T): ValueOf<T> | undefined;
+export declare function _firstKeyOrUndefined<T extends AnyObject>(obj: T): keyof T | undefined;
 /**
- * Returns the first [key, value] tuple of the object,
- * or `undefined` if the object is empty.
+ * 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 _firstEntry<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>] | undefined;
+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

@@ -192,7 +192,8 @@ export function _findKeyByValue(obj, v) {
     return Object.entries(obj).find(([_, value]) => value === v)?.[0];
 }
 /**
- * Returns the first key of the object, or `undefined` if the object is empty.
+ * 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
@@ -203,6 +204,17 @@ export function _findKeyByValue(obj, v) {
  * 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;
@@ -210,10 +222,22 @@ export function _firstKey(obj) {
     return undefined;
 }
 /**
- * Returns the first value of the object, or `undefined` if the object is empty.
+ * 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];
@@ -221,11 +245,22 @@ export function _firstValue(obj) {
     return undefined;
 }
 /**
- * Returns the first [key, value] tuple of the object,
- * or `undefined` if the object is empty.
+ * 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]];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.76.0",
+  "version": "15.76.1",
   "dependencies": {
     "tslib": "^2"
   },

package/src/array/array.util.ts

@@ -469,14 +469,23 @@ export function _firstOrUndefined<T>(array: readonly T[]): T | undefined {
 }
 
 /**
- * Returns the first item of an iterable (Set, Map.values(), generator, etc.),
- * or `undefined` if the iterable is empty.
+ * 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 | undefined {
+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
 }

package/src/object/object.util.ts

@@ -243,7 +243,8 @@ export function _findKeyByValue<T extends AnyObject>(obj: T, v: ValueOf<T>): key
 }
 
 /**
- * Returns the first key of the object, or `undefined` if the object is empty.
+ * 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
@@ -253,7 +254,18 @@ export function _findKeyByValue<T extends AnyObject>(obj: T, v: ValueOf<T>): key
  * objects (integer-like keys ascending first, then string keys in
  * insertion order).
  */
-export function _firstKey<T extends AnyObject>(obj: T): keyof T | undefined {
+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
   }
@@ -261,10 +273,22 @@ export function _firstKey<T extends AnyObject>(obj: T): keyof T | undefined {
 }
 
 /**
- * Returns the first value of the object, or `undefined` if the object is empty.
+ * 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> | undefined {
+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>
   }
@@ -272,11 +296,24 @@ export function _firstValue<T extends AnyObject>(obj: T): ValueOf<T> | undefined
 }
 
 /**
- * Returns the first [key, value] tuple of the object,
- * or `undefined` if the object is empty.
+ * 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 _firstEntry<T extends AnyObject>(obj: T): [keyof T, ValueOf<T>] | undefined {
+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>]
   }