atomic-fns 0.1.1 → 0.2.0

package/.esdoc.json

@@ -0,0 +1,9 @@
+{
+  "source": "./src",
+  "destination": "./docs",
+  "plugins": [
+    {
+      "name": "esdoc-standard-plugin"
+    }
+  ]
+}

package/README.md

@@ -4,15 +4,17 @@
 
 Stop shipping code built for browsers from 2015. Really though, look at the [issues](https://github.com/lodash/lodash/issues/2930#issuecomment-370295020).
 
-* Modular: Pick what you need. Works with all bundlers and also supports tree-shaking.
-* Native: Uses newer data structures and control flow techniques.
-* Lazy: Leverages generators, iterators and functional composition.
-* Fluent: Pure functions and abstract classes. Include only what you need.
-* TypeScript & JSDoc: Supports both TypeScript and latest JS spec. JSDoc for best in class experience.
+* **Modular**: Pick what you need. Works with all bundlers and also supports tree-shaking.
+* **ESNext**: Uses modern idiomatic syntax, data structures, and control flow techniques.
+* **Lazy**: Leverage generators, iterators, and functional composition.
+* **Fluent**: Pure functions and abstract classes. Include only what you need.
+* **TypeScript & docs**: Includes both type declaration files and js with JSDocs for best in class experience.
+
+## Get Started
 
 This library is available as an npm package. To install the package just run:
 
-```
+```bash
 npm install atomic-fns
 ```
 
@@ -21,24 +23,24 @@ npm install atomic-fns
 import { id, reversed, sorted, times, uniqueId } from 'atomic-fns'
 
 reverse([1, 2, 3, 4])
-// => [4, 3, 2, 1]
+// -> [4, 3, 2, 1]
 
 sorted([4, 3, 2, 1])
-// => [1, 2, 3, 4]
+// -> [1, 2, 3, 4]
 
 times(5, id)
-// => [0, 1, 2, 3, 4]
+// -> [0, 1, 2, 3, 4]
 
 times(5, id)
-// => [0, 1, 2, 3, 4]
+// -> [0, 1, 2, 3, 4]
 
 uniqueId('user_')
-// => 'user_101225005'
+// -> 'user_101225005'
 ```
 
 ## Docs
 
-🛠 Under construction.
+🚢 Coming soon at [atomic-fns.dev](https://atomic-fns.dev).
 
 💡 See the `src` directory for comments.
 

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "atomic-fns",
-  "description": "A general-purpose and forward looking toolbox for evergreen JS code standards.",
-  "version": "0.1.1",
-  "main": "build/index.js",
+  "description": "Like Lodash, but for ESNext and with types. Stop shipping code built for browsers from 2015.",
+  "version": "0.2.0",
+  "main": "src/index.js",
   "type": "module",
   "devDependencies": {
     "@types/jasmine": "^4.3.0",
     "@typescript-eslint/eslint-plugin": "^5.39.0",
+    "esdoc": "^1.1.0",
+    "esdoc-standard-plugin": "^1.0.0",
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-config-standard-with-typescript": "^23.0.0",
@@ -24,12 +26,13 @@
     "typescript": "^4.8.4"
   },
   "scripts": {
-    "postinstall": "npm run tsc",
+    "prepublishOnly": "npm test && npm run tsc",
     "test": "NODE_OPTIONS=--loader=ts-node/esm jasmine --config=jasmine.json",
     "tsc": "tsc -p ./tsconfig.xo.json --declaration",
     "lint": "eslint src/**",
     "lint:fix": "eslint src/** --fix",
-    "format": "prettier --write src/**"
+    "format": "prettier --write src/**",
+    "docs": "npm run tsc && esdoc"
   },
   "lint-staged": {
     "*.ts": "eslint"
@@ -41,12 +44,14 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/adrian2x/atomic-fns.git"
+    "url": "https://github.com/adrian2x/atomic-fns.git"
   },
   "keywords": [
-    "es-next",
+    "atomic",
+    "atomicfns",
+    "atomic-fns",
     "esnext",
-    "ecmascript",
+    "es-next",
     "@esnext",
     "@es-next",
     "es6",
@@ -56,16 +61,21 @@
     "es2017",
     "es2019",
     "es2020",
+    "es2021",
+    "es2022",
+    "es2023",
+    "lodash",
+    "lazy",
     "modules",
     "stdlib",
     "core-js",
     "util",
     "fp"
   ],
-  "author": "Adrian Cruz <adrian2x>",
+  "author": "Adrian Cruz <kangoonie@gmail.com>",
   "license": "Apache-2.0",
   "bugs": {
-    "url": "https://github.com/adrian2x/es-next/issues"
+    "url": "https://github.com/adrian2x/atomic-fns/issues"
   },
-  "homepage": "https://github.com/adrian2x/es-next#readme"
-}
+  "homepage": "https://github.com/adrian2x/atomic-fns#readme"
+}

package/{build → src}/collections.d.ts

@@ -1,18 +1,17 @@
-/// <reference path="../src/globals.d.ts" />
 import { Function, Iteratee } from './globals.js';
 /**
  * A container type that provides contains().
  *
- * @export
+ *
  * @interface Container
  */
 export interface Container {
     contains: (x: any) => boolean;
 }
 /**
- * These are the "rich comparison" methods, as in Python.
+ * These are the "rich comparison" methods, inspired by Python operators.
+ *
  *
- * @export
  * @interface Comparable
  */
 export interface Comparable {
@@ -33,7 +32,7 @@ export interface Comparable {
  * A Collection is an iterable container type.
  * This is an abstract base class for user-defined collection types.
  *
- * @export
+ *
  * @abstract
  * @class Collection
  * @implements {Container}
@@ -87,7 +86,7 @@ export interface Reversible<T = unknown> {
 /**
  * A sequence is an iterable type with efficient index-based access.
  *
- * @export
+ *
  * @abstract
  * @class Sequence
  * @extends {Collection}
@@ -141,6 +140,14 @@ export declare abstract class Sequence<T> extends Collection implements Reversib
     size(): number;
     reversed(): Iterator<T>;
 }
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
 export declare class FrozenSet<T = any> extends Set<T> {
     constructor(iterable: Iterable<T>);
     add(): this;
@@ -149,7 +156,20 @@ export declare class FrozenSet<T = any> extends Set<T> {
     freeze(): Readonly<this>;
 }
 export declare const compact: (...arr: any[]) => any[];
-export declare function namedtuple(...fields: string[]): (...args: any[]) => any[][];
+/**
+ * Creates a function that can be used to create named tuple-like objects.
+ * @example
+ * ```
+ * let Point = namedtuple('x', 'y', 'z')
+ * let userObj = User(0, 0, 0)
+ * // -> {x: 0, y: 0, z: 0}
+ * ```
+ *
+ *
+ * @param {...string[]} fields
+ * @return
+ */
+export declare function namedtuple(...fields: string[]): (...args: any[]) => {};
 export declare function filter(arr: any, fn?: Iteratee | PropertyKey | Object): any[] | undefined;
 export declare function find(arr: any, fn: Iteratee | PropertyKey | Object): any;
 export declare function findRight(arr: any, fn: Iteratee | PropertyKey | Object): any;
@@ -168,7 +188,7 @@ export declare function lastIndexOf(obj: any, x: any, start?: any): any;
 /**
  * Creates a clone of the given `obj`. If `deep` is `true` it will clone it recursively.
  *
- * @export
+ *
  * @param {*} obj
  * @param {boolean} [deep=false]
  * @return The clone value
@@ -184,7 +204,7 @@ export declare function sortedUniq(arr: any, fn?: string | Iteratee): any[];
  *
  * Note: this method mutates `obj`
  *
- * @export
+ *
  * @param {Object} obj
  * @param {...Object} sources
  * @return {Object} The destination object.
@@ -196,7 +216,7 @@ export declare function union(...args: any[]): Generator<unknown, void, unknown>
 /**
  * Creates an object composed of keys generated from the results of running each element of `arr` thru `func`. The order of grouped values is determined by the order they occur in `arr`. The corresponding value of each key is an array of elements responsible for generating the key.
  *
- * @export
+ *
  * @param {(any[] | Object)} arr The collection to iterate over.
  * @param {(Iteratee | PropertyKey)} [func=id] The iteratee to transform keys.
  * @return {Object} Returns the composed aggregate object.

package/{build → src}/collections.js

@@ -1,11 +1,10 @@
-/// <reference path='globals.d.ts'/>
-import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunc, isNull, isNumber, isObject, isString, keys, NotImplementedError } from './globals.js';
+import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunc, isNull, isNumber, isObject, isString, keys, NotImplementedError, set } from './globals.js';
 import { comp, eq, id } from './operators.js';
 /**
  * A Collection is an iterable container type.
  * This is an abstract base class for user-defined collection types.
  *
- * @export
+ *
  * @abstract
  * @class Collection
  * @implements {Container}
@@ -58,7 +57,7 @@ export class Collection {
 /**
  * A sequence is an iterable type with efficient index-based access.
  *
- * @export
+ *
  * @abstract
  * @class Sequence
  * @extends {Collection}
@@ -124,6 +123,14 @@ export class Sequence extends Collection {
         throw new NotImplementedError();
     }
 }
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
 export class FrozenSet extends Set {
     constructor(iterable) {
         super(iterable);
@@ -146,8 +153,21 @@ export class FrozenSet extends Set {
     }
 }
 export const compact = (...arr) => arr.filter((x) => !isEmpty(x));
+/**
+ * Creates a function that can be used to create named tuple-like objects.
+ * @example
+ * ```
+ * let Point = namedtuple('x', 'y', 'z')
+ * let userObj = User(0, 0, 0)
+ * // -> {x: 0, y: 0, z: 0}
+ * ```
+ *
+ *
+ * @param {...string[]} fields
+ * @return
+ */
 export function namedtuple(...fields) {
-    return (...args) => fields.map((f, i) => [f, args[i]]);
+    return (...args) => fields.reduce((prev, f, i) => set(prev, f, args[i], false, true), {});
 }
 export function filter(arr, fn = isNull) {
     if (Array.isArray(arr)) {
@@ -155,18 +175,17 @@ export function filter(arr, fn = isNull) {
         if (typeof fn === 'function')
             return arr.filter(fn);
         if (typeof fn === 'string')
-            return arr.filter((x) => x?.[fn]);
+            return arr.filter((x) => get(x, fn));
         if (isObject(fn))
             return arr.filter(matches(fn));
     }
 }
 export function find(arr, fn) {
     if (Array.isArray(arr)) {
-        // @ts-expect-error function is not compatible?
         if (typeof fn === 'function')
             return arr.find(fn);
         if (typeof fn === 'string')
-            return arr.find((x) => x?.[fn]);
+            return arr.find((x) => x && x[fn]);
         if (isObject(fn))
             return arr.find(matches(fn));
     }
@@ -180,7 +199,7 @@ export function findRight(arr, fn) {
                     return x;
             }
             else if (typeof fn === 'string') {
-                if (x?.[fn])
+                if (x && x[fn])
                     return x;
             }
             else if (isObject(fn)) {
@@ -191,8 +210,10 @@ export function findRight(arr, fn) {
     }
 }
 export const matches = (o) => (x) => {
+    if (!o || !x)
+        return false;
     for (const key in o) {
-        if (!eq(x?.[key], o[key]))
+        if (!eq(x[key], o[key]))
             return false;
     }
     return true;
@@ -260,7 +281,7 @@ export const map = (arr, fn) => {
     if (isObject(arr)) {
         return Object.keys(arr).map((key) => {
             if (typeof fn === 'string')
-                return arr[key]?.[fn];
+                return get(arr[key], fn);
             return fn(arr[key], key, arr);
         });
     }
@@ -305,15 +326,17 @@ export function contains(arr, y) {
     return indexOf(arr, y) >= 0;
 }
 export function indexOf(obj, x, start = 0) {
+    if (obj == null)
+        return;
     const op = call(obj, 'indexOf', x, start);
     if (op != null)
         return op;
-    const length = obj?.length;
-    if (!length || start >= length)
-        return -1;
+    const length = obj.length;
     if (length && start < 0) {
         start = Math.max(start + length, 0);
     }
+    if (!length || start >= length)
+        return -1;
     for (; start < length; start++) {
         if (eq(x, obj[start]))
             return start;
@@ -321,14 +344,16 @@ export function indexOf(obj, x, start = 0) {
     return -1;
 }
 export function lastIndexOf(obj, x, start) {
+    if (obj == null)
+        return;
     const op = call(obj, 'lastIndexOf', x, start);
     if (op != null)
         return op;
-    const length = obj?.length;
-    if (!length)
-        return -1;
+    const length = obj.length;
     if (start == null)
         start = length - 1;
+    if (!length || start < 0)
+        return -1;
     for (; start >= 0; start--) {
         if (eq(x, obj[start]))
             return start;
@@ -338,7 +363,7 @@ export function lastIndexOf(obj, x, start) {
 /**
  * Creates a clone of the given `obj`. If `deep` is `true` it will clone it recursively.
  *
- * @export
+ *
  * @param {*} obj
  * @param {boolean} [deep=false]
  * @return The clone value
@@ -448,7 +473,7 @@ function baseMerge(obj, source, stack) {
         const srcValue = source[key];
         const objValue = obj[key];
         if (typeof srcValue === 'object' && srcValue !== null) {
-            baseMergeDeep(obj, source, key, stack ?? new WeakMap());
+            baseMergeDeep(obj, source, key, stack || new WeakMap());
         }
         else {
             if (objValue !== srcValue) {
@@ -462,7 +487,7 @@ function baseMerge(obj, source, stack) {
  *
  * Note: this method mutates `obj`
  *
- * @export
+ *
  * @param {Object} obj
  * @param {...Object} sources
  * @return {Object} The destination object.
@@ -516,7 +541,7 @@ export function* union(...args) {
 /**
  * Creates an object composed of keys generated from the results of running each element of `arr` thru `func`. The order of grouped values is determined by the order they occur in `arr`. The corresponding value of each key is an array of elements responsible for generating the key.
  *
- * @export
+ *
  * @param {(any[] | Object)} arr The collection to iterate over.
  * @param {(Iteratee | PropertyKey)} [func=id] The iteratee to transform keys.
  * @return {Object} Returns the composed aggregate object.

package/src/collections.ts

@@ -1,4 +1,3 @@
-/// <reference path='globals.d.ts'/>
 import {
   call,
   Function,
@@ -14,14 +13,15 @@ import {
   isString,
   Iteratee,
   keys,
-  NotImplementedError
+  NotImplementedError,
+  set
 } from './globals.js'
 import { comp, eq, id } from './operators.js'
 
 /**
  * A container type that provides contains().
  *
- * @export
+ *
  * @interface Container
  */
 export interface Container {
@@ -29,9 +29,9 @@ export interface Container {
 }
 
 /**
- * These are the "rich comparison" methods, as in Python.
+ * These are the "rich comparison" methods, inspired by Python operators.
+ *
  *
- * @export
  * @interface Comparable
  */
 export interface Comparable {
@@ -53,7 +53,7 @@ export interface Comparable {
  * A Collection is an iterable container type.
  * This is an abstract base class for user-defined collection types.
  *
- * @export
+ *
  * @abstract
  * @class Collection
  * @implements {Container}
@@ -122,7 +122,7 @@ export interface Reversible<T = unknown> {
 /**
  * A sequence is an iterable type with efficient index-based access.
  *
- * @export
+ *
  * @abstract
  * @class Sequence
  * @extends {Collection}
@@ -196,6 +196,14 @@ export abstract class Sequence<T> extends Collection implements Reversible<T> {
   }
 }
 
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
 export class FrozenSet<T = any> extends Set<T> {
   constructor(iterable: Iterable<T>) {
     super(iterable)
@@ -224,24 +232,36 @@ export class FrozenSet<T = any> extends Set<T> {
 
 export const compact = (...arr) => arr.filter((x) => !isEmpty(x))
 
+/**
+ * Creates a function that can be used to create named tuple-like objects.
+ * @example
+ * ```
+ * let Point = namedtuple('x', 'y', 'z')
+ * let userObj = User(0, 0, 0)
+ * // -> {x: 0, y: 0, z: 0}
+ * ```
+ *
+ *
+ * @param {...string[]} fields
+ * @return
+ */
 export function namedtuple(...fields: string[]) {
-  return (...args) => fields.map((f, i) => [f, args[i]])
+  return (...args) => fields.reduce((prev, f, i) => set(prev, f, args[i], false, true), {})
 }
 
 export function filter(arr, fn: Iteratee | PropertyKey | Object = isNull) {
   if (Array.isArray(arr)) {
     // @ts-expect-error function is not compatible?
     if (typeof fn === 'function') return arr.filter(fn)
-    if (typeof fn === 'string') return arr.filter((x) => x?.[fn])
+    if (typeof fn === 'string') return arr.filter((x) => get(x, fn))
     if (isObject(fn)) return arr.filter(matches(fn))
   }
 }
 
 export function find(arr, fn: Iteratee | PropertyKey | Object) {
   if (Array.isArray(arr)) {
-    // @ts-expect-error function is not compatible?
-    if (typeof fn === 'function') return arr.find(fn)
-    if (typeof fn === 'string') return arr.find((x) => x?.[fn])
+    if (typeof fn === 'function') return arr.find(fn as Iteratee)
+    if (typeof fn === 'string') return arr.find((x) => x && x[fn])
     if (isObject(fn)) return arr.find(matches(fn))
   }
 }
@@ -253,7 +273,7 @@ export function findRight(arr, fn: Iteratee | PropertyKey | Object) {
       if (typeof fn === 'function') {
         if (fn(x)) return x
       } else if (typeof fn === 'string') {
-        if (x?.[fn]) return x
+        if (x && x[fn]) return x
       } else if (isObject(fn)) {
         if (matches(fn)(x)) return x
       }
@@ -262,8 +282,9 @@ export function findRight(arr, fn: Iteratee | PropertyKey | Object) {
 }
 
 export const matches = (o) => (x) => {
+  if (!o || !x) return false
   for (const key in o) {
-    if (!eq(x?.[key], o[key])) return false
+    if (!eq(x[key], o[key])) return false
   }
   return true
 }
@@ -329,7 +350,7 @@ export const map = (arr, fn: Function | string) => {
   }
   if (isObject(arr)) {
     return Object.keys(arr).map((key) => {
-      if (typeof fn === 'string') return arr[key]?.[fn]
+      if (typeof fn === 'string') return get(arr[key], fn)
       return fn(arr[key], key, arr)
     })
   }
@@ -374,13 +395,14 @@ export function contains(arr, y) {
 }
 
 export function indexOf(obj, x, start = 0) {
+  if (obj == null) return
   const op = call(obj, 'indexOf', x, start)
   if (op != null) return op
-  const length = obj?.length
-  if (!length || start >= length) return -1
+  const length = obj.length
   if (length && start < 0) {
     start = Math.max(start + length, 0)
   }
+  if (!length || start >= length) return -1
   for (; start < length; start++) {
     if (eq(x, obj[start])) return start
   }
@@ -388,11 +410,12 @@ export function indexOf(obj, x, start = 0) {
 }
 
 export function lastIndexOf(obj, x, start?) {
+  if (obj == null) return
   const op = call(obj, 'lastIndexOf', x, start)
   if (op != null) return op
-  const length = obj?.length
-  if (!length) return -1
+  const length = obj.length
   if (start == null) start = length - 1
+  if (!length || start < 0) return -1
   for (; start >= 0; start--) {
     if (eq(x, obj[start])) return start
   }
@@ -402,7 +425,7 @@ export function lastIndexOf(obj, x, start?) {
 /**
  * Creates a clone of the given `obj`. If `deep` is `true` it will clone it recursively.
  *
- * @export
+ *
  * @param {*} obj
  * @param {boolean} [deep=false]
  * @return The clone value
@@ -512,7 +535,7 @@ function baseMerge(obj, source, stack?) {
     const srcValue = source[key]
     const objValue = obj[key]
     if (typeof srcValue === 'object' && srcValue !== null) {
-      baseMergeDeep(obj, source, key, stack ?? new WeakMap())
+      baseMergeDeep(obj, source, key, stack || new WeakMap())
     } else {
       if (objValue !== srcValue) {
         obj[key] = srcValue
@@ -526,7 +549,7 @@ function baseMerge(obj, source, stack?) {
  *
  * Note: this method mutates `obj`
  *
- * @export
+ *
  * @param {Object} obj
  * @param {...Object} sources
  * @return {Object} The destination object.
@@ -586,7 +609,7 @@ export function* union(...args) {
 /**
  * Creates an object composed of keys generated from the results of running each element of `arr` thru `func`. The order of grouped values is determined by the order they occur in `arr`. The corresponding value of each key is an array of elements responsible for generating the key.
  *
- * @export
+ *
  * @param {(any[] | Object)} arr The collection to iterate over.
  * @param {(Iteratee | PropertyKey)} [func=id] The iteratee to transform keys.
  * @return {Object} Returns the composed aggregate object.

package/{build → src}/functools.d.ts

@@ -7,7 +7,7 @@ export declare const compose: (...args: any[]) => (x: any) => any;
 /**
  * Creates a function that memoizes the result of `func`. If `resolver` is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function. By default, the first argument provided to the memoized function is used as the map cache key.
  *
- * @export
+ *
  * @param {Function} func The function to have its output memoized.
  * @param {Function} [resolver] The function to resolve the cache key.
  * @return {Function} Returns the new memoized function.
@@ -16,7 +16,7 @@ export declare function memoize(func: Function, resolver?: Function): Function;
 /**
  * Creates a debounced function that delays invoking `func` until after `wait` milliseconds have elapsed since the last time the debounced function was invoked. Subsequent calls to the debounced function return the result of the last successful invocation. Provide options to set the `maxWait` milliseconds, regardless of when the function was last invoked.
  *
- * @export
+ *
  * @param {Function} func The function to debounce.
  * @param {number} wait The number of milliseconds to delay.
  * @param {{ maxWait: number }} { maxWait } The maximum time `func` is allowed to be delayed before it's invoked.
@@ -28,7 +28,7 @@ export declare function debounce(func: Function, wait: number, { maxWait }: {
 /**
  * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds. Subsequent calls to the throttled function return the result of the last successful invocation.
  *
- * @export
+ *
  * @param {Function} func The function to throttle.
  * @param {number} time The number of milliseconds to throttle invocations to.
  * @return {Function} Returns the new throttled function.