ferrum - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

package.json

 {
   "name": "ferrum",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "",
@@ -5,0 +5,0 @@ "main": "src/index.js",

src/sequence.js

@@ -16,3 +16,3 @@ /*
 // declaraions...
-/* eslint-disable no-use-before-define, no-param-reassign, no-restricted-syntax */
+/* eslint-disable no-use-before-define, no-param-reassign, no-restricted-syntax, no-return-assign */
 
@@ -299,5 +299,17 @@ const { curry, pipe } = require('./functional');
  * Extracts the next element from the iterator.
- * If the element is exhausted, IteratorEnded will be thrown
  *
+ * ```
+ * const {iter, next} = require('ferrum');
+ *
+ * const it = iter([1,2,3]);
+ * next(it); // => 1
+ * next(it); // => 2
+ * next(it); // => 3
+ * next(it); // throws IteratorEnded
+ * next(it); // throws IteratorEnded
+ * ```
+ *
+ * @function
  * @param {Sequence} seq Any sequence for which iter() is defined
+ * @throws {IteratorEnded} If the sequence is empty
  * @returns {Any}
@@ -314,9 +326,196 @@ */
 
-/** Extract the nth element from the sequence */
+/**
+ * Extracts the next element from the iterator.
+ *
+ * ```
+ * const {iter, tryNext} = require('ferrum');
+ *
+ * const it = iter([1,2,3]);
+ * tryNext(it, null); // => 1
+ * tryNext(it, null); // => 2
+ * tryNext(it, null); // => 3
+ * tryNext(it, null); // => null
+ * tryNext(it, null); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Any} fallback The value to return if the sequence is empty
+ * @returns {Any}
+ */
+const tryNext = curry('tryNext', (seq, fallback) => {
+  const { done, value } = iter(seq).next();
+  if (done) {
+    return fallback;
+  } else {
+    return value;
+  }
+});
+
+/**
+ * Extract the nth element from the sequence
+ *
+ * ```
+ * const {iter, next, nth} = require('ferrum');
+ *
+ *
+ * const it = iter('hello world');
+ * nth(it, 3);  // => 'l'
+ * next(it);    // => 'o'
+ *
+ * const fifth = nth(4);
+ * fifth(it)  // => 'l'
+ * nth(it, 10); // throws IteratorEnded
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Number} idx The index of the element
+ * @throws {IteratorEnded} If the sequence is too short
+ * @returns {Any}
+ */
 const nth = curry('nth', (seq, idx) => next(skip(seq, idx)));
-/** Extract the first element from the sequence */
+/**
+ * Extract the first element from the sequence; this is effectively
+ * an alias for next();
+ *
+ * ```
+ * const {first} = require('ferrum');
+ *
+ * first([1,2]) // => 1
+ * first([]); // throws IteratorEnded
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @throws {IteratorEnded} If the sequence is too short
+ * @returns {Any}
+ */
 const first = seq => next(seq);
-/** Extract the second element from the sequence */
+/**
+ * Extract the second element from the sequence
+ *
+ * ```
+ * const {second} = require('ferrum');
+ *
+ * second([1,2]) // => 2
+ * second([1]); // throws IteratorEnded
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @throws {IteratorEnded} If the sequence is too short
+ * @returns {Any}
+ */
 const second = seq => nth(seq, 1);
+/**
+ * Extract the last element from the sequence
+ *
+ * ```
+ * const {last} = require('ferrum');
+ *
+ * last([1,2,3,4,5]) // => 5
+ * last([]); // throws IteratorEnded
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @throws {IteratorEnded} If the sequence is empty
+ * @returns {Any}
+ */
+const last = (seq) => {
+  const nothing = Symbol('');
+  const v = tryLast(seq, nothing);
+  if (v === nothing) {
+    throw new IteratorEnded();
+  } else {
+    return v;
+  }
+};
 
+/**
+ * Extract the nth element from the sequence
+ *
+ * ```
+ * const {iter, next, tryNth} = require('ferrum');
+ *
+ * const it = iter('hello world');
+ * tryNth(it, null, 3);  // => 'l'
+ * next(it);    // => 'o'
+ *
+ * const fifth = nth(4, null);
+ * fifth(it)  // => 'l'
+ * tryNth(it, 10, null); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Number} idx The index of the element
+ * @param {Any} fallback The value to return if the sequence is too short
+ * @returns {Any}
+ */
+const tryNth = curry('tryNth', (seq, idx, fallback) => tryNext(trySkip(seq, idx), fallback));
+/**
+ * Extract the first element from the sequence; this is effectively
+ * an alias for tryNext();
+ *
+ * ```
+ * const {tryFirst} = require('ferrum');
+ *
+ * tryFirst([1,2], null) // => 1
+ * tryFirst([], null);   // => null
+ *
+ * const fn = tryFirst(null);
+ * fn([]); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Any} fallback The value to return if the sequence is too short
+ * @returns {Any}
+ */
+const tryFirst = curry('tryFirst', (seq, fallback) => tryNext(seq, fallback));
+/**
+ * Extract the second element from the sequence
+ *
+ * ```
+ * const {trySecond} = require('ferrum');
+ *
+ * trySecond([1,2], null) // => 2
+ * trySecond([1], null);  // => null
+ *
+ * const fn = trySecond(null);
+ * fn([1]); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Any} fallback The value to return if the sequence is too short
+ * @returns {Any}
+ */
+const trySecond = curry('trySecond', (seq, fallback) => tryNth(seq, 1, fallback));
+/**
+ * Extract the last element from the sequence
+ *
+ * ```
+ * const {tryLast} = require('ferrum');
+ *
+ * tryLast([1,2,3,4,5], null) // => 5
+ * tryLast([], null); // => null
+ *
+ * const fn = tryLast(null);
+ * fn([]); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Any} fallback The value to return if the sequence is empty
+ * @returns {Any}
+ */
+const tryLast = curry('tryLast', (seq, fallback) => {
+  let r = fallback;
+  each(seq, v => r = v);
+  return r;
+});
+
 // ITERATOR SINKS ////////////////////////////////////////////
@@ -328,2 +527,15 @@
  *
+ * ```
+ * const {each} = require('ferrum');
+ *
+ * each({foo: 42, bar: 23}, ([key, value]) => {
+ *   console.log(`${key}: ${value}`)
+ * });
+ *
+ * each([1,2,3], (v) => {
+ *   console.log(v);
+ * });
+ * ```
+ *
+ * @function
  * @param {Sequence} seq Any sequence for which iter() is defined
@@ -338,3 +550,87 @@ * @param {Function} fn Function taking a single parameter
 
-/** Determine whether the items in two sequences are equal. */
+/**
+ * Return the first element in the sequence for which the predicate matches.
+ *
+ * ```
+ * const {find} = require('ferrum');
+ *
+ * find([1,2,3,4], v => v>2); // => 3
+ * find([1,2,3,4], v => v>10); // throws IteratorEnded
+ *
+ * const findEven = find(v => v % 2 === 0);
+ * find([3,4,1,2]); // => 4
+ * find([]); // throws IteratorEnded
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Function} fn The predicate
+ * @throws {IteratorEnded} If no element in the sequence matches the predicate..
+ * @returns Any
+ */
+const find = curry('find', (seq, fn) => next(filter(seq, fn)));
+
+/**
+ * Return the first element in the sequence for which the predicate matches.
+ *
+ * ```
+ * const {tryFind} = require('ferrum');
+ *
+ * tryFind([1,2,3,4], null, v => v>2); // => 3
+ * tryFind([1,2,3,4], null, v => v>10); // => null
+ *
+ * const findEven = tryFind(null, v => v%2 === 0);
+ * findEven([1,9,10,14]); // => 10
+ * findEven([]); // => null
+ * ```
+ *
+ * @function
+ * @param {Sequence} seq Any sequence for which iter() is defined
+ * @param {Any} fallback The value to return if no element in the sequence matches the predicate
+ * @param {Function} fn The predicate
+ * @returns Any
+ */
+const tryFind = curry('tryFind', (seq, fallback, fn) => tryNext(filter(seq, fn), fallback));
+
+/**
+ * Determine whether the items in two sequences are equal.
+ *
+ * ```
+ * const {seqEq, eq} = require('ferrum');
+ *
+ * seqEq([1,2,3,4], [1,2,3,4]); // => true
+ * seqEq([1,2,3,4], [1,2,3]); // => false
+ *
+ * // The types of the objects being compared is not important,
+ * // just the contents of the iterator
+ * seqEq(new Set([1,2,3]), [1,2,3]); // => true
+ * seqEq(new Set([1,2,3,3]), [1,2,3,3]); // => false (the set discards the second 3)
+ *
+ * // Note that sets and maps should usually compared using eq() and not
+ * // seqEq, since seqEq cares about the infestation order while eq() does
+ * // not for sets and maps
+ * eq(new Set([1,2,3]), new Set([1,2,3])); // => true
+ * eq(new Set([3,2,1]), new Set([1,2,3])); // => true
+ *
+ * seqEq(new Set([1,2,3]), new Set([1,2,3])); // => true
+ * seqEq(new Set([3,2,1]), new Set([1,2,3])); // => false
+ *
+ * // Objects should never be compared using seqEq, because the order
+ * // in which the elements of an object are returned is undefined
+ * const obj = {foo: 23, bar: 42};
+ * seqEq(obj, obj); // UNDEFINED BEHAVIOUR; could be true or false
+ *
+ * // Same goes of course for es6 Maps created from objects
+ * seqEq(dict(obj), dict(obj))); // => UNDEFINED BEHAVIOUR; could be true or false
+ *
+ * // Objects as elements inside the iterator are OK; elements are compared
+ * // using eq() not seqEq()
+ * seqEq([{foo: 42, bar: 23}], [{bar: 23, foo: 42}]); // => true
+ * ```
+ *
+ * @function
+ * @param {Sequence} a Any sequence for which iter() is defined
+ * @param {Sequence} b Any sequence for which iter() is defined
+ * @returns {Boolean}
+ */
 const seqEq = (a, b) => pipe(
@@ -350,2 +646,15 @@ zipLongest([a, b], Symbol('EqualToNothing')),
  * over the container and counting the elements this way if necessary.
+ *
+ * ```
+ * const {iter,count} = require('ferrum')
+ *
+ * count([1,2,3]); // => 3; O(1)
+ * count(iter([1,2,3])); // => 3; O(n)
+ * ```
+ *
+ * See: [https://en.wikipedia.org/wiki/Big_O_notation]()
+ *
+ * @function
+ * @param {Sequence} a Any sequence for which iter() is defined
+ * @returns {Number}
  */
@@ -1059,7 +1368,15 @@ const count = (val) => {
   next,
+  tryNext,
   nth,
   first,
   second,
+  last,
+  tryNth,
+  tryFirst,
+  trySecond,
+  tryLast,
   seqEq,
   each,
+  find,
+  tryFind,
   count,
@@ -1066,0 +1383,0 @@ list,

test/sequence.test.js

@@ -21,3 +21,4 @@ /*
   iter, range, range0, repeat, extend, extend1, flattenTree,
-  IteratorEnded, next, nth, first, second, seqEq, each, count, list, uniq,
+  IteratorEnded, next, tryNext, nth, first, second, last, tryNth, tryFirst,
+  trySecond, tryLast, seqEq, each, find, tryFind, count, list, uniq,
   join, dict, obj, into, foldl, foldr, any, all, sum, product, map,
@@ -161,12 +162,36 @@ filter, reject, reverse, enumerate, trySkip, skip, skipWhile, tryTake,
 
-it('nth()', () => {
-  ckThrows(IteratorEnded, () => nth([1, 2, 3, 4], 5));
-  assert.strictEqual(nth([1, 2, 3, 4], 2), 3);
+it('tryNext(), tryFirst()', () => {
+  each([tryNext, tryFirst], (fn) => {
+    assert.deepStrictEqual(fn(null)({ foo: 42 }), ['foo', 42]);
+    each([{}, [], ''], (cont) => {
+      assertEquals(fn(null)(cont), null);
+    });
+  });
 });
 
-it('second()', () => {
+it('nth(), tryNth()', () => {
+  ckThrows(IteratorEnded, () => nth([1, 2, 3, 4], 10));
+  assertEquals(nth([1, 2, 3, 4], 2), 3);
+
+  assertEquals(tryNth(null)(5)([1,2,3]), null);
+  assertEquals(tryNth(null)(2)([1,2,3]), 3);
+});
+
+it('second(), trySecond', () => {
   ckThrows(IteratorEnded, () => second([4]));
   assert.strictEqual(second([4, 3]), 3);
+
+  assertEquals(trySecond(null)([]), null);
+  assertEquals(trySecond(null)([1,2,3]), 2);
 });
 
+it('last()', () => {
+  ckThrows(IteratorEnded, () => last([]));
+  assert.strictEqual(last([4, 3]), 3);
+
+  assertEquals(tryLast(null)([]), null);
+  assertEquals(tryLast(null)([1,2,3]), 3);
+  assertEquals(tryLast(null)([1,2,3,4]), 4);
+});
+
 it('into(), list()', () => {
@@ -404,2 +429,10 @@ each([list, into(Array)], (fn) => {
 
+it('find, tryFind', () => {
+  assertEquals(find([1,2,3,4], x => x>2), 3);
+  ckThrows(IteratorEnded, () => find([1,2,3,4], x => x>10));
+
+  assertEquals(tryFind([1,2,3,4], null, x => x>2), 3);
+  assertEquals(tryFind([1,2,3,4], null, x => x>10), null);
+});
+
 it('union/union2', () => {
@@ -406,0 +439,0 @@ const o2 = {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 4 instances in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 20 instances in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Number of medium supply chain risk alerts

4

decreased by-80.95%

Worsened metrics

Total package byte prevSize

951099

decreased by-68.81%

Number of package files

74

decreased by-51.95%

Lines of code

5518

decreased by-25.91%

No dependency changes