atomic-fns 0.3.1 → 0.3.3-beta

package/{src → core}/collections/index.ts

@@ -21,231 +21,24 @@ import {
   isSymbol,
   Iteratee,
   keys,
-  NotImplementedError,
   set
 } from '../globals/index.js'
 import { enumerate } from '../itertools/index.js'
-import { comp, eq, id } from '../operators/index.js'
+import { compare, eq, id } from '../operators/index.js'
+
+export * from './abc.js'
+export * from './BTree.js'
+export * from './deque.js'
+export * from './frozenset.js'
+export * from './Heap.js'
+export * from './LRUCache.js'
+export * from './SortedSet.js'
+export * from './SortedMap.js'
+export * from './SortedTree.js'
+export * from './SplayTree.js'
 
 /**
- * A container type that provides contains().
- *
- *
- * @interface Container
- */
-export interface Container {
-  contains: (x) => boolean
-}
-
-/**
- * These are the "rich comparison" methods, inspired by Python operators.
- *
- *
- * @interface Comparable
- */
-export interface Comparable {
-  /** x < y: calls this.lt(other) reflection. */
-  lt?: (other) => boolean
-  /** x ≤ y: calls this.le(other) reflection. */
-  le?: (other) => boolean
-  /** x == y: calls this.eq(other) reflection. */
-  eq: (other) => boolean
-  /** x != y: calls this.ne(other) reflection. */
-  ne: (other) => boolean
-  /** x > y: calls this.gt(other) reflection. */
-  gt?: (other) => boolean
-  /** x ≥ y: calls this.ge(other) reflection. */
-  ge?: (other) => boolean
-}
-
-/**
- * A `Collection` is an iterable {@link Container} type.
- * This is an abstract base class for user-defined collection types.
- *
- *
- * @abstract
- * @class Collection
- * @implements {Container}
- */
-export abstract class Collection implements Container {
-  /**
-   * Returns an iterator for the container items
-   * @return {Iterator}
-   */
-  [Symbol.iterator]() {
-    return this
-  }
-
-  /**
-   * Implements the iterator protocol and returns the next item in the iterable.
-   */
-  next() {}
-
-  /**
-   * Adds a new item to the container.
-   * @param item - The item to add to the collection.
-   */
-  add(item) {}
-
-  /**
-   * Checks if item is present in the container.
-   * @param item - The item to search for in the collection.
-   * @returns `true` when the element is found, else `false`
-   */
-  contains(item) {
-    return false
-  }
-
-  /**
-   * Returns the total number of elements in the container.
-   */
-  size(): number {
-    throw new NotImplementedError()
-  }
-
-  /**
-   * Remove the first item from the container where `item == x`
-   * @returns `true` when the element is found and removed, else `false`
-   */
-  remove(x) {
-    return false
-  }
-
-  /**
-   * Retrieve and remove the item at index `i`.
-   * @returns the item or undefined if not found.
-   */
-  pop(i) {}
-
-  /**
-   * Remove all items from the container
-   */
-  clear() {}
-}
-
-/**
- * Implements an iterable that allows backward iteration.
- * @interface Reversible
- */
-export interface Reversible<T = unknown> {
-  reversed: () => Iterator<T>
-}
-
-/**
- * A sequence is an iterable {@link Collection} type with efficient index-based access.
- * @abstract
- * @class Sequence
- * @extends {Collection}
- * @template T
- */
-export abstract class Sequence<T> extends Collection implements Reversible<T> {
-  /**
-   * Return the item at the given key or index
-   * @param {*} key
-   * @memberof Sequence
-   */
-  get(key): T | undefined {
-    throw new NotImplementedError()
-  }
-
-  /**
-   * Set a new value at the given key or index
-   *
-   * @param {*} key
-   * @param {T} val
-   * @memberof Sequence
-   */
-  set(key, val: T) {
-    throw new NotImplementedError()
-  }
-
-  /**
-   * Deletes the given key or index, and its value.
-   * Raises ValueError if not key is found.
-   *
-   * @param {*} key
-   * @memberof Sequence
-   */
-  delete(key) {
-    throw new NotImplementedError()
-  }
-
-  /**
-   * Adds a new item to the end of the sequence.
-   *
-   * @param {T} x
-   * @memberof Sequence
-   */
-  append(x: T) {}
-
-  /**
-   * Append all the items to the sequence.
-   *
-   * @param {Iterable<T>} iter
-   * @memberof Sequence
-   */
-  extend(iter: Iterable<T>) {}
-
-  /**
-   * Return the index of x in the sequence, or undefined if not found.
-   *
-   * @param {T} item
-   * @return {(number | undefined)}
-   * @memberof Sequence
-   */
-  indexOf(item: T): number | undefined {
-    throw new NotImplementedError()
-  }
-
-  size() {
-    return 0
-  }
-
-  reversed(): Iterator<T> {
-    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<T = any> extends Set<T> {
-  constructor(iterable: Iterable<T>) {
-    super(iterable)
-    return this.freeze()
-  }
-
-  /** @private */
-  add() {
-    throw TypeError('FrozenSet cannot be modified.')
-    return this // eslint-disable-line
-  }
-
-  /** @private */
-  delete() {
-    throw TypeError('FrozenSet cannot be modified.')
-    return false // eslint-disable-line
-  }
-
-  /** @private */
-  clear() {
-    throw TypeError('FrozenSet cannot be modified.')
-    return this // eslint-disable-line
-  }
-
-  /** @private */
-  freeze() {
-    return Object.freeze(this)
-  }
-}
-
-/**
- * Creates a new array with all `falsey` and empty values removed.
+ * Creates a new array with all falsy and empty values removed.
  * @param arr The array to compact
  * @returns A new array with the filtered values.
  * @example
@@ -387,6 +180,22 @@ export function findRight(arr, fn: Iteratee | PropertyKey | Object) {
   }
 }
 
+/**
+ * Performs an efficient array insert operation in the given array. If the index or the array is invalid, it just returns the given array.
+ *
+ * **Note:** Uses the same behavior as `Array.splice`.
+ *
+ * @param {Array<*>} arr The given array to insert into
+ * @param {number} index The index of the array insert operation.
+ * @param {*} value The value to insert in the array at the given `index`.
+ * @returns {Array<*>} The given array.
+ */
+export function insert(arr: any[], index: number, value) {
+  if (!arr || arr.length <= index || index < 0) return arr
+  arr.splice(index, 0, value)
+  return arr
+}
+
 /**
  * Creates a function that performs a partial deep comparison between a given object and `shape`, returning `true` if the given object has equivalent property values, else `false`.
  * @example
@@ -942,7 +751,7 @@ uniq([2, 1, 2])
  */
 export function sortedUniq(arr, fn: string | Iteratee = id) {
   const values = uniq(arr, fn)
-  values.sort(comp)
+  values.sort(compare)
   return values
 }
 
@@ -1140,7 +949,7 @@ export function* union(...args: Array<Iterable<any>>) {
  *
  * @param arr The collection to iterate over.
  * @param [func=id] The iteratee to transform keys.
- * @returns Returns the composed aggregate object.
+ * @returns Returns the aggregated object.
  *
  * @example
 ```js
@@ -1164,6 +973,39 @@ export function groupBy(arr: Iterable<any> | Object, func: Iteratee | PropertyKe
   return results
 }
 
+/**
+ * Similar to {@link groupBy} but it returns a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map Map} object with the results.
+ *
+ * @param arr The collection to iterate over.
+ * @param {Function | PropertyKey} [func=id] The iteratee to transform keys.
+ * @returns {Map} Returns the aggregated map object.
+ * @template K, V
+ *
+ * @example
+```js
+groupByMap([6.1, 4.2, 6.3], Math.floor)
+// => Map { 4: [4.2], 6: [6.1, 6.3] }
+
+// The `property` iteratee shorthand.
+groupByMap(['one', 'two', 'three'], 'length')
+// => Map { 3: ['one', 'two'], 5: ['three'] }
+```
+ */
+export function groupByMap<K = any, V = any>(
+  arr: Iterable<any> | Object,
+  func: Iteratee | PropertyKey = id
+): Map<K, V[]> {
+  const results = new Map<K, V[]>()
+  const useKey = typeof func === 'function' ? func : partial(get, func)
+  forEach(arr, (value: V) => {
+    const groupKey = useKey(value)
+    const values = results.get(groupKey) || []
+    values.push(value)
+    results.set(groupKey, values)
+  })
+  return results
+}
+
 /**
  * Removes all elements from array that `func` returns truthy for and returns an array of the removed elements.
  * @param arr The array to remove from.
@@ -1179,8 +1021,4 @@ export function remove<T>(arr: T[], func: any) {
 }
 
 // TODO: binary search utils
-// TODO: heap/heapify
-// TODO: deque
 // TODO: Counter
-// TODO: Skip list
-// TODO: BST (BTree)

package/core/collections/test.html

@@ -0,0 +1,10 @@
+<script type="module">
+  import { SplayTree } from 'https://unpkg.com/atomic-fns/core/collections'
+  let tree = new SplayTree()
+
+  for (let i = 20; i > 0; i -= 2) {
+    tree.set(i, i)
+  }
+
+  console.log(tree)
+</script>

package/core/collections/typedArrays.d.ts

@@ -0,0 +1,31 @@
+export declare function getPointerArray(size: any): Uint8ArrayConstructor | Uint16ArrayConstructor | Uint32ArrayConstructor;
+export declare function getSignedPointerArray(size: any): Int8ArrayConstructor | Int16ArrayConstructor | Int32ArrayConstructor | Float64ArrayConstructor;
+/**
+ * Function returning the minimal type able to represent the given number.
+ *
+ * @param  {number} value - Value to test.
+ * @return {TypedArrayClass}
+ */
+export declare function getNumberType(value: any): Uint8ArrayConstructor | Uint16ArrayConstructor | Uint32ArrayConstructor | Int8ArrayConstructor | Int16ArrayConstructor | Int32ArrayConstructor | Float64ArrayConstructor;
+export declare function getMinimalRepresentation(array: any, getter: any): null;
+/**
+ * Function returning whether the given value is a typed array.
+ *
+ * @param  {any} value - Value to test.
+ * @return {boolean}
+ */
+export declare function isTypedArray(value: any): boolean;
+/**
+ * Function used to concat byte arrays.
+ *
+ * @param  {...ByteArray}
+ * @return {ByteArray}
+ */
+export declare function concat(): any;
+/**
+ * Function used to initialize a byte array of indices.
+ *
+ * @param  {number}    length - Length of target.
+ * @return {ByteArray}
+ */
+export declare function indices(length: any): any;

package/core/collections/typedArrays.js

@@ -0,0 +1,143 @@
+/**
+ * When using an unsigned integer array to store pointers, one might want to
+ * choose the optimal word size in regards to the actual numbers of pointers
+ * to store.
+ *
+ * This helpers does just that.
+ *
+ * @param  {number} size - Expected size of the array to map.
+ * @return {TypedArray}
+ */
+const MAX_8BIT_INTEGER = Math.pow(2, 8) - 1;
+const MAX_16BIT_INTEGER = Math.pow(2, 16) - 1;
+const MAX_32BIT_INTEGER = Math.pow(2, 32) - 1;
+const MAX_SIGNED_8BIT_INTEGER = Math.pow(2, 7) - 1;
+const MAX_SIGNED_16BIT_INTEGER = Math.pow(2, 15) - 1;
+const MAX_SIGNED_32BIT_INTEGER = Math.pow(2, 31) - 1;
+export function getPointerArray(size) {
+    const maxIndex = size - 1;
+    if (maxIndex <= MAX_8BIT_INTEGER)
+        return Uint8Array;
+    if (maxIndex <= MAX_16BIT_INTEGER)
+        return Uint16Array;
+    // if (maxIndex <= MAX_32BIT_INTEGER) return Uint32Array
+    return Uint32Array;
+}
+export function getSignedPointerArray(size) {
+    const maxIndex = size - 1;
+    if (maxIndex <= MAX_SIGNED_8BIT_INTEGER)
+        return Int8Array;
+    if (maxIndex <= MAX_SIGNED_16BIT_INTEGER)
+        return Int16Array;
+    if (maxIndex <= MAX_SIGNED_32BIT_INTEGER)
+        return Int32Array;
+    return Float64Array;
+}
+/**
+ * Function returning the minimal type able to represent the given number.
+ *
+ * @param  {number} value - Value to test.
+ * @return {TypedArrayClass}
+ */
+export function getNumberType(value) {
+    // <= 32 bits itnteger?
+    if (value === (value | 0)) {
+        // Negative
+        if (Math.sign(value) === -1) {
+            if (value <= 127 && value >= -128)
+                return Int8Array;
+            if (value <= 32767 && value >= -32768)
+                return Int16Array;
+            return Int32Array;
+        }
+        else {
+            if (value <= 255)
+                return Uint8Array;
+            if (value <= 65535)
+                return Uint16Array;
+            return Uint32Array;
+        }
+    }
+    // 53 bits integer & floats
+    // NOTE: it's kinda hard to tell whether we could use 32bits or not...
+    return Float64Array;
+}
+/**
+ * Function returning the minimal type able to represent the given array
+ * of JavaScript numbers.
+ *
+ * @param  {array}    array  - Array to represent.
+ * @param  {function} getter - Optional getter.
+ * @return {TypedArrayClass}
+ */
+const TYPE_PRIORITY = {
+    Uint8Array: 1,
+    Int8Array: 2,
+    Uint16Array: 3,
+    Int16Array: 4,
+    Uint32Array: 5,
+    Int32Array: 6,
+    Float32Array: 7,
+    Float64Array: 8
+};
+export function getMinimalRepresentation(array, getter) {
+    let maxType = null;
+    let maxPriority = 0;
+    let p;
+    let t;
+    let v;
+    let i;
+    let l;
+    for (i = 0, l = array.length; i < l; i++) {
+        v = getter ? getter(array[i]) : array[i];
+        t = exports.getNumberType(v);
+        p = TYPE_PRIORITY[t.name];
+        if (p > maxPriority) {
+            maxPriority = p;
+            maxType = t;
+        }
+    }
+    return maxType;
+}
+/**
+ * Function returning whether the given value is a typed array.
+ *
+ * @param  {any} value - Value to test.
+ * @return {boolean}
+ */
+export function isTypedArray(value) {
+    return ArrayBuffer.isView(value);
+}
+/**
+ * Function used to concat byte arrays.
+ *
+ * @param  {...ByteArray}
+ * @return {ByteArray}
+ */
+export function concat() {
+    let length = 0;
+    let i;
+    let o;
+    let l;
+    for (i = 0, l = arguments.length; i < l; i++)
+        length += arguments[i].length;
+    const array = new arguments[0].constructor(length);
+    for (i = 0, o = 0; i < l; i++) {
+        array.set(arguments[i], o);
+        o += arguments[i].length;
+    }
+    return array;
+}
+/**
+ * Function used to initialize a byte array of indices.
+ *
+ * @param  {number}    length - Length of target.
+ * @return {ByteArray}
+ */
+export function indices(length) {
+    const PointerArray = exports.getPointerArray(length);
+    const array = new PointerArray(length);
+    for (let i = 0; i < length; i++)
+        array[i] = i;
+    return array;
+}

package/core/collections/typedArrays.ts

@@ -0,0 +1,163 @@
+/**
+ * When using an unsigned integer array to store pointers, one might want to
+ * choose the optimal word size in regards to the actual numbers of pointers
+ * to store.
+ *
+ * This helpers does just that.
+ *
+ * @param  {number} size - Expected size of the array to map.
+ * @return {TypedArray}
+ */
+const MAX_8BIT_INTEGER = Math.pow(2, 8) - 1
+const MAX_16BIT_INTEGER = Math.pow(2, 16) - 1
+const MAX_32BIT_INTEGER = Math.pow(2, 32) - 1
+
+const MAX_SIGNED_8BIT_INTEGER = Math.pow(2, 7) - 1
+const MAX_SIGNED_16BIT_INTEGER = Math.pow(2, 15) - 1
+const MAX_SIGNED_32BIT_INTEGER = Math.pow(2, 31) - 1
+
+export function getPointerArray(size) {
+  const maxIndex = size - 1
+
+  if (maxIndex <= MAX_8BIT_INTEGER) return Uint8Array
+
+  if (maxIndex <= MAX_16BIT_INTEGER) return Uint16Array
+
+  // if (maxIndex <= MAX_32BIT_INTEGER) return Uint32Array
+
+  return Uint32Array
+}
+
+export function getSignedPointerArray(size) {
+  const maxIndex = size - 1
+
+  if (maxIndex <= MAX_SIGNED_8BIT_INTEGER) return Int8Array
+
+  if (maxIndex <= MAX_SIGNED_16BIT_INTEGER) return Int16Array
+
+  if (maxIndex <= MAX_SIGNED_32BIT_INTEGER) return Int32Array
+
+  return Float64Array
+}
+
+/**
+ * Function returning the minimal type able to represent the given number.
+ *
+ * @param  {number} value - Value to test.
+ * @return {TypedArrayClass}
+ */
+export function getNumberType(value) {
+  // <= 32 bits itnteger?
+  if (value === (value | 0)) {
+    // Negative
+    if (Math.sign(value) === -1) {
+      if (value <= 127 && value >= -128) return Int8Array
+
+      if (value <= 32767 && value >= -32768) return Int16Array
+
+      return Int32Array
+    } else {
+      if (value <= 255) return Uint8Array
+
+      if (value <= 65535) return Uint16Array
+
+      return Uint32Array
+    }
+  }
+
+  // 53 bits integer & floats
+  // NOTE: it's kinda hard to tell whether we could use 32bits or not...
+  return Float64Array
+}
+
+/**
+ * Function returning the minimal type able to represent the given array
+ * of JavaScript numbers.
+ *
+ * @param  {array}    array  - Array to represent.
+ * @param  {function} getter - Optional getter.
+ * @return {TypedArrayClass}
+ */
+const TYPE_PRIORITY = {
+  Uint8Array: 1,
+  Int8Array: 2,
+  Uint16Array: 3,
+  Int16Array: 4,
+  Uint32Array: 5,
+  Int32Array: 6,
+  Float32Array: 7,
+  Float64Array: 8
+}
+
+export function getMinimalRepresentation(array, getter) {
+  let maxType = null
+  let maxPriority = 0
+  let p
+  let t
+  let v
+  let i
+  let l
+
+  for (i = 0, l = array.length; i < l; i++) {
+    v = getter ? getter(array[i]) : array[i]
+    t = exports.getNumberType(v)
+    p = TYPE_PRIORITY[t.name]
+
+    if (p > maxPriority) {
+      maxPriority = p
+      maxType = t
+    }
+  }
+
+  return maxType
+}
+
+/**
+ * Function returning whether the given value is a typed array.
+ *
+ * @param  {any} value - Value to test.
+ * @return {boolean}
+ */
+export function isTypedArray(value) {
+  return ArrayBuffer.isView(value)
+}
+
+/**
+ * Function used to concat byte arrays.
+ *
+ * @param  {...ByteArray}
+ * @return {ByteArray}
+ */
+export function concat() {
+  let length = 0
+  let i
+  let o
+  let l
+
+  for (i = 0, l = arguments.length; i < l; i++) length += arguments[i].length
+
+  const array = new arguments[0].constructor(length)
+
+  for (i = 0, o = 0; i < l; i++) {
+    array.set(arguments[i], o)
+    o += arguments[i].length
+  }
+
+  return array
+}
+
+/**
+ * Function used to initialize a byte array of indices.
+ *
+ * @param  {number}    length - Length of target.
+ * @return {ByteArray}
+ */
+export function indices(length) {
+  const PointerArray = exports.getPointerArray(length)
+
+  const array = new PointerArray(length)
+
+  for (let i = 0; i < length; i++) array[i] = i
+
+  return array
+}

package/{src → core}/functools/index.d.ts

@@ -88,7 +88,7 @@ export declare function once(func: Function): (...args: any[]) => any;
 export declare type Maybe<T> = T | undefined;
 export declare type Result<T, E = any> = [Maybe<T>, Maybe<E>];
 /**
- * Wraps a function to catch any exceptions inside and return a `go` style error-return type.
+ * Wraps a function to catch any exceptions inside and return a `go` style error-return type {@link Result}.
  *
  * @param {Function} fun The function to wrap and catch if it throws.
  * @param {?function(err: E, res: T): *} [onFinally] Optional callback that will be called on the `finally` clause if given.
@@ -101,7 +101,7 @@ export declare function result<T = any, E = unknown>(fun: Function<T>, onFinally
  *
  * @param {Function|Promise} awaitable The function or promise to await.
  * @param {?function(err: E, res: T): *} [onFinally] Optional callback that will be called on the `finally` clause if given.
- * @returns {Function} A new function that awaits the `awaitable` param and returns a return type.
+ * @returns {Function} A new function that awaits the `awaitable` param and returns a {@link Result} type.
  * @template T,E
  */
 export declare function resultAsync<T = any, E = unknown>(awaitable: Promise<T> | Function<Promise<T>>, onFinally?: (err: E, res: T) => any): (...args: any[]) => Promise<Result<T, E>>;