@bitblit/ratchet-common 6.0.145-alpha → 6.0.147-alpha

package/src/lang/map-ratchet.ts

@@ -0,0 +1,220 @@
+/*
+    Functions for working with maps (dictionaries/objects in javascript)
+*/
+
+import { KeyValue } from './key-value.js';
+import { Logger } from '../logger/logger.js';
+import { ErrorRatchet } from './error-ratchet.js';
+import { StringRatchet } from "./string-ratchet.ts";
+
+export class MapRatchet {
+  // Takes any map with keys that are nested and expands them
+  // eg, x['a.b']=2 becomes x['a']={b:2}
+  // Renamed because the pre-v4 version deferred to lodash and handled arrays correctly.
+  // This removes the lodash dependency, but isn't fully backward compatible
+  public static expandNestedKeysToObjects<T>(src: any, separator = '.'): T {
+    if (!separator || separator.length !== 1) {
+      throw new Error('Invalid separator (must be single character)');
+    }
+    const rval: T = {} as T;
+    Object.keys(src).forEach((k) => {
+      const path: string[] = k.split(separator);
+      let target: any = rval;
+      while (path.length > 1) {
+        target[path[0]] = target[path[0]] || {};
+        target = target[path[0]];
+        path.splice(0, 1);
+      }
+      target[path[0]] = src[k];
+    });
+    return rval;
+  }
+
+  public static mapByUniqueProperty<T, R>(input: T[], propName: string): Map<R, T> {
+    if (!input || !propName) {
+      throw new Error('Neither input nor propName can be null');
+    }
+
+    const rval: Map<R, T> = new Map<R, T>();
+    input.forEach((i) => {
+      const val: R = i ? i[propName] : null;
+      if (val === null || val === undefined) {
+        throw new Error('No value for ' + propName + ' found in ' + JSON.stringify(i));
+      }
+      if (rval.has(val)) {
+        throw new Error('Multiple values found for ' + val);
+      }
+      rval.set(val, i);
+    });
+    return rval;
+  }
+
+  public static groupByProperty<T, R>(input: T[], propName: string): Map<R, T[]> {
+    if (!input || !propName) {
+      throw new Error('Neither input nor propName can be null');
+    }
+
+    const rval: Map<R, T[]> = new Map<R, T[]>();
+    input.forEach((i) => {
+      const val: R = i ? i[propName] : null;
+      if (val === null || val === undefined) {
+        throw ErrorRatchet.fErr('No value for %s found in %j', propName, i);
+      }
+      if (!rval.has(val)) {
+        rval.set(val, []);
+      }
+      rval.get(val).push(i);
+    });
+    return rval;
+  }
+
+  public static findValue(toSearch: any, path: string[]): any {
+    if (!path || path.length == 0) {
+      return toSearch;
+    } else {
+      if (toSearch) {
+        return MapRatchet.findValue(toSearch[path[0]], path.slice(1));
+      } else {
+        return null;
+      }
+    }
+  }
+
+  public static findValueDotPath(toSearch: any, dotPath: string): any {
+    if (!dotPath || dotPath.length == 0) {
+      return toSearch;
+    } else {
+      if (toSearch) {
+        return MapRatchet.findValue(toSearch, dotPath.split('.'));
+      } else {
+        return null;
+      }
+    }
+  }
+
+  // Ok so this does the dumbest possible deep compare, by converting
+  // both objects to JSON and comparing strings.  Its slow and stupid
+  // but its easy.
+
+  public static simpleDeepCompare(object1: any, object2: any): boolean {
+    if (object1 == null && object2 == null) return true;
+    if (object1 == null || object2 == null) return false;
+    return JSON.stringify(object1) == JSON.stringify(object2);
+  }
+
+  public static toKeyValueList(value: Record<string, any>): KeyValue<any>[] {
+    const returnArray: KeyValue<any>[] = [];
+
+    for (const k of Object.keys(value)) {
+      returnArray.push({
+        key: k,
+        value: value[k],
+      } as KeyValue<any>);
+    }
+
+    return returnArray;
+  }
+
+  public static fromKeyValueList<T>(list: KeyValue<T>[]): Record<string, T> {
+    const rval: any = {};
+    list.forEach((a) => (rval[a.key] = a.value));
+    return rval;
+  }
+
+  /*
+    Mainly here to simplify sending objects to DynamoDB - recursively descend and clean up javascript objects, removing
+    any empty strings, nulls, etc.
+
+    CAW 2024-08-09: Since DynamoClient has its own implementation of this now, better to use the marshaller over there instead
+     */
+  public static cleanup<T>(obj: T, stripZero = false, stripNull = true, stripUndefined = true, stripEmptyString = true): T {
+    // See : https://stackoverflow.com/questions/286141/remove-blank-attributes-from-an-object-in-javascript
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+      return obj;
+    }
+    const o = JSON.parse(JSON.stringify(obj)); // Clone source oect.
+
+    Object.keys(o).forEach((key) => {
+      if (o[key] && typeof o[key] === 'object') {
+        if (Array.isArray(o[key])) {
+          for (let i = 0; i < o[key].length; i++) {
+            o[key][i] = MapRatchet.cleanup(o[key][i]);
+          }
+        } else {
+          o[key] = MapRatchet.cleanup(o[key]); // Recurse.
+        }
+      } else if (
+        (o[key] === undefined && stripUndefined) ||
+        (o[key] === null && stripNull) ||
+        (o[key] === '' && stripEmptyString) ||
+        (o[key] === 0 && stripZero)
+      ) {
+        // This actually IS a bad example of this, but the whole function is deprecated now
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete o[key]; // Delete undefined and null.
+      } else {
+        // Leave it alone
+      }
+    });
+
+    return o; // Return new object.
+  }
+
+  public static extractValueFromMapIgnoreCase(src: any, key: string): any {
+    let rval: any = null;
+    if (src && key) {
+      const finder: string = key.toLowerCase();
+      Object.keys(src).forEach((s) => {
+        if (s.toLowerCase() === finder) {
+          const newVal: string = src[s];
+          if (rval) {
+            Logger.warn('Multiple entries found for %s (replacing %s with %s', key, rval, newVal);
+          }
+          rval = newVal;
+        }
+      });
+    }
+    return rval;
+  }
+
+  public static safeCallFunction(ob: any, fnName: string): boolean {
+    let rval = false;
+    if (!!ob && !!ob[fnName] && typeof ob[fnName] === 'function') {
+      try {
+        ob[fnName]();
+        rval = true;
+      } catch (err) {
+        Logger.warn('Error calling %s on %s : %s', fnName, ob, err, err);
+      }
+    }
+    return rval;
+  }
+
+  public static caseInsensitiveAccess<T>(ob: any, keyName: string): T {
+    let rval: T = null;
+
+    if (!!ob && !!keyName) {
+      rval = ob[keyName]; // Short circuit
+      if (!rval) {
+        const keyNameCI: string = Object.keys(ob).find((f) => f.toLowerCase() === keyName.toLowerCase());
+        if (keyNameCI) {
+          rval = ob[keyNameCI];
+        }
+      }
+    }
+    return rval;
+  }
+
+  public static snakeCaseKeysToCamelCase(obj:any):any {
+    if (Array.isArray(obj)) {
+      return obj.map(v => StringRatchet.snakeCaseToCamelCase(v));
+    } else if (obj !== null && obj.constructor === Object) {
+      return Object.entries(obj).reduce((acc, [key, value]) => {
+        const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        acc[camelKey] = StringRatchet.snakeCaseToCamelCase(value);
+        return acc;
+      }, {});
+    }
+    return obj;
+  }
+}

package/src/lang/no.spec.ts

@@ -0,0 +1,9 @@
+import { PromiseRatchet } from './promise-ratchet.js';
+import { No } from './no.js';
+import { describe, test } from 'vitest';
+
+describe('#no', function () {
+  test('should do nothing', () => {
+    PromiseRatchet.wait(100).then(No.op);
+  });
+});

package/src/lang/no.ts

@@ -0,0 +1,7 @@
+// Clean way to do a no-op
+export class No {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public static op(...args: any[]): void {
+    // Do nothing
+  }
+}

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

@@ -0,0 +1,154 @@
+import { NumberRatchet, SinglesAndRanges } from './number-ratchet.js';
+import fs from 'fs';
+import path from 'path';
+import { EsmRatchet } from './esm-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#toFixedDecimalNumber', function () {
+  test('should convert "5.1234 to 5.12', function () {
+    expect(NumberRatchet.toFixedDecimalNumber(5.1234, 2)).toEqual(5.12);
+    expect(NumberRatchet.toFixedDecimalNumber('5.1234', 2)).toEqual(5.12);
+  });
+
+  test('should convert "5.5678 to 5.57', function () {
+    expect(NumberRatchet.toFixedDecimalNumber(5.5678, 2)).toEqual(5.57);
+    expect(NumberRatchet.toFixedDecimalNumber('5.5678', 2)).toEqual(5.57);
+  });
+});
+
+describe('#leadingZeros', function () {
+  test('should convert "5" to 05', function () {
+    const result: string = NumberRatchet.leadingZeros('5', 2);
+    expect(result).toEqual('05');
+  });
+
+  test('should leave 166 alone', function () {
+    const result: string = NumberRatchet.leadingZeros('166', 2);
+    expect(result).toEqual('166');
+  });
+});
+
+describe('#safeToNumber', function () {
+  test('should convert "55" to 55', function () {
+    const result: number = NumberRatchet.safeNumber('55');
+    expect(result).toEqual(55);
+  });
+
+  test('should convert "574,528" to 574528', function () {
+    const result: number = NumberRatchet.safeNumber('574,528');
+    expect(result).toEqual(574528);
+  });
+
+  test('should convert "574.528,88" to 574528.88 like european', function () {
+    const result: number = NumberRatchet.safeNumberOpt('574.528,88', { preParseCharacterMapping: { '.': '', ',': '.' } });
+    expect(result).toEqual(574528.88);
+  });
+
+  test('should leave 66 alone', function () {
+    const result: number = NumberRatchet.safeNumber(66);
+    expect(result).toEqual(66);
+  });
+
+  test('should return the default when it cannot parse', function () {
+    const result: number = NumberRatchet.safeNumber({ test: 'test' }, 42);
+    expect(result).toEqual(42);
+  });
+
+  test('should return the default for the empty string', function () {
+    const result: number = NumberRatchet.safeNumber({ test: '' }, 42);
+    expect(result).toEqual(42);
+  });
+
+  test('should return the default for null/undefined if set true', function () {
+    const result: number = NumberRatchet.safeNumber(null, 42, true);
+    expect(result).toEqual(42);
+    const result2: number = NumberRatchet.safeNumber(undefined, 46, true);
+    expect(result2).toEqual(46);
+  });
+
+  test('should return the passed value for null/undefined if set false', function () {
+    const result: number = NumberRatchet.safeNumber(null, 42, false);
+    expect(result).toEqual(null);
+    const result2: number = NumberRatchet.safeNumber(undefined, 46, false);
+    expect(result2).toEqual(undefined);
+  });
+
+  test('should return null for an undefined input by default', function () {
+    const result: number | null = NumberRatchet.safeNumber(undefined, 0);
+    expect(result).toEqual(null);
+  });
+
+  test('should return null for a null input by default', function () {
+    const result: number = NumberRatchet.safeNumber(null, 42);
+    expect(result).toEqual(null);
+  });
+});
+
+describe('#parseCSV', function () {
+  test('should convert "1,2,3" to [1,2,3]', function () {
+    const result: number[] = NumberRatchet.numberCSVToList('1,2,3');
+    expect(result.length).toEqual(3);
+  });
+
+  test('should convert " 1, 2,3  " to [1,2,3]', function () {
+    const result: number[] = NumberRatchet.numberCSVToList(' 1, 2,3 ');
+    expect(result.length).toEqual(3);
+  });
+
+  test('should convert " a1, 2,b  " to [2]', function () {
+    const result: number[] = NumberRatchet.numberCSVToList(' a1, 2,b  ');
+    expect(result.length).toEqual(1);
+    expect(result[0]).toEqual(2);
+  });
+});
+
+describe('#fitToWindow', function () {
+  test('should fit input to the window', function () {
+    expect(NumberRatchet.fitToWindow(5, 8, 10)).toEqual(9);
+    expect(NumberRatchet.fitToWindow(8, 2, 10)).toEqual(8);
+    expect(NumberRatchet.fitToWindow(8, 9, 9)).toEqual(9);
+    expect(NumberRatchet.fitToWindow(12, 2, 10)).toEqual(4);
+  });
+});
+
+describe('#groupNumbersIntoContiguousRanges', function () {
+  test('should group numbers', function () {
+    let input: number[] = JSON.parse(
+      fs.readFileSync(path.join(EsmRatchet.fetchDirName(import.meta.url), '../../../../test-data/number_set.json')).toString(),
+    );
+    input = input.map((i) => NumberRatchet.safeNumber(i));
+    const grouped: SinglesAndRanges = NumberRatchet.groupNumbersIntoContiguousRanges(input, 5);
+    expect(grouped).toBeTruthy();
+  });
+});
+
+describe('#distributeItemsEvenly', function () {
+  test('should distribute evenly', function () {
+    const test1: number[] = NumberRatchet.distributeItemsEvenly(4, 6);
+    expect(test1).toBeTruthy();
+    const test2: number[] = NumberRatchet.distributeItemsEvenly(12, 6);
+    expect(test2).toBeTruthy();
+    const test3: number[] = NumberRatchet.distributeItemsEvenly(5, 6);
+    expect(test3).toBeTruthy();
+    const test4: number[] = NumberRatchet.distributeItemsEvenly(192, 11);
+    expect(test4).toBeTruthy();
+    const test5: number[] = NumberRatchet.distributeItemsEvenly(11, 192);
+    expect(test5).toBeTruthy();
+  });
+});
+
+describe('#createRange', function () {
+  test('should create ranges', function () {
+    const test1: number[] = NumberRatchet.createRange(0, 5, 1);
+    expect(test1).toBeTruthy();
+    expect(test1.length).toEqual(5);
+
+    const test2: number[] = NumberRatchet.createRange(1, 5, 1);
+    expect(test2).toBeTruthy();
+    expect(test2.length).toEqual(4);
+
+    const test3: number[] = NumberRatchet.createRange(0, 10, 2);
+    expect(test3).toBeTruthy();
+    expect(test3.length).toEqual(5);
+  });
+});

package/src/lang/number-ratchet.ts

@@ -0,0 +1,253 @@
+/*
+    Functions for working with numbers
+*/
+
+import { Logger } from '../logger/logger.js';
+import { RequireRatchet } from './require-ratchet.js';
+import { Range } from './range';
+
+export class NumberRatchet {
+  private static MAX_LEADING_ZEROS_FORMAT_LENGTH = 1000; // Because really, why?
+  public static readonly DEFAULT_SAFE_NUMBER_OPTIONS: SafeNumberOptions = {
+    ifNotNumber: null,
+    returnValueForNull: null,
+    returnValueForUndefined: null,
+    preParseCharacterMapping: { ',': '' },
+  };
+
+  public static toFixedDecimalNumber(input: number | string, placesAfterPoint: number): number {
+    const v: number = NumberRatchet.safeNumber(input);
+    // If v is not defined, let that bubble up...
+    return v === null || v === undefined ? v : NumberRatchet.safeNumber(v.toFixed(placesAfterPoint));
+  }
+
+  public static leadingZeros(val: any, size: number): string {
+    const sVal = String(val);
+    if (sVal.length < size) {
+      let pad = '0000';
+      if (size > NumberRatchet.MAX_LEADING_ZEROS_FORMAT_LENGTH) {
+        throw 'Cannot format number that large (max length is ' + NumberRatchet.MAX_LEADING_ZEROS_FORMAT_LENGTH + ')';
+      }
+      while (pad.length < size) {
+        pad = pad + pad; // It won't take that long to get there
+      }
+
+      return (pad + sVal).slice(-1 * size);
+    } else {
+      return sVal;
+    }
+  }
+
+  public static between(inTest: number, inP1: number, inP2: number): boolean {
+    const test: number = NumberRatchet.safeNumber(inTest);
+    const p1: number = NumberRatchet.safeNumber(inP1);
+    const p2: number = NumberRatchet.safeNumber(inP2);
+
+    return (test >= p1 && test <= p2) || (test >= p2 && test <= p1);
+  }
+
+  // If it's a number, leave it alone, if it's a string, parse it.
+  // If its null or undefined, default to passing it through
+  // unmodified to match old behavior, but if the user sets the
+  // useDefaultForNullAndUndefined flag, use it instead
+  // I support both modes because some people consider "null/undefined" a valid value for
+  // numbers and others don't!
+
+  public static safeNumber(input: any, ifNotNumber: number = null, useDefaultForNullAndUndefined?: boolean): number {
+    const opts: Partial<SafeNumberOptions> = {
+      ifNotNumber: ifNotNumber,
+      returnValueForNull: useDefaultForNullAndUndefined ? ifNotNumber : null,
+      returnValueForUndefined: useDefaultForNullAndUndefined ? ifNotNumber : undefined,
+    };
+    if (useDefaultForNullAndUndefined === undefined) {
+      opts.returnValueForUndefined = null; // For backwards compatibility - used to return null for both null and undefined
+    }
+
+    return NumberRatchet.safeNumberOpt(input, opts);
+  }
+
+  public static safeNumberOpt(input: any, optionPart?: Partial<SafeNumberOptions>): number {
+    let rval: number = undefined;
+    const opts: SafeNumberOptions = Object.assign({}, NumberRatchet.DEFAULT_SAFE_NUMBER_OPTIONS, optionPart || {});
+    if (input === null) {
+      rval = opts.returnValueForNull;
+    } else if (input === undefined) {
+      rval = opts.returnValueForUndefined;
+    } else {
+      const type: string = typeof input;
+      if (type == 'number') {
+        rval = input;
+      } else if (type == 'string') {
+        let test: string = input.trim();
+        if (test.length === 0) {
+          rval = opts.ifNotNumber;
+        } else {
+          if (opts.preParseCharacterMapping && Object.keys(opts.preParseCharacterMapping).length > 0) {
+            let t2 = '';
+            for (let i = 0; i < test.length; i++) {
+              const cr: string = test.charAt(i);
+              t2 += opts.preParseCharacterMapping[cr] === undefined ? cr : opts.preParseCharacterMapping[cr];
+            }
+            test = t2;
+          }
+          rval = Number.parseFloat(test);
+        }
+      } else {
+        Logger.warn('Value is of type %s, returning default', type);
+        rval = opts.ifNotNumber;
+      }
+
+      if (isNaN(rval)) {
+        Logger.debug('Parsed string to NaN - using NaN value from param');
+        rval = opts.ifNotNumber;
+      }
+    }
+
+    return rval;
+  }
+
+  public static numberCSVToList(inputCSV: string): number[] {
+    let rval: number[] = null;
+    if (inputCSV) {
+      rval = inputCSV.split(',').map((s) => {
+        return NumberRatchet.safeNumber(s.trim());
+      });
+      rval = rval.filter((r) => typeof r === 'number' && !isNaN(r));
+    }
+    return rval;
+  }
+
+  public static fitToWindow(val: number, b1: number, b2: number): number {
+    let rval: number = val;
+    if (val === null || b1 === null || b2 === null || b1 < 0 || b2 < 0 || val < 0) {
+      throw new Error('All values must be non-null and larger than 0');
+    }
+    const low: number = Math.min(b1, b2);
+    const high: number = Math.max(b1, b2);
+    const windowSize: number = high - low;
+    if (high === low) {
+      // If the bounds are the same the answer is always the same
+      rval = high;
+    } else {
+      // Not super efficient (I should use modulo here) but works for the moment
+      while (rval < low) {
+        rval += windowSize;
+      }
+      while (rval > high) {
+        rval -= windowSize;
+      }
+    }
+
+    return rval;
+  }
+
+  public static groupNumbersIntoContiguousRanges(inputData: number[], minRangeSize = 3): SinglesAndRanges {
+    RequireRatchet.notNullOrUndefined(inputData);
+    const input: number[] = Object.assign([], inputData);
+    input.sort((a, b) => a - b);
+
+    const singles: number[] = [];
+    const ranges: NumberRange[] = [];
+    let start = 0;
+    for (let i = 1; i < input.length; i++) {
+      if (input[i] === input[i - 1] + 1) {
+        // Just advance
+      } else {
+        // End of sequence, either single or range
+        if (start === i - 1) {
+          singles.push(input[i - 1]);
+        } else {
+          const rangeSize: number = i - start;
+          if (rangeSize < minRangeSize) {
+            for (let j = start; j < i; j++) {
+              singles.push(input[j]);
+            }
+          } else {
+            ranges.push({
+              min: input[start],
+              max: input[i - 1],
+            });
+          }
+        }
+        // Either way, advance start
+        start = i;
+      }
+    }
+    return {
+      singles: singles,
+      ranges: ranges,
+    };
+  }
+
+  // Given N items and M buckets, return how many items in each bucket, as even as
+  // possible
+  public static distributeItemsEvenly(items: number, buckets: number): number[] {
+    RequireRatchet.notNullOrUndefined(items, 'items');
+    RequireRatchet.notNullOrUndefined(buckets, 'buckets');
+    RequireRatchet.true(items > 0 && items === Math.floor(items), 'Items integer larger than 0');
+    RequireRatchet.true(buckets > 0 && buckets === Math.floor(buckets), 'Buckets integer larger than 0');
+
+    const offset: number = buckets / items;
+    const rval: number[] = [];
+    for (let i = 0; i < buckets; i++) {
+      rval.push(0);
+    }
+
+    let loc = 0;
+    let rem: number = items;
+
+    while (rem > 0) {
+      rval[Math.floor(loc) % buckets]++;
+      rem--;
+      loc += offset;
+    }
+
+    return rval;
+  }
+
+  // Just creates an array of numbers between 2 bounds
+  public static createRange(minInclusive: number, maxExclusive: number, step = 1): number[] {
+    const rval: number[] = [];
+    let val: number = minInclusive;
+    while (val < maxExclusive) {
+      rval.push(val);
+      val += step;
+    }
+    return rval;
+  }
+
+  public static percentFormatNumberRange(range: Range<number>): string {
+    let rval: string = 'N/A';
+    if (range) {
+      rval = range.low ? NumberRatchet.pctFormatted(range.low) : ' ^ ';
+      rval += ' - ';
+      rval += range.high ? NumberRatchet.pctFormatted(range.high) : ' ^ ';
+    }
+    return rval;
+  }
+
+  public static pctFormatted(pct: number, fractionDigits: number = 2): string {
+    const rval: string =
+      pct === null || pct === undefined
+        ? 'Null'
+        : pct.toLocaleString('en-US', { minimumFractionDigits: fractionDigits, maximumFractionDigits: fractionDigits }) + '%';
+    return rval;
+  }
+}
+
+export interface SinglesAndRanges {
+  singles: number[];
+  ranges: NumberRange[];
+}
+
+export interface NumberRange {
+  min: number;
+  max: number;
+}
+
+export interface SafeNumberOptions {
+  ifNotNumber: number; // Value to return if the passed value was not a number
+  returnValueForNull: number;
+  returnValueForUndefined: number;
+  preParseCharacterMapping: Record<string, string>; // Replaces any characters on the left side with the right - used to remove the thousand separators and convert for euro currencies
+}

package/src/lang/parsed-url.ts

@@ -0,0 +1,10 @@
+export interface ParsedUrl {
+  href: string;
+  protocol: string;
+  host: string;
+  hostname: string;
+  port: string;
+  pathname: string;
+  search: string;
+  hash: string;
+}