atomic-fns 0.1.0 → 0.2.0

package/src/random.ts

@@ -1,23 +1,42 @@
 import { isObject, round } from './globals'
 
+/** Returns a random float between a [min, max) value (max exclusive). */
 export const random = (min = 0, max = 1) => Math.random() * (max - min) + min
 
-export const randomInt = (min = 0, max = 1) => round(random(min, max), 0)
+/** Returns a random integer between a [min, max] value (inclusive). */
+export const randomInt = (min = 0, max = 1) => Math.round(random(min, max))
 
+/** Returns the item at some random index in a sequence. */
 export const choice = (arr: any[]) => {
-  if (!arr?.length) return
-  const index = randomInt(0, arr.length - 1)
-  return arr[index]
+  if (!arr || !arr.length) return
+  return arr[randomInt(0, arr.length - 1)]
 }
 
+/**
+ * Returns a random sample of size k from a list of items.
+ *
+ * @export
+ * @param {any[]} arr
+ * @param {number} k
+ * @return
+ */
 export function sample(arr: any[], k: number) {
-  if (!arr?.length) return
-  const result: any[] = []
-  while (k--) result.push(choice(arr))
+  if (!arr || !arr.length || arr.length < k) return
+  const result: typeof arr = []
+  for (let i = 0; i < k; i++) {
+    result.push(choice(arr))
+  }
   return result
 }
 
+/**
+ * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
+ *
+ * @param {*} arr
+ * @return
+ */
 export function shuffle(arr) {
+  if (!arr || !arr.length) return
   if (isObject(arr)) arr = Object.values(arr)
   const n = arr.length - 1
   for (let i = n; i > 0; i--) {
@@ -26,4 +45,5 @@ export function shuffle(arr) {
     arr[j] = arr[i]
     arr[i] = temp
   }
+  return arr
 }

package/tests/globals.spec.ts

@@ -26,6 +26,7 @@ import {
   values,
   round,
   enumerate,
+  isEmpty,
   isGenerator,
   hash,
   hashCode,
@@ -36,8 +37,7 @@ import {
   list,
   next,
   get
-} from '../build/globals.js'
-import { isEmpty } from '../src/globals.js'
+} from '../src/globals.js'
 
 function cb() {}
 
@@ -109,6 +109,8 @@ describe('globals', () => {
   it('str', () => {
     assert(str(undefined) === '')
     assert(str(null) === '')
+    assert(str(true) === 'true')
+    assert(str(false) === 'false')
     assert(str(NaN) === 'NaN')
     assert(str(42) === '42')
     assert(str([]) === '')
@@ -119,7 +121,9 @@ describe('globals', () => {
   it('uniqueId', () => {
     const uid = uniqueId()
     assert(isNumber(uid))
-    assert.match(uniqueId('contact_'), /^contact_\d+/)
+    let prefix = 'user_'
+    const userId = uniqueId('user_')
+    assert(userId.startsWith('user_'))
   })
 
   it('call', () => {

package/tsconfig.json

@@ -47,7 +47,7 @@
     // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
     // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
     // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
-    "outDir": "./build", /* Specify an output folder for all emitted files. */
+    // "outDir": "./build", /* Specify an output folder for all emitted files. */
     // "removeComments": true,                           /* Disable emitting comments. */
     // "noEmit": true,                                   /* Disable emitting files from a compilation. */
     // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
@@ -99,5 +99,11 @@
     {
       "path": "./tsconfig.node.json"
     }
-  ]
+  ],
+  "typedocOptions": {
+    "entryPoints": [
+      "src/index.ts"
+    ],
+    "out": "docs"
+  }
 }

package/build/globals.d.ts

@@ -1,175 +0,0 @@
-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.
- *
- * @export
- * @class CustomError
- * @extends {Error}
- */
-export declare class CustomError extends Error {
-    /**
-     * Returns a new CustomError with the specified message.
-     * @param message
-     * @constructor
-     */
-    constructor(message?: any);
-}
-/**
- * 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.
- *
- * @export
- * @param {*} value
- * @return
- */
-export declare function type(value: any): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "array" | "promise" | "null" | "NaN";
-/** Same as calling toString() */
-export declare const str: (x: any) => string;
-/** 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`.
- *
- * @export
- * @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.
- * @export
- * @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.
- *
- * @export
- * @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.
- *
- * @export
- * @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
- * @export
- * @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;

package/build/random.d.ts

@@ -1,5 +0,0 @@
-export declare const random: (min?: number, max?: number) => number;
-export declare const randomInt: (min?: number, max?: number) => number;
-export declare const choice: (arr: any[]) => any;
-export declare function sample(arr: any[], k: number): any[] | undefined;
-export declare function shuffle(arr: any): void;

package/build/random.js

@@ -1,28 +0,0 @@
-import { isObject, round } from './globals';
-export const random = (min = 0, max = 1) => Math.random() * (max - min) + min;
-export const randomInt = (min = 0, max = 1) => round(random(min, max), 0);
-export const choice = (arr) => {
-    if (!arr?.length)
-        return;
-    const index = randomInt(0, arr.length - 1);
-    return arr[index];
-};
-export function sample(arr, k) {
-    if (!arr?.length)
-        return;
-    const result = [];
-    while (k--)
-        result.push(choice(arr));
-    return result;
-}
-export function shuffle(arr) {
-    if (isObject(arr))
-        arr = Object.values(arr);
-    const n = arr.length - 1;
-    for (let i = n; i > 0; i--) {
-        const j = randomInt(0, i);
-        const temp = arr[j];
-        arr[j] = arr[i];
-        arr[i] = temp;
-    }
-}