@bitblit/ratchet-common 6.0.146-alpha → 6.0.148-alpha

package/src/lang/promise-ratchet.spec.ts

@@ -0,0 +1,104 @@
+import { PromiseRatchet } from './promise-ratchet.js';
+import { Logger } from '../logger/logger.js';
+import { TimeoutToken } from './timeout-token.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+import { describe, expect, test } from 'vitest';
+
+const fnFalse = (_ignored) => {
+  return false;
+};
+const fnOn3 = (t) => {
+  Logger.info('t=%d', t);
+  return t == 3;
+};
+const waitAndPrint = async (t1: number, t2: string) => {
+  Logger.info('Running: %s', t2);
+  await PromiseRatchet.wait(t1 * 2);
+  return t1 * 2;
+};
+
+describe('#promiseRatchet', function () {
+  test('should timeout eventually', async () => {
+    try {
+      Logger.setLevel(LoggerLevelName.silly);
+      const result: boolean | TimeoutToken = await PromiseRatchet.waitFor(fnFalse, true, 100, 2);
+      Logger.info('Got : %s', result);
+      expect(result).toEqual(false);
+    } catch (err) {
+      Logger.warn('Error: %s', err, err);
+    }
+  });
+
+  test('should succeed on 3rd try', async () => {
+    const promise: Promise<boolean> = PromiseRatchet.waitFor(fnOn3, true, 100, 4);
+    const result: boolean | TimeoutToken = await promise;
+    expect(result).toEqual(true);
+  });
+
+  test('should run 10 elements, 2 at a time', async () => {
+    Logger.setLevel(LoggerLevelName.debug);
+    const elements: any[][] = [
+      [100, 'Test1'],
+      [120, 'Test2'],
+      [130, 'Test3'],
+      [140, 'Test4'],
+      [150, 'Test5'],
+      [160, 'Test6'],
+      [170, 'Test7'],
+      [180, 'Test8'],
+      [190, 'Test9'],
+      [200, 'Test10'],
+    ];
+
+    const results: number[] = await PromiseRatchet.runBoundedParallel<number>(waitAndPrint, elements, this, 2);
+
+    Logger.info('Final results %j', results);
+    expect(results).toBeTruthy();
+    expect(results.length).toEqual(10);
+  }, 30000);
+
+  test('should run 10 waits, 2 at a time', async () => {
+    Logger.setLevel(LoggerLevelName.debug);
+    const elements: number[] = [100, 110, 120, 130, 140, 150, 160, 170, 180, 200];
+
+    const results: any[] = await PromiseRatchet.runBoundedParallelSingleParam(PromiseRatchet.wait, elements, this, 2);
+
+    Logger.info('Final results %j', results);
+    expect(results).toBeTruthy();
+    expect(results.length).toEqual(10);
+  });
+
+  test('Validate runBoundedParallelSingleParam params', async () => {
+    const inputSymbols: string[] = ['a', 'b', 'c'];
+
+    const output: boolean[] = await PromiseRatchet.runBoundedParallelSingleParam<boolean>(
+      async (symbol) => {
+        Logger.info('Symbol was %s', symbol);
+        return true;
+      },
+      inputSymbols,
+      this,
+      1,
+    );
+
+    expect(output).not.toBeNull();
+  });
+
+  test.skip('should run an async function as a for/each', async () => {
+    Logger.setLevel(LoggerLevelName.debug);
+    const elements: number[] = [1001, 1002, 2000];
+    const pfn: (v: any) => Promise<void> = async (v) => {
+      Logger.info('Waiting %s', v);
+      await PromiseRatchet.wait(v);
+      Logger.info('Finished %s', v);
+    };
+
+    Logger.info('Serial test');
+    await PromiseRatchet.asyncForEachSerial(elements, pfn);
+
+    Logger.info('Parallel test');
+    await PromiseRatchet.asyncForEachParallel(elements, pfn);
+
+    Logger.info('Done');
+  });
+});

package/src/lang/promise-ratchet.ts

@@ -0,0 +1,196 @@
+/*
+    Functions for working with promises
+*/
+
+import { Logger } from '../logger/logger.js';
+import { ArrayRatchet } from './array-ratchet.js';
+import { TimeoutToken } from './timeout-token.js';
+import { StopWatch } from './stop-watch.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+
+export class PromiseRatchet {
+  /**
+   * Returns a promise that only resolves when the named event happens on the event source -
+   * the promise will return the passed object, if any, at that point.  If errEventNames are specified,
+   * the promise will reject when any of those events are fired
+   * @param evtSrc Object that will fire the event
+   * @param okEvtNames Names of the event that will be considered successes
+   * @param errEvtNames Names of error events
+   * @param rval Return value, if any
+   */
+  public static resolveOnEvent<T>(evtSrc: any, okEvtNames: string[], errEvtNames: string[] = [], rval: T = null): Promise<T> {
+    if (!evtSrc || !okEvtNames || okEvtNames.length === 0 || !evtSrc['on']) {
+      return Promise.reject('Cannot continue - missing source object or name, or the object is not an event source');
+    }
+    return new Promise<T>((res, rej) => {
+      okEvtNames.forEach((e) => {
+        evtSrc.on(e, () => {
+          res(rval);
+        });
+      });
+
+      if (errEvtNames) {
+        errEvtNames.forEach((e) => {
+          evtSrc.on(e, (err) => {
+            rej(err);
+          });
+        });
+      }
+    });
+  }
+
+  public static timeout<T>(srcPromise: Promise<T>, title: string, timeoutMS: number): Promise<T | TimeoutToken> {
+    return Promise.race([srcPromise, PromiseRatchet.createTimeoutPromise(title, timeoutMS) as Promise<T | TimeoutToken>]);
+  }
+
+  public static createTimeoutPromise(title: string, timeoutMS: number): Promise<TimeoutToken> {
+    // Create a promise that rejects in <timeoutMS> milliseconds
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    return new Promise<TimeoutToken>((resolve, reject) => {
+      const id = setTimeout(() => {
+        clearTimeout(id);
+        const rval: TimeoutToken = new TimeoutToken(title, timeoutMS);
+        resolve(rval);
+      }, timeoutMS);
+    });
+  }
+
+  public static async wait(time: number): Promise<void> {
+    // Ignore the returned timeout token
+    await PromiseRatchet.createTimeoutPromise('Wait ' + time, time);
+    Logger.silly('Finished wait of %d ms', time);
+  }
+
+  public static dumpResult(result: any): void {
+    Logger.info('Success, result was : \n\n%s\n\n', JSON.stringify(result));
+    process.exit(0);
+  }
+
+  public static dumpError(err: any): void {
+    Logger.warn('Failure, err was : \n\n%s\n\n  --  \n\n%s\n\n', JSON.stringify(err), String(err));
+    console.trace();
+    process.exit(1);
+  }
+
+  public static logErrorAndReturnNull(err: any): void {
+    Logger.warn('Failure, err was : \n\n%s\n\n  --  \n\n%s\n\n', JSON.stringify(err), String(err));
+    return null;
+  }
+
+  public static runPromiseAndDump<T>(promise: Promise<T>): void {
+    promise.then(PromiseRatchet.dumpResult).catch(PromiseRatchet.dumpError);
+  }
+
+  // Waits for up to maxCycles iterations of intervalMS milliseconds for the test function to return the expected value
+  // If that happens, returns true, otherwise, returns false
+  // Also returns false if the test function throws an exception or returns null (null may NOT be the expectedValue, as
+  // it is used as the "breakout" poison pill value
+  public static async waitFor(
+    testFunction: (n: number) => any,
+    expectedValue: any,
+    intervalMS: number,
+    maxCycles: number,
+    label = 'waitFor',
+    count = 0,
+  ): Promise<boolean> {
+    if (expectedValue == null || intervalMS < 50 || maxCycles < 1 || count < 0 || typeof testFunction != 'function') {
+      Logger.warn('%s: Invalid configuration for waitFor - exiting immediately', label);
+
+      Logger.warn(
+        'ExpectedValue : %s ; interval: %d ; maxCycles: %d ; test : %s',
+        expectedValue,
+        intervalMS,
+        maxCycles,
+        typeof testFunction,
+      );
+
+      return false;
+    }
+
+    let curVal: any = null;
+    try {
+      curVal = testFunction(count);
+    } catch (err) {
+      Logger.warn('%s: Caught error while waiting, giving up : %s', label, err);
+      return false;
+    }
+
+    if (curVal === null) {
+      Logger.debug('%s:CurVal was null - aborting', label);
+      return false;
+    } else if (curVal == expectedValue) {
+      Logger.debug('%s:Found expected value', label);
+      return true;
+    } else if (count > maxCycles) {
+      // Exceeded max cycles
+      Logger.debug('%s:Exceeded max cycles, giving up', label);
+      return false;
+    } else {
+      Logger.debug('%s : value not reached yet, waiting (count = %d of %d)', label, count, maxCycles);
+      await PromiseRatchet.wait(intervalMS);
+      return PromiseRatchet.waitFor(testFunction, expectedValue, intervalMS, maxCycles, label, count + 1);
+    }
+  }
+
+  public static async runBoundedParallel<T>(
+    promiseFn: (...args) => Promise<T> | undefined,
+    params: any[][],
+    context: any,
+    maxConcurrent = 1,
+    logLevel: LoggerLevelName = LoggerLevelName.debug,
+  ): Promise<T[]> {
+    const sw: StopWatch = new StopWatch();
+    let rval: T[] = [];
+    let remain: any[][] = params;
+    Logger.logByLevel(logLevel, 'Processing %d total elements %d at a time', params.length, maxConcurrent);
+
+    const ctx: any = context || this;
+    let processed = 0;
+    const totalCount: number = remain.length;
+
+    while (remain.length > 0) {
+      const curBatch: any[] = remain.slice(0, Math.min(remain.length, maxConcurrent));
+      remain = remain.slice(curBatch.length);
+
+      const proms: Promise<T>[] = curBatch.map((c) => promiseFn.apply(ctx, c) as Promise<T>);
+      const output: T[] = await Promise.all(proms);
+      processed += proms.length;
+      rval = rval.concat(output);
+
+      const pct: number = processed / totalCount;
+      Logger.logByLevel(logLevel, '%d elements remain : %s', remain.length, sw.dumpExpected(pct));
+    }
+    sw.log();
+    return rval;
+  }
+
+  public static async runBoundedParallelSingleParam<T>(
+    promiseFn: (arg) => Promise<T> | undefined,
+    params: any[],
+    context: any,
+    maxConcurrent = 1,
+    logLevel: LoggerLevelName = LoggerLevelName.debug,
+  ): Promise<T[]> {
+    const wrappedParams: any[][] = ArrayRatchet.wrapElementsInArray(params);
+    return PromiseRatchet.runBoundedParallel<T>(promiseFn, wrappedParams, context, maxConcurrent, logLevel);
+  }
+
+  public static async asyncForEachSerial<T, R>(array: any[], callback: (val: T, idx: number, arr: T[]) => Promise<R>): Promise<void> {
+    for (let index = 0; index < array.length; index++) {
+      await callback(array[index], index, array);
+    }
+  }
+
+  public static async asyncForEachParallel<T>(array: T[], callback: (val: T, idx: number, arr: T[]) => Promise<any>): Promise<void> {
+    const proms: Promise<any>[] = [];
+
+    for (let index = 0; index < array.length; index++) {
+      proms.push(callback(array[index], index, array));
+    }
+    await Promise.all(proms);
+  }
+
+  private constructor() {
+    // Blocked for instantiation
+  }
+}

package/src/lang/range.ts

@@ -0,0 +1,4 @@
+export interface Range<T> {
+  low: T;
+  high: T;
+}

package/src/lang/require-ratchet.spec.ts

@@ -0,0 +1,85 @@
+import { RequireRatchet } from './require-ratchet.js';
+import { fail } from 'assert';
+import { Logger } from '../logger/logger.js';
+import { describe, test } from 'vitest';
+
+describe('#standardCases', function () {
+  test('should throw exception on null value', function () {
+    try {
+      RequireRatchet.notNullOrUndefined(null, 'test1');
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+    try {
+      RequireRatchet.notNullOrUndefined(undefined, 'test2');
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+  });
+
+  test('should throw exception on whitespace value', function () {
+    try {
+      RequireRatchet.notNullUndefinedOrOnlyWhitespaceString('', 'test1');
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+    try {
+      RequireRatchet.notNullUndefinedOrOnlyWhitespaceString('    ', 'test2');
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+  });
+});
+
+describe('#noNullOrUndefinedValuesInArray', function () {
+  test('should throw exception on null value', function () {
+    const arr: any[] = [1, null, 'a'];
+    try {
+      RequireRatchet.noNullOrUndefinedValuesInArray(arr);
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+  });
+
+  test('throw exception on bad length', function () {
+    const arr: any[] = [1, 2, 'a'];
+    try {
+      RequireRatchet.noNullOrUndefinedValuesInArray(arr, 4);
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+  });
+
+  test('should not throw exception on good values', function () {
+    const arr: any[] = [1, 2, 'a'];
+    RequireRatchet.noNullOrUndefinedValuesInArray(arr, 3);
+  });
+
+  test('should not throw exception on good constructor values', function () {
+    const _test: ConstructorTester = new ConstructorTester('a', 'b');
+  });
+
+  test('throw exception on null constructor param', function () {
+    try {
+      const _test: ConstructorTester = new ConstructorTester('a', null);
+      fail('Should have thrown exception');
+    } catch (err) {
+      Logger.debug('Correctly threw exception : %s', err);
+    }
+  });
+});
+
+export class ConstructorTester {
+  constructor(_testVal1: string, _testVal2: string) {
+    Logger.info('Args : %j', this.constructor);
+    //Logger.info('Args : %j', this.constructor.arguments.length);
+
+    //RequireRatchet.noNullOrUndefinedValuesInRestArgs(this.constructor.arguments, ...arguments);
+  }
+}

package/src/lang/require-ratchet.ts

@@ -0,0 +1,68 @@
+/*
+    Functions for making simple assertions
+*/
+
+export class RequireRatchet {
+  public static isNullOrUndefined(ob: any): boolean {
+    return Object.is(ob, null) || Object.is(ob, undefined);
+  }
+
+  public static notNullOrUndefined(ob: any, name = 'object'): void {
+    if (RequireRatchet.isNullOrUndefined(ob)) {
+      throw new Error(name + ' may not be null or undefined');
+    }
+  }
+
+  public static notNullUndefinedOrOnlyWhitespaceString(ob: string, name = 'string'): void {
+    if (RequireRatchet.isNullOrUndefined(ob) || ob.trim() === '') {
+      throw new Error(name + ' may not be null or undefined or only whitespace string');
+    }
+  }
+
+  public static notNullUndefinedOrEmptyArray(ob: any[], name = 'string'): void {
+    if (RequireRatchet.isNullOrUndefined(ob) || ob.length === 0) {
+      throw new Error(name + ' may not be null or undefined or an empty array');
+    }
+  }
+
+  public static equal(ob1: any, ob2: any, message = 'Values must be equal'): void {
+    if (ob1 !== ob2) {
+      throw new Error(message);
+    }
+  }
+
+  public static true(ob: boolean, message = 'Value must be true'): void {
+    RequireRatchet.equal(ob, true, message);
+  }
+
+  public static noNullOrUndefinedValuesInArray(arr: any[], expectedLength: number = null, customMsg: string = null): void {
+    RequireRatchet.notNullOrUndefined(arr, 'Source array may not be null');
+    if (expectedLength !== null && arr.length !== expectedLength) {
+      throw new Error(`Expected array of length ${expectedLength} but was ${arr.length} ${customMsg}`);
+    }
+    for (let i = 0; i < arr.length; i++) {
+      if (RequireRatchet.isNullOrUndefined(arr[i])) {
+        throw new Error(`Array index ${i} was null or undefined ${customMsg}`);
+      }
+    }
+  }
+
+  public static noNullOrUndefinedValuesInRestArgs(expectedLength: number, ...restArgs: any[]): void {
+    RequireRatchet.notNullOrUndefined(restArgs, 'Source array may not be null');
+    if (expectedLength !== null && restArgs.length !== expectedLength) {
+      throw new Error(`Expected array of length ${expectedLength} but was ${restArgs.length}`);
+    }
+    for (let i = 0; i < restArgs.length; i++) {
+      if (RequireRatchet.isNullOrUndefined(restArgs[i])) {
+        throw new Error(`Array index ${i} was null or undefined`);
+      }
+    }
+  }
+
+  public static constructorArgumentsMatchLengthAndAreNonNull(): void {
+    // eslint-disable-next-line prefer-rest-params
+    const args: any[] = Array.from(arguments);
+    const len: number = this.constructor.length;
+    return RequireRatchet.noNullOrUndefinedValuesInArray(args, len);
+  }
+}

package/src/lang/simple-arg-ratchet.spec.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from 'vitest';
+import { SimpleArgRatchet } from './simple-arg-ratchet.js';
+
+describe('#simpleArgRatchet', function () {
+  test('should parse multi arguments', function () {
+    const test: string[] = ['--a', 'b', '--c', 'd', '--a', 'e'];
+    const out: Record<string, string[]> = SimpleArgRatchet.parseArgs(test, ['a', 'c']);
+    expect(out).not.toBeNull;
+    expect(out['a'].length).toEqual(2);
+    expect(out['c'].length).toEqual(1);
+    expect(out['c'][0]).toEqual('d');
+  });
+});

package/src/lang/simple-arg-ratchet.ts

@@ -0,0 +1,47 @@
+import { ErrorRatchet } from './error-ratchet.js';
+
+/**
+ * A dirt simple arg parser - only allows the --x y format
+ */
+export class SimpleArgRatchet {
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static parseArgs(args: string[], validArgNames: string[]): Record<string, string[]> {
+    const rval: Record<string, string[]> = {};
+    if (args?.length) {
+      if (args.length % 2 !== 0) {
+        throw ErrorRatchet.fErr('Invalid arguments, all args must take the form --a b, but there were an odd number of arguments');
+      }
+      for (let i = 0; i < args.length; i += 2) {
+        let key: string = args[i];
+        const value: string = args[i + 1];
+        if (!key.startsWith('--')) {
+          throw ErrorRatchet.fErr('Argument %s does not take the form --x', key);
+        }
+        key = key.substring(2);
+        if (!validArgNames.includes(key)) {
+          throw ErrorRatchet.fErr('Argument %s is not a valid argument (valid were %j)', key, validArgNames);
+        }
+        rval[key] = rval[key] ?? [];
+        rval[key].push(value);
+      }
+    }
+    return rval;
+  }
+
+  public static parseSingleArgs(args: string[], validArgNames: string[]): Record<string, string> {
+    const tmp: Record<string, string[]> = SimpleArgRatchet.parseArgs(args, validArgNames);
+    const rval: Record<string, string> = {};
+    Object.keys(tmp).forEach((k) => {
+      const v: string[] = tmp[k];
+      if (v.length > 1) {
+        throw ErrorRatchet.fErr('Argument %s had %d values, but should have 1', k, v.length);
+      }
+      rval[k] = v[0];
+    });
+
+    return rval;
+  }
+}

package/src/lang/simple-encryption-ratchet.ts

@@ -0,0 +1,88 @@
+import { RequireRatchet } from "./require-ratchet.ts";
+import { NumberRatchet } from "./number-ratchet.ts";
+import { Base64Ratchet } from "./base64-ratchet.ts";
+
+/**
+ * A VERY simple wrapper for doing basic AES-GCM encryption on arbitrary text -
+ * useful for slugs, etc., since the same code should work both in Node.js and
+ * most modern browsers
+ */
+export class SimpleEncryptionRatchet{
+  private sharedKey: Promise<CryptoKey>;
+
+  constructor(sharedRawKey: string | Promise<string>, private urlSafe:boolean = false, private ivLength: number = 12) { // Recommended for AES-GCM
+    RequireRatchet.notNullOrUndefined(sharedRawKey);
+    RequireRatchet.true(ivLength>=12, 'ivLength must be at least 12');
+    this.sharedKey = this.createSharedKey(sharedRawKey);
+  }
+
+  // Converts string to ArrayBuffer
+  private strToBuf(str: string): Uint8Array<ArrayBuffer> {
+    return new TextEncoder().encode(str);
+  }
+
+  // Converts ArrayBuffer to base64
+  private bufToBase64(buf: ArrayBuffer): string {
+    return btoa(String.fromCharCode(...new Uint8Array(buf)));
+  }
+
+  // Converts base64 to ArrayBuffer
+  private base64ToBuf(base64: string): Uint8Array<ArrayBuffer> {
+    return new Uint8Array(atob(base64).split('').map(c => c.charCodeAt(0)));
+  }
+
+
+  // Encrypt a string with a shared key
+  public async encrypt(data: string): Promise<string> {
+    const iv:Uint8Array<ArrayBuffer> = crypto.getRandomValues(new Uint8Array(this.ivLength));
+    const encoded:Uint8Array<ArrayBuffer> = this.strToBuf(data);
+    const key: CryptoKey = await this.sharedKey;
+    const ciphertext = await crypto.subtle.encrypt(
+      { name: "AES-GCM", iv },
+      key,
+      encoded
+    );
+    const ivMsg: string = this.bufToBase64(iv.buffer);
+    const dataMsg: string = this.bufToBase64(ciphertext);
+
+    // Format it up in a way that can be unrolled later
+    let rval: string = ivMsg.length+'K'+ivMsg+dataMsg;
+    if (this.urlSafe) {
+      rval = Base64Ratchet.encodeStringToBase64UrlString(rval);
+    }
+    return rval;
+  }
+
+  // Decrypt a string with the shared key
+  public async decrypt(encryptedValueIn: string): Promise<string> {
+    const encryptedValue: string = this.urlSafe ? Base64Ratchet.decodeBase64UrlStringToString(encryptedValueIn) : encryptedValueIn;
+    const split: number = encryptedValue?.indexOf('K')
+    if (!split || split<1) {
+      throw new Error('Invalid split : '+split);
+    }
+    const ivLen: number = NumberRatchet.safeNumber(encryptedValue.substring(0, split));
+    const iv: string = encryptedValue.substring(split+1, split+1+ivLen);
+    const data: string = encryptedValue.substring(split+1+ivLen);
+
+    const key: CryptoKey = await this.sharedKey;
+    const decrypted = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: this.base64ToBuf(iv) },
+      key,
+      this.base64ToBuf(data)
+    );
+    return new TextDecoder().decode(decrypted);
+  }
+
+  // Generate or import a shared key
+  private async createSharedKey(rawKeyIn: string | Promise<string>): Promise<CryptoKey> {
+    const rawKey: string = typeof rawKeyIn === 'string' ? rawKeyIn : await rawKeyIn;
+    const keyMaterial = this.strToBuf(rawKey.padEnd(32, '0').slice(0, 32)); // 256-bit key
+    return crypto.subtle.importKey(
+      "raw",
+      keyMaterial,
+      "AES-GCM",
+      false,
+      ["encrypt", "decrypt"]
+    );
+  }
+}

package/src/lang/sort-ratchet.spec.ts

@@ -0,0 +1,58 @@
+import { SortRatchet } from './sort-ratchet.js';
+import { Logger } from '../logger/logger.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#sortRatchet', function () {
+  test('sort nulls and undefined to the top', async () => {
+    const input: string[] = [null, 'a', null, 'b', null, 'c'];
+    input.sort((a, b) => SortRatchet.sortNullToTop<string>(a, b, (a, b) => a.localeCompare(b)));
+
+    expect(input.length).toEqual(6);
+    expect(input[3]).toEqual('a');
+    expect(input[0]).toBeFalsy();
+    expect(input[1]).toBeFalsy();
+    expect(input[2]).toBeFalsy();
+  });
+
+  test('sort nulls and undefined to the bottom', async () => {
+    const input: string[] = ['a', null, 'b', undefined, 'c', null];
+    input.sort((a, b) => SortRatchet.sortNullToBottom<string>(a, b, (a, b) => a.localeCompare(b)));
+
+    Logger.info('%j', input);
+
+    expect(input.length).toEqual(6);
+    expect(input[0]).toEqual('a');
+    expect(input[3]).toBeFalsy();
+    expect(input[4]).toBeFalsy();
+    expect(input[5]).toBeFalsy();
+  });
+
+  test('sort mixed numbers and strings as numbers', async () => {
+    const input: (string | number)[] = ['1', 10, '5', 20, '-8', 35.2];
+    input.sort(SortRatchet.sortNumericStringsAsNumbers);
+
+    Logger.info('%j', input);
+
+    expect(input.length).toEqual(6);
+    expect(input[0]).toEqual('-8');
+    expect(input[1]).toEqual('1');
+    expect(input[2]).toEqual('5');
+    expect(input[3]).toEqual(10);
+    expect(input[4]).toEqual(20);
+    expect(input[5]).toEqual(35.2);
+  });
+
+  test('sort mixed numbers and strings as numbers handling string as null', async () => {
+    const input: (string | number)[] = ['a', 10, 'b', 20, '-8', 35.2];
+    input.sort(SortRatchet.sortNumericStringsAsNumbers);
+
+    Logger.info('%j', input);
+
+    expect(input[0]).toEqual('-8');
+    expect(input[1]).toEqual(10);
+    expect(input[2]).toEqual(20);
+    expect(input[3]).toEqual(35.2);
+    expect(input[4]).toEqual('a');
+    expect(input[5]).toEqual('b');
+  });
+});