atomic-fns 0.1.1 → 0.2.2

package/src/collections.ts

@@ -1,4 +1,7 @@
-/// <reference path='globals.d.ts'/>
+/**
+ * Collections
+ * @module
+ */
 import {
   call,
   Function,
@@ -14,14 +17,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 +33,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 +57,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 +126,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 +200,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,23 +236,35 @@ 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 === 'function') return arr.find(fn as Iteratee)
     if (typeof fn === 'string') return arr.find((x) => x?.[fn])
     if (isObject(fn)) return arr.find(matches(fn))
   }
@@ -262,8 +286,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 +354,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 +399,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 +414,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 +429,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 +539,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 +553,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 +613,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}/datetime.d.ts

@@ -1 +1,5 @@
+/**
+ * Date
+ * @module
+ */
 export declare const now: number;

package/src/datetime.js

@@ -0,0 +1,5 @@
+/**
+ * Date
+ * @module
+ */
+export const now = new Date().getTime()

package/src/datetime.ts

@@ -1 +1,6 @@
+/**
+ * Date
+ * @module
+ */
+
 export const now = new Date().getTime()

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

@@ -1,3 +1,7 @@
+/**
+ * FP
+ * @module
+ */
 import { Function } from './globals.js';
 export declare const bind: (fn: any, self: any, ...args: any[]) => any;
 export declare const partial: (fn: any, ...args: any[]) => any;
@@ -7,7 +11,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 +20,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 +32,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.

package/{build → src}/functools.js

@@ -1,79 +1,78 @@
-export const bind = (fn, self, ...args) => fn.bind(self, ...args);
-export const partial = (fn, ...args) => bind(fn, {}, ...args);
-export const flow = (...args) => (x) => {
+export const bind = (fn, self, ...args) => fn.bind(self, ...args)
+export const partial = (fn, ...args) => bind(fn, {}, ...args)
+export const flow =
+  (...args) =>
+  (x) => {
     for (const fn of args) {
-        x = fn(x);
+      x = fn(x)
     }
-    return x;
-};
-export const pipe = flow;
-export const compose = (...args) => flow(args.reverse());
+    return x
+  }
+export const pipe = flow
+export const compose = (...args) => flow(args.reverse())
 /**
  * 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.
  */
 export function memoize(func, resolver) {
-    const cache = new Map();
-    return (...args) => {
-        const key = resolver ? resolver(...args) : args[0];
-        const prev = cache.get(key);
-        if (prev !== undefined)
-            return prev;
-        const value = func(...args);
-        cache.set(key, value);
-        return value;
-    };
+  const cache = new Map()
+  return (...args) => {
+    const key = resolver ? resolver(...args) : args[0]
+    const prev = cache.get(key)
+    if (prev !== undefined) return prev
+    const value = func(...args)
+    cache.set(key, value)
+    return value
+  }
 }
 /**
  * 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.
  * @return {Function} Returns the new debounced function.
  */
 export function debounce(func, wait, { maxWait }) {
-    let timer, maxTimer, lastResult;
-    return (...args) => {
-        if (timer)
-            clearTimeout(timer);
-        timer = setTimeout(() => {
-            clearTimeout(maxTimer);
-            maxTimer = null;
-            lastResult = func(...args);
-        }, wait);
-        if (maxWait && !maxTimer) {
-            maxTimer = setTimeout(() => {
-                clearTimeout(timer);
-                maxTimer = null;
-                lastResult = func(...args);
-            }, maxWait);
-        }
-        return lastResult;
-    };
+  let timer, maxTimer, lastResult
+  return (...args) => {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      clearTimeout(maxTimer)
+      maxTimer = null
+      lastResult = func(...args)
+    }, wait)
+    if (maxWait && !maxTimer) {
+      maxTimer = setTimeout(() => {
+        clearTimeout(timer)
+        maxTimer = null
+        lastResult = func(...args)
+      }, maxWait)
+    }
+    return lastResult
+  }
 }
 /**
  * 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.
  */
 export function throttle(func, time) {
-    let pending = false;
-    return (...args) => {
-        if (pending)
-            return;
-        func(...args);
-        pending = true;
-        setTimeout(() => {
-            pending = false;
-        }, time);
-    };
+  let pending = false
+  return (...args) => {
+    if (pending) return
+    func(...args)
+    pending = true
+    setTimeout(() => {
+      pending = false
+    }, time)
+  }
 }

package/src/functools.ts

@@ -1,3 +1,7 @@
+/**
+ * FP
+ * @module
+ */
 import { Function } from './globals.js'
 
 export const bind = (fn, self, ...args) => fn.bind(self, ...args)
@@ -20,7 +24,7 @@ export const compose = (...args) => flow(args.reverse())
 /**
  * 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.
@@ -40,7 +44,7 @@ export 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.
@@ -71,7 +75,7 @@ export function debounce(func: Function, wait: number, { maxWait }: { maxWait: n
 /**
  * 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.

package/src/globals.d.ts

@@ -1,5 +1,179 @@
-interface ErrorConstructor {
-  /** See https://v8.dev/docs/stack-trace-api#stack-trace-collection-for-custom-exceptions. */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  captureStackTrace(error: Object, constructor?: Function): void
+/**
+ * Globals
+ * @module
+ */
+export declare type Comp = (x: any, y: any) => number;
+export declare type Function = (...args: any[]) => any;
+export declare type Iteratee = (value: any, key?: any, arr?: any) => any;
+export declare const True: () => boolean;
+export declare const False: () => boolean;
+/**
+ * A custom error class that inherits from the Error object.
+ *
+ *
+ * @class CustomError
+ * @extends {Error}
+ */
+export declare class CustomError extends Error {
+    /**
+     * Returns a new CustomError with the specified message.
+     * @param {string} message
+     * @constructor
+     */
+    constructor(message?: string);
 }
+/**
+ * Custom error to signal an invalid index access.
+ * @extends {CustomError}
+ */
+export declare class IndexError extends CustomError {
+}
+/**
+ * Raised when a system function returns an I/O failure such as "file not found"
+ * or "disk full".
+ * @extends {CustomError}
+ */
+export declare class IOError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid key access.
+ * @extends {CustomError}
+ */
+export declare class KeyError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid operation.
+ * @extends {CustomError}
+ */
+export declare class NotImplementedError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid value.
+ * @extends {CustomError}
+ */
+export declare class ValueError extends CustomError {
+}
+/**
+ * Raised when the second argument of a division or modulo operation is zero.
+ * @extends {CustomError}
+ */
+export declare class ZeroDivisionError extends CustomError {
+}
+/**
+ * Returns the true type of any value with correct detection for null, Array,
+ * Object, Promise, Symbol, and NaN.
+ *
+ *
+ * @param {*} value
+ * @return
+ */
+export declare function type(value: any): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "array" | "promise" | "null" | "NaN";
+/** Same as `x.toString()`. Returns `''` when x is null or undefined */
+export declare const str: (x: any) => any;
+/** Check if value is a boolean type */
+export declare const isBool: (x: any) => boolean;
+/** Check if value is an object type */
+export declare const isObject: (x: any) => boolean;
+/** Check if value is a string type */
+export declare const isString: (x: any) => boolean;
+/** Check if value is an Array type */
+export declare const isArray: (x: any) => boolean;
+/** Check if value is Array-like type.
+ * A value is considered array-like if it's not a function and has a
+ * `.length` number property.
+ */
+export declare const isArrayLike: (x: any) => boolean;
+/** Check if value is a function type */
+export declare const isFunc: (x: any) => boolean;
+/** Check if value is a number type */
+export declare const isNumber: (x: any) => boolean;
+/** Check if value is a Bigint type */
+export declare const isBigint: (x: any) => boolean;
+/** Check if value is NaN based on `Number.isNaN` */
+export declare const isNaN: (x: any) => boolean;
+/** Check if value is a Promise type */
+export declare const isPromise: (x: any) => boolean;
+/** Check if value is an async function type */
+export declare const isAsync: (x: any) => boolean;
+/** Check if value is a generator function type */
+export declare const isGenerator: (x: any) => boolean;
+/** Check if value is null or undefined */
+export declare const isNull: (x: any) => boolean;
+/** Check if value is not null or undefined */
+export declare const notNull: (x: any) => boolean;
+export declare function len(x: any): any;
+/** Returns true for objects without length or falsey values. */
+export declare const isEmpty: (x: any) => boolean;
+/** Check if value is a Symbol type */
+export declare const isSymbol: (x: any) => boolean;
+/**
+ * Generates a unique ID using random numbers.
+ * If prefix is given, the ID is appended to it
+ */
+export declare const uniqueId: (pre?: string) => any;
+/**
+ * Checks if `obj.key` is a function, and calls it with any `args`.
+ *
+ *
+ * @param {*} obj
+ * @param {PropertyKey} key
+ * @param {...any[]} args
+ * @return `obj.key(...args)`
+ */
+export declare function call(obj: any, key: PropertyKey, ...args: any[]): any;
+/** Convert number to unicode character */
+export declare const chr: (x: number) => string;
+/** Convert character to Unicode code point */
+export declare const ord: (x: string) => number;
+/** `Object.keys(x)` */
+export declare const keys: (x: any) => string[];
+/** `Object.values(x)` */
+export declare const values: (x: any) => unknown[];
+/**
+ * Round `x` to the number of digits after the decimal point. If `digits` is
+ * omitted, it returns the nearest integer to x.
+ *
+ * @param {number} x
+ * @param {number} [digits=0]
+ */
+export declare function round(x: number, digits?: number): number;
+export declare const floor: (x: number) => number;
+export declare const ceil: (x: number) => number;
+/**
+ * Yields elements like `[index, item]` from an iterable.
+ *
+ *
+ * @template T
+ * @param {Iterable<T>} iterable
+ */
+export declare function enumerate<T = unknown>(iterable: Iterable<T>): Generator<(number | T)[], void, unknown>;
+export declare const has: (obj: any, attr: PropertyKey) => any;
+/**
+ * Check if the attribute is present in the object, or return optional default.
+ *
+ *
+ * @param {*} obj
+ * @param {PropertyKey} key
+ * @param {*} [value=undefined]
+ * @return The property value or default value
+ */
+export declare function get(obj: any, key: PropertyKey | PropertyKey[], value?: any): any;
+export declare function del(x: any, attr: any): any;
+export declare function set(self: any, attr: PropertyKey, value: any, writable?: boolean, enumerable?: boolean): any;
+export declare const HASH_KEY: unique symbol;
+export declare function hash(obj: any): any;
+/**
+ * A hash value generator for strings
+ *
+ * @param {string} str
+ * @return {number}
+ * @see http://isthe.com/chongo/tech/comp/fnv/
+ */
+export declare function hashCode(str: string): number;
+export declare const bin: (n: number) => string;
+export declare const hex: (n: number) => string;
+export declare const oct: (n: number) => string;
+export declare const float: (x: any) => number;
+export declare const int: (x: any, base?: number) => number;
+export declare const list: (arr?: any) => unknown[];
+export declare const next: (iter: Iterator<unknown>) => any;