atomic-fns 1.1.6 → 1.2.0

package/dist/itertools/index.js

@@ -3,8 +3,8 @@
  *
  * @module itertools
  */
-import { call, isEmpty, isObject, notNull, ValueError } from '../globals/index.js';
-import { add, bool, compare, eq, id } from '../operators/index.js';
+import { call, isDate, isEmpty, isIterable, isObject, isRegExp, notNull, ValueError } from '../globals/index.js';
+import { add, bool, compare, eq, identity } from '../operators/index.js';
 /**
  * Make an iterator that returns accumulated sums, or accumulated results of other binary functions (specified via the optional `func` argument).
  * @param iterable The iterable to accumulate
@@ -15,15 +15,18 @@ import { add, bool, compare, eq, id } from '../operators/index.js';
 export function* accumulate(iterable, func = add, initial) {
     const it = iter(iterable);
     let total = initial;
-    let head = it.next();
-    if (initial == null)
+    if (initial == null) {
+        const head = it.next();
+        if (head.done)
+            return;
         total = head.value;
-    while (!head.done) {
+    }
+    while (true) {
         yield total;
-        head = it.next();
-        if (head.done)
+        const current = it.next();
+        if (current.done)
             return;
-        total = func(total, head.value);
+        total = func(total, current.value);
     }
 }
 /**
@@ -34,12 +37,12 @@ export function* accumulate(iterable, func = add, initial) {
  * @example
 ```js
 all([0])
-// true
+// false
 
 all([1, 2, 3])
 // true
 
-all([2, 4, 6] => (n) => n > 1)
+all([2, 4, 6], n => n > 1)
 // true
 ```
 @see {@link any}
@@ -64,7 +67,7 @@ any([0])
 any([0, 1, null, undefined])
 // true
 
-any([1, 4, 5] => (n) => n % 2 === 0)
+any([1, 4, 5], n => n % 2 === 0)
 // true
 ```
 @see {@link all}
@@ -89,9 +92,6 @@ export function chain(...iterables) {
 contains([1, 2, 3], 1)
 // true
 
-contains([1, 2, 3], 1, 2)
-// false
-
 contains({ 'a': 1, 'b': 2 }, 1)
 // true
 
@@ -107,7 +107,8 @@ export function contains(collection, value) {
     const includes = call(collection, 'includes', value);
     if (includes != null)
         return includes;
-    return any(collection, (x) => eq(value, x));
+    const items = isIterable(collection) ? collection : Object.values(collection);
+    return any(items, (x) => eq(value, x));
 }
 /**
  * Returns a generator that drops elements from the iterable as long as the predicate is `true`; afterwards, returns every remaining element. Note, the generator does not produce any output until the predicate first becomes `false`.
@@ -119,9 +120,9 @@ export function* dropWhile(iterable, predicate) {
     const it = iter(iterable);
     while (true) {
         const head = it.next();
+        if (head.done)
+            return head.value;
         if (!predicate(head.value)) {
-            if (head.done)
-                return head.value;
             yield head.value;
             break;
         }
@@ -140,14 +141,6 @@ export function iforEach(iterable, fun) {
         }
     }
 }
-export function IterableIterator(next) {
-    return {
-        next,
-        [Symbol.iterator]() {
-            return this;
-        }
-    };
-}
 /**
  * Yields elements like `[index, item]` from an iterable. Index starts at zero by default.
  * @template T
@@ -180,18 +173,20 @@ export function first(iterable) {
 }
 /**
  * Creates a new generator that filters all falsy and empty values from iterable.
- * @param arr The array to compact
- * @returns A new array with the filtered values.
+ * @param iterable The iterable to compact
+ * @returns A generator with the filtered values.
  * @example
 ```js
-compact([0, 1, false, 2, '', 3])
+[...icompact([0, 1, false, 2, '', 3])]
 // [1, 2, 3]
 ```
  */
 export function* icompact(iterable) {
     for (const value of iterable) {
-        if (!isEmpty(value))
+        // `isEmpty` reads arity and keys, which say nothing about these values
+        if (!isEmpty(value) || typeof value === 'function' || isDate(value) || isRegExp(value)) {
             yield value;
+        }
     }
 }
 /**
@@ -224,8 +219,12 @@ export function* iflatten(iterables) {
         }
     }
 }
-export function flatMap(iterable, mapFn = id) {
-    return iflatten(imap(iterable, mapFn));
+export function flatMap(iterable, mapFn = identity) {
+    const toIterable = (x) => {
+        const mapped = mapFn(x);
+        return isIterable(mapped) ? mapped : [mapped];
+    };
+    return iflatten(imap(iterable, toIterable));
 }
 export function* islice(iterable, start, stop, step = 1) {
     if (stop != null && stop < 0)
@@ -237,9 +236,9 @@ export function* islice(iterable, start, stop, step = 1) {
     if (step < 0)
         throw new ValueError(`step parameter can't be negative`);
     for (const [i, value] of enumerate(iterable)) {
+        if (stop != null && i >= stop)
+            return;
         if (i === start) {
-            if (stop && start + step > stop)
-                return value;
             yield value;
             start += step;
         }
@@ -280,7 +279,7 @@ export function partition(iterable, predicate) {
 /**
  * Returns a generator for a sequence of numbers in the given range, starting from `start` (default 0) to `stop` (not-inclusive) in increments of `step` (default 1).
  *
- * `range(x)` is a shorthand for `range(0, x, 1)`.
+ * `range(x)` is a shorthand for `range(0, x, 1)`, or `range(0, x, -1)` when `x` is negative.
  * @param args When called with a single argument, it is assigned to `stop` param. If two arguments are given, it will assign them to `(start, stop)`. When three arguments, it means `(start, stop, step)`.
  * @example
 ```js
@@ -297,7 +296,7 @@ range(5, 0, -1)
 // [5, 4, 3, 2, 1]
 
 range(-3)
-// []
+// [0, -1, -2]
 ```
  */
 export function* range(...args) {
@@ -338,7 +337,7 @@ reduce([1, 2, 3, 4, 5], (x, y) => x + y, 0)
 export function reduce(iterable, reducer, initial) {
     const it = iter(iterable);
     let output = initial ?? it.next().value;
-    for (const [index, value] of enumerate(it)) {
+    for (const [index, value] of enumerate({ [Symbol.iterator]: () => it })) {
         output = reducer(output, value, index);
     }
     return output;
@@ -357,17 +356,13 @@ export function sorted(args, key, reverse, compareFn) {
         args = Object.keys(args);
     }
     if (typeof key === 'boolean') {
-        if (typeof reverse === 'function') {
+        if (typeof reverse === 'function')
             compareFn = reverse;
-            reverse = false;
-        }
-        else {
-            reverse = true;
-        }
-        key = id;
+        reverse = key || reverse === true;
+        key = identity;
     }
     const copy = Array.from(args);
-    const _compare = compKey(compareFn || compare, key || id);
+    const _compare = compKey(compareFn || compare, key || identity);
     copy.sort(_compare);
     if (reverse)
         copy.reverse();
@@ -423,6 +418,8 @@ for item of zip([1, 2, 3], ['sugar', 'spice', 'nice'])
 ```
  */
 export function* zip(...args) {
+    if (args.length === 0)
+        return;
     const iterables = args.map(iter);
     while (true) {
         const items = [];

package/dist/math/index.d.ts

@@ -3,7 +3,7 @@
  *
  * @module math
  */
-import { Predicate } from '../types.js';
+import type { Predicate } from '../types.js';
 /**
  * Returns the absolute value of a number. The argument may be a number or an object implementing the `abs()`.
  * @param x The value.
@@ -21,35 +21,18 @@ export declare function abs(x: any): number;
  */
 export declare function round(x: number, digits?: number): number;
 /**
- * Rounds down and returns the largest integer less than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer less than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor Math.floor()}
- */
-export declare function floor(x: number): number;
-/**
- * Rounds up and returns the largest integer greater than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer greater than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil Math.ceil()}
- */
-export declare function ceil(x: number): number;
-/**
- * Returns a tuple like `[x / y, x % y]`.
+ * Returns a tuple like `[q, r]` with the floored quotient of `x / y` and a remainder that takes the sign of `y`, so `q * y + r` gives `x`, as in Python.
  *
  * @param x
  * @param y
  * @returns
  */
 export declare function divmod(x: number, y: number): [number, number];
-export declare function log2(x: any): number;
-export declare function logBase(x: any, y: any): number;
+export declare function logBase(x: number, y: number): number;
 /**
  * Returns the smallest element in an iterable. The optional `key` argument specifies a transform on the elements before comparing them. If the elements in the iterable are objects that implement a custom `lt` method, this will be called to compare.
  * @param iterable The iterable to inspect.
- * @param key Optional key function to transform the elements (default `id`).
+ * @param key Optional key function to transform the elements (default `identity`).
  * @returns The smallest element in the iterable.
  */
 export declare function min(iterable: number[]): number;
@@ -57,7 +40,7 @@ export declare function min<T>(iterable: Iterable<T>, key?: Predicate<T>): T;
 /**
  * Returns the largest element in an iterable. The optional `key` argument specifies a transform on the elements before comparing them. If the elements in the iterable are objects that implement a custom `gt` method, this will be called to compare.
  * @param iterable The iterable to inspect.
- * @param key Optional key function to transform the elements (default `id`).
+ * @param key Optional key function to transform the elements (default `identity`).
  * @returns The largest element in the iterable.
  */
 export declare function max(iterable: number[]): number;
@@ -72,24 +55,24 @@ export declare function max<T>(iterable: Iterable<T>, key?: Predicate<T>): T;
 ```js
 let objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }]
 
-mean(objects, (o) => o.n)
+mean(objects, o => o.n)
 // 5
 ```
  */
 export declare function mean(iterable: number[]): number;
 export declare function mean<T>(iterable: Iterable<T>, key?: Predicate<T>): number;
 /**
- * Sums `initial` and the items of an iterable and returns the total.
- * @param args The elements to add to `initial`.
- * @param initial The initial value to add to (default `0`).
- * @returns The total sum of initial and iterable elements.
+ * Sums the items of an iterable and returns the total. The optional `key` argument specifies a transform on the elements before adding them.
+ * @param args The elements to add.
+ * @param key Optional key function to transform the elements (default `identity`).
+ * @returns The total sum of the iterable elements.
  * @example
 ```js
 sum([1, 2, 3, 4])
 // 10
 
-sum([1, 2, 3, 4], 5)
-// 15
+sum([{ n: 1 }, { n: 2 }], o => o.n)
+// 3
 ```
  */
 export declare function sum(args: number[]): number;

package/dist/math/index.js

@@ -5,7 +5,7 @@
  */
 import { call } from '../globals/index.js';
 import { reduce } from '../itertools/index.js';
-import { gt, id, lt } from '../operators/index.js';
+import { gt, identity, lt } from '../operators/index.js';
 /**
  * Returns the absolute value of a number. The argument may be a number or an object implementing the `abs()`.
  * @param x The value.
@@ -28,43 +28,26 @@ export function abs(x) {
  */
 export function round(x, digits = 0) {
     const base = 10 ** digits;
-    return Math.round(x * base) / base;
+    const scaled = x * base;
+    // A number too large to scale has no digits left to round.
+    return Number.isFinite(scaled) ? Math.round(scaled) / base : Number(x);
 }
 /**
- * Rounds down and returns the largest integer less than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer less than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor Math.floor()}
- */
-export function floor(x) {
-    return Math.floor(x);
-}
-/**
- * Rounds up and returns the largest integer greater than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer greater than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil Math.ceil()}
- */
-export function ceil(x) {
-    return Math.ceil(x);
-}
-/**
- * Returns a tuple like `[x / y, x % y]`.
+ * Returns a tuple like `[q, r]` with the floored quotient of `x / y` and a remainder that takes the sign of `y`, so `q * y + r` gives `x`, as in Python.
  *
  * @param x
  * @param y
  * @returns
  */
 export function divmod(x, y) {
-    return [Math.floor(x / y), x % y];
-}
-export function log2(x) {
-    if (x > 0) {
-        return Math.log(x) * 1.442695;
+    let remainder = x % y;
+    let quotient = (x - remainder) / y;
+    if (remainder !== 0 && remainder < 0 !== y < 0) {
+        remainder += y;
+        quotient -= 1;
     }
-    return Number.NaN;
+    // A zero or NaN quotient keeps the sign of zero and the infinities of `x / y`.
+    return [Math.round(quotient) || Math.floor(x / y), remainder];
 }
 export function logBase(x, y) {
     if (x > 0 && y > 0) {
@@ -72,13 +55,13 @@ export function logBase(x, y) {
     }
     return Number.NaN;
 }
-export function min(iterable, key = id) {
+export function min(iterable, key = identity) {
     return reduce(iterable, (x, y) => (lt(key(x), key(y)) ? x : y));
 }
-export function max(iterable, key = id) {
+export function max(iterable, key = identity) {
     return reduce(iterable, (x, y) => (gt(key(x), key(y)) ? x : y));
 }
-export function mean(iterable, key = id) {
+export function mean(iterable, key = identity) {
     let total = 0;
     let count = 0;
     for (const value of iterable) {
@@ -89,7 +72,7 @@ export function mean(iterable, key = id) {
         return total / count;
     return Number.NaN;
 }
-export function sum(args, key = id) {
+export function sum(args, key = identity) {
     let initial = 0;
     for (const x of args) {
         initial += key(x);

package/dist/mod.d.ts

@@ -0,0 +1 @@
+export * from './index.js';

package/dist/mod.js

@@ -0,0 +1 @@
+export * from './index.js';

package/dist/operators/index.d.ts

@@ -3,8 +3,8 @@
  *
  * @module operators
  */
-/** This is the identity function. It always returns the same value that was passed in */
-export declare function id(x: any): any;
+/** This is the identity function. It always returns the same value that was passed in. */
+export declare const identity: <T>(x: T) => T;
 /**
  * Called to implement truth value testing.
  * @param x
@@ -27,7 +27,7 @@ export declare function isinstance(x: any, y: any): boolean;
  *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#parameters Array.sort()}
  */
-export declare type Comparer<T = any> = (x: T, y: T) => number;
+export type Comparer<T = any> = (x: T, y: T) => number;
 /**
  * Checks whether `x` is a comparable type and returns the result of `x.compare(y)`.
  * Otherwise the return value of the compare function is equivalent to `obj === other ? 0 : obj < other ? -1 : 1`

package/dist/operators/index.js

@@ -4,10 +4,8 @@
  * @module operators
  */
 import { call, isObject } from '../globals/index.js';
-/** This is the identity function. It always returns the same value that was passed in */
-export function id(x) {
-    return x;
-}
+/** This is the identity function. It always returns the same value that was passed in. */
+export const identity = (x) => x;
 /**
  * Called to implement truth value testing.
  * @param x
@@ -51,7 +49,9 @@ export function compare(x, y) {
     const op = call(x, 'compare', y);
     if (typeof op === 'number')
         return op;
-    if (x < y || lt(x, y))
+    if (x instanceof Date && y instanceof Date)
+        return Math.sign(x.getTime() - y.getTime()) || 0;
+    if (lt(x, y))
         return -1;
     return 1;
 }
@@ -63,7 +63,7 @@ export function compare(x, y) {
  * @returns {boolean} `true` if `x` and `y` are equal or `false` otherwise.
  */
 export function eq(x, y) {
-    return Object.is(x, y) || call(x, 'eq', y) != null;
+    return x === y || Object.is(x, y) || !!call(x, 'eq', y);
 }
 /**
  * Compares two values to check if `x` is strictly less than `y`. If `x` is an object with a `lt` method, it returns `x.lt(y)`.
@@ -73,7 +73,8 @@ export function eq(x, y) {
  * @returns {boolean} `true` if `x` is strictly less than `y` or `false` otherwise.
  */
 export function lt(x, y) {
-    return x < y || call(x, 'lt', y) != null;
+    const op = call(x, 'lt', y);
+    return op != null ? !!op : x < y;
 }
 /**
  * Compares two values to check if `x <= y`. If `x` is an object with a `lte` method, it returns `x.lte(y)`, also checks `x.eq(y)` and `x.lt(y)`.
@@ -85,13 +86,13 @@ export function lt(x, y) {
  * @see {@link lt}
  */
 export function lte(x, y) {
-    if (x <= y || call(x, 'lte', y))
-        return true;
-    if (x === y || eq(x, y))
-        return true;
-    if (x < y || lt(x, y))
-        return true;
-    return false;
+    const op = call(x, 'lte', y);
+    if (op != null)
+        return !!op;
+    const less = call(x, 'lt', y);
+    if (less != null)
+        return !!less || eq(x, y) || (call(y, 'lt', x) === false && x <= y);
+    return x <= y || eq(x, y);
 }
 /**
  * Compares two values to check if `x` is strictly greater than `y`. If `x` is an object with a `gt` method, it returns `x.gt(y)`.
@@ -101,7 +102,8 @@ export function lte(x, y) {
  * @returns {boolean} `true` if `x` is strictly greater than `y` or `false` otherwise.
  */
 export function gt(x, y) {
-    return x > y || call(x, 'gt', y);
+    const op = call(x, 'gt', y);
+    return op != null ? !!op : x > y;
 }
 /**
  * Compares two values to check if `x >= y`. If `x` is an object with a `gte` method, it returns `x.gte(y)`, also checks `x.eq(y)` and `x.gt(y)`.
@@ -113,13 +115,13 @@ export function gt(x, y) {
  * @see {@link gt}
  */
 export function gte(x, y) {
-    if (x <= y || call(x, 'gte', y))
-        return true;
-    if (x === y || eq(x, y))
-        return true;
-    if (x > y || gt(x, y))
-        return true;
-    return false;
+    const op = call(x, 'gte', y);
+    if (op != null)
+        return !!op;
+    const greater = call(x, 'gt', y);
+    if (greater != null)
+        return !!greater || eq(x, y) || (call(y, 'gt', x) === false && x >= y);
+    return x >= y || eq(x, y);
 }
 /**
  * The addition (+) operator. If `x` is an object with an `add` method, it returns `x.add(y)`.
@@ -199,6 +201,26 @@ export function pow(x, y) {
         return op;
     return x ** y;
 }
+/** Class names tell kinds apart across realms, where prototypes differ. */
+function sameKind(x, y) {
+    if (!x || !y || typeof x !== 'object' || typeof y !== 'object')
+        return false;
+    const tag = Object.prototype.toString;
+    if (tag.call(x) !== tag.call(y))
+        return false;
+    return (x.constructor?.name ?? 'Object') === (y.constructor?.name ?? 'Object');
+}
+function isList(x) {
+    return Array.isArray(x) || (ArrayBuffer.isView(x) && !(x instanceof DataView));
+}
+function isDateOrRegExp(x) {
+    return x instanceof Date || x instanceof RegExp;
+}
+function sameDateOrRegExp(x, y) {
+    if (x instanceof Date)
+        return Object.is(x.getTime(), y.getTime());
+    return String(x) === String(y);
+}
 /**
  * Performs a shallow comparison of two objects or arrays to check if they have the same keys, length and values.
  * @param obj
@@ -209,8 +231,10 @@ export function pow(x, y) {
 export function shallowEqual(obj, other) {
     if (obj === other)
         return true;
-    if (!obj || !other)
+    if (!sameKind(obj, other))
         return false;
+    if (isDateOrRegExp(obj))
+        return sameDateOrRegExp(obj, other);
     if (Array.isArray(obj)) {
         // compare the arrays
         if (obj.length !== other.length)
@@ -229,7 +253,7 @@ export function shallowEqual(obj, other) {
         if (objKeys.length !== otherKeys.length)
             return false;
         for (const key of objKeys) {
-            if (!Object.prototype.hasOwnProperty.call(other, key) || obj[key] !== other[key]) {
+            if (!Object.hasOwn(other, key) || obj[key] !== other[key]) {
                 return false;
             }
         }
@@ -237,21 +261,26 @@ export function shallowEqual(obj, other) {
     }
     return false;
 }
-export function deepEqual(obj, other, checker = eq, seen = new WeakSet()) {
+export function deepEqual(obj, other, checker = eq, seen = new WeakMap()) {
+    if (!(seen instanceof WeakMap))
+        seen = new WeakMap();
     if (checker(obj, other))
         return true;
-    if (!obj || !other)
-        return false;
-    if (obj.prototype !== other.prototype)
-        return false;
-    if (seen.has(obj) && seen.has(other))
+    if (!sameKind(obj, other))
         return false;
-    if (Array.isArray(obj)) {
+    if (isDateOrRegExp(obj))
+        return sameDateOrRegExp(obj, other);
+    // A pair that was compared before needs no second walk: it either held, or the call has returned.
+    const partners = seen.get(obj) ?? new WeakSet();
+    if (partners.has(other))
+        return true;
+    seen.set(obj, partners.add(other));
+    if (isList(obj)) {
         // compare the arrays
         if (obj.length !== other.length)
             return false;
         for (let i = 0; i < obj.length; i++) {
-            if (!deepEqual(obj[i], other[i], checker)) {
+            if (!deepEqual(obj[i], other[i], checker, seen)) {
                 return false;
             }
         }
@@ -270,8 +299,6 @@ export function deepEqual(obj, other, checker = eq, seen = new WeakSet()) {
         // compare keys and values
         if (obj.size !== other.size)
             return false;
-        seen.add(obj);
-        seen.add(other);
         for (const key of obj.keys()) {
             if (!other.has(key))
                 return false;
@@ -287,11 +314,8 @@ export function deepEqual(obj, other, checker = eq, seen = new WeakSet()) {
         const otherKeys = Object.keys(other);
         if (objKeys.length !== otherKeys.length)
             return false;
-        seen.add(obj);
-        seen.add(other);
         for (const key of objKeys) {
-            if (!Object.prototype.hasOwnProperty.call(other, key) ||
-                !deepEqual(obj[key], other[key], checker, seen)) {
+            if (!Object.hasOwn(other, key) || !deepEqual(obj[key], other[key], checker, seen)) {
                 return false;
             }
         }

package/dist/random/index.js

@@ -11,7 +11,8 @@ import { isObject } from '../globals/index.js';
  * @returns {number}
  */
 export function random(min = 0, max = 1) {
-    return Math.random() * (max - min) + min;
+    const value = Math.random() * (max - min) + min;
+    return value === max ? min : value;
 }
 /**
  * Returns a random integer between a [min, max] value (inclusive).
@@ -20,7 +21,9 @@ export function random(min = 0, max = 1) {
  * @returns {number}
  */
 export function randomInt(min = 0, max = 1) {
-    return Math.round(random(min, max));
+    const low = Math.ceil(Math.min(min, max));
+    const high = Math.floor(Math.max(min, max));
+    return low + Math.floor(random(0, high - low + 1));
 }
 /**
  * Returns the item at some random index in a sequence.
@@ -42,7 +45,7 @@ export function choice(arr) {
 export function sample(arr, size) {
     if (!arr?.length || arr.length < size)
         return [];
-    return shuffle(arr.slice()).slice(-size);
+    return shuffle(arr.slice()).slice(0, size);
 }
 /**
  * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
@@ -53,11 +56,11 @@ export function sample(arr, size) {
  * @template T
  */
 export function shuffle(arr, size) {
-    if (!arr?.length)
-        return arr;
     if (isObject(arr))
         arr = Object.values(arr);
-    if (size == null)
+    if (!arr?.length)
+        return arr;
+    if (size == null || size >= arr.length)
         size = arr.length - 1;
     for (let i = 0; i <= size; i++) {
         const j = randomInt(i, size);

package/dist/string/index.d.ts

@@ -33,7 +33,7 @@ export declare function capitalize(s: string): string;
 /**
  * Split a string into an array of its words.
  * @param {string} s The string to split
- * @param {RegExp | string} [pattern] The pattern to match words
+ * @param {RegExp | string} [pattern] The separator to split on, instead of matching words
  * @returns {string[]} Returns the words array.
  * @example
 ```js