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

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

@@ -0,0 +1,45 @@
+import { EnumRatchet } from './enum-ratchet.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#enumRatchet', function () {
+  test('should list keys', async () => {
+    const keys: string[] = EnumRatchet.listEnumKeys(TestEnum);
+    expect(keys).toBeTruthy();
+    expect(keys.length).toBeGreaterThan(1);
+  });
+
+  test('should find key case insensitive', async () => {
+    const t1: TestEnum = EnumRatchet.keyToEnum<TestEnum>(TestEnum, 'a');
+    const t2: TestEnum = EnumRatchet.keyToEnum<TestEnum>(TestEnum, 'b');
+    const t3: TestEnum = EnumRatchet.keyToEnum<TestEnum>(TestEnum, 'A', true);
+    const t4: TestEnum = EnumRatchet.keyToEnum<TestEnum>(TestEnum, 'A');
+
+    const fixed: TestEnum = TestEnum.A;
+
+    expect(t1).toBeTruthy();
+    expect(t2).toBeTruthy();
+    expect(t3).toBeNull();
+    expect(t4).toEqual(fixed);
+    expect(t4 === fixed).toBeTruthy();
+  });
+
+  test('should parse a csv of enums', async () => {
+    const vals: TestEnum[] = EnumRatchet.parseCsvToEnumArray<TestEnum>(TestEnum, 'a, b');
+    expect(vals).toBeTruthy();
+    expect(vals.length).toEqual(2);
+  });
+
+  test('should work with psuedo-enums like ratchet uses', async () => {
+    const keys: string[] = EnumRatchet.listEnumKeys(LoggerLevelName);
+    expect(keys.length).toEqual(6);
+    expect(keys.includes('info')).toBeTruthy();
+    expect(keys.includes('xxx')).toBeFalsy();
+  });
+});
+
+export enum TestEnum {
+  A = 'a',
+  B = 'b',
+  C = 'c',
+}

package/src/lang/enum-ratchet.ts

@@ -0,0 +1,41 @@
+import { $enum, EnumWrapper } from 'ts-enum-util';
+import { StringRatchet } from './string-ratchet.js';
+
+/**
+ * This class is here because Typescript's enums aren't very good - they aren't typesafe, and are difficult
+ * to go back-and-forth from strings, etc.  This also allows the HTTP layer to send an enum that isn't using the
+ * same case as the enum and still handle it correctly.  Either way, it puts all the conversion login in one
+ * place so if typescript changes this yet again in the future there'll be a convenient place to fix them
+ * all at once
+ */
+export class EnumRatchet {
+  public static listEnumKeys(enumeration: any): string[] {
+    const rval: string[] = $enum(enumeration).getValues();
+    return rval;
+  }
+
+  public static keyToEnum<T>(enumeration: any, val: string, caseSensitive = false): T {
+    const e: EnumWrapper = $enum(enumeration);
+    let rval: T = null;
+    if (val) {
+      rval = e.asValueOrDefault(val, null);
+      if (!rval && !caseSensitive) {
+        // Try other cases
+        const keys: string[] = EnumRatchet.listEnumKeys(enumeration);
+        const mKey: string = keys.find((k) => k.toUpperCase() === val.toUpperCase());
+        if (mKey) {
+          rval = e.asValueOrDefault(mKey, null);
+        }
+      }
+    }
+    return rval;
+  }
+
+  public static parseCsvToEnumArray<T>(enumeration: any, input: string): T[] {
+    const split: string[] = StringRatchet.trimToEmpty(input)
+      .split(',')
+      .map((s) => s.trim());
+    const rval: T[] = split.map((s) => EnumRatchet.keyToEnum<T>(enumeration, s)).filter((s) => !!s);
+    return rval;
+  }
+}

package/src/lang/error-handling-approach.ts

@@ -0,0 +1,6 @@
+export enum ErrorHandlingApproach {
+  PassThru = 'PassThru',
+  LogAndSwallow = 'LogAndSwallow',
+  Swallow = 'Swallow',
+  LogAndPassThru = 'LogAndPassThru',
+}

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

@@ -0,0 +1,25 @@
+import { ErrorRatchet } from './error-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#errorRatchet', function () {
+  test('should cast to error', async () => {
+    const e1: Error = new Error('test1');
+    const e2 = 'test2';
+
+    const e1p: Error = ErrorRatchet.asErr(e1);
+    const e2p: Error = ErrorRatchet.asErr(e2);
+    const en: Error = ErrorRatchet.asErr(null);
+
+    expect(en).toBeNull();
+    expect(e1p).toEqual(e1);
+    expect(e2p).not.toEqual(e2);
+    expect(e2p instanceof Error).toBeTruthy();
+  });
+
+  test('should correctly stringify', async () => {
+    const flag = 'test1';
+    const e1: Error = new Error(flag);
+    const out: string = ErrorRatchet.safeStringifyErr(e1);
+    expect(out).toEqual(flag);
+  });
+});

package/src/lang/error-ratchet.ts

@@ -0,0 +1,70 @@
+/*
+    Functions for working with errors
+*/
+
+import { Logger } from '../logger/logger.js';
+import { StringRatchet } from './string-ratchet.js';
+import { ErrorHandlingApproach } from './error-handling-approach.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+
+export class ErrorRatchet {
+  public static handleErrorByApproach(
+    err: any,
+    approach: ErrorHandlingApproach,
+    level: LoggerLevelName = LoggerLevelName.error,
+    formatMsg: string = 'Error: %s',
+  ) {
+    if (err && approach) {
+      if (approach === ErrorHandlingApproach.LogAndSwallow || approach === ErrorHandlingApproach.LogAndPassThru) {
+        Logger.logByLevel(level, formatMsg, err, err);
+      }
+      if (approach === ErrorHandlingApproach.PassThru || approach === ErrorHandlingApproach.LogAndPassThru) {
+        throw err;
+      }
+    } else {
+      Logger.error('Cannot handle error %s - %s, missing either error or approach', err, approach);
+    }
+  }
+
+  public static safeStringifyErr(err: any, log = true): string {
+    let rval = 'ERR WAS NULL';
+    if (err) {
+      if (err['message']) {
+        rval = err['message'];
+      } else {
+        try {
+          rval = JSON.stringify(err);
+        } catch (err2) {
+          Logger.error('Failed to json stringify: %s', err2);
+          rval = String(err);
+        }
+      }
+    }
+    if (log) {
+      Logger.error('%s', rval, err);
+    }
+    return rval;
+  }
+
+  // Mainly for Typescript 4.5+ where this is now any/unknown by default
+  public static asErr(input: any): Error {
+    let rval: Error = null;
+    if (input) {
+      if (input instanceof Error) {
+        rval = input;
+      } else {
+        rval = new Error('Force-Cast to error : ' + String(input));
+      }
+    }
+    return rval;
+  }
+
+  public static fErr(format: string, ...input: any[]): Error {
+    const msg: string = StringRatchet.format(format, ...input);
+    return new Error(msg);
+  }
+
+  public static throwFormattedErr(format: string, ...input: any[]): Error {
+    throw ErrorRatchet.fErr(format, ...input);
+  }
+}

package/src/lang/esm-ratchet.ts

@@ -0,0 +1,81 @@
+/**
+ * Functions to ease the transition to using ESM instead of CommonJS
+ */
+
+import url from 'url';
+import { ErrorRatchet } from './error-ratchet.js';
+import { Logger } from '../logger/logger.js';
+import { StringRatchet } from './string-ratchet.js';
+
+export class EsmRatchet {
+  private static readonly DYNAMIC_IMPORT_CACHE: Map<string, Promise<any>> = new Map<string, Promise<any>>();
+
+  public static fetchDirName(root: string): string {
+    if (!root) {
+      throw new Error('Need to provide root (should be import.meta.url)');
+    }
+    const rval: string = url.fileURLToPath(new URL('.', root));
+    return rval;
+  }
+
+  public static fetchFileName(root: string): string {
+    if (!root) {
+      throw new Error('Need to provide root (should be import.meta.url)');
+    }
+    const rval: string = url.fileURLToPath(root);
+    return rval;
+  }
+
+  public static async cachedTypedDynamicImport<T>(
+    libPath: string,
+    importName?: string,
+    requiredKeys?: string[],
+    swallowErrorIfMissing?: boolean,
+  ): Promise<T> {
+    const cacheKey: string = StringRatchet.trimToNull(importName) ? libPath + '__' + importName : libPath;
+    let rval: Promise<T> = EsmRatchet.DYNAMIC_IMPORT_CACHE.get(cacheKey);
+    if (!rval) {
+      rval = EsmRatchet.typedDynamicImport<T>(libPath, importName, requiredKeys, swallowErrorIfMissing);
+      if (rval) {
+        EsmRatchet.DYNAMIC_IMPORT_CACHE.set(cacheKey, rval);
+      }
+    }
+    return rval;
+  }
+
+  public static async typedDynamicImport<T>(
+    libPath: string,
+    importName?: string,
+    requiredKeys?: string[],
+    swallowErrorIfMissing?: boolean,
+  ): Promise<T> {
+    let rval: T;
+    try {
+      rval = await import(libPath);
+    } catch (err) {
+      if (swallowErrorIfMissing) {
+        Logger.debug('Cannot find library %s but swallow specified, returning null', libPath);
+        rval = null;
+      } else {
+        throw ErrorRatchet.fErr('Could not find the "%s" library : %s', libPath, err);
+      }
+    }
+    if (StringRatchet.trimToNull(importName)) {
+      if (rval[importName]) {
+        rval = rval[importName];
+      } else {
+        throw ErrorRatchet.fErr('Imported library %s, tried to load name %s but only found %j', libPath, importName, Object.keys(rval));
+      }
+    }
+
+    if (requiredKeys?.length && rval) {
+      const keys: string[] = Object.keys(rval);
+      requiredKeys.forEach((k) => {
+        if (!keys.includes(k)) {
+          throw ErrorRatchet.fErr('Failed to import "%s" - required keys are %j, but found %j', libPath, requiredKeys, keys);
+        }
+      });
+    }
+    return rval;
+  }
+}

package/src/lang/expiring-object.spec.ts

@@ -0,0 +1,56 @@
+import { ExpiringObject } from './expiring-object.js';
+import { PromiseRatchet } from './promise-ratchet.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#expiringObject', function () {
+  test('should default the object', async () => {
+    const expObject: ExpiringObject<number> = new ExpiringObject<number>({
+      initialValue: 7,
+      timeToLiveMS: 50_000,
+      logLevel: LoggerLevelName.info,
+    });
+    const val: number = await expObject.fetch();
+    expect(val).toEqual(7);
+  });
+
+  test('should expire the object', async () => {
+    const expObject: ExpiringObject<number> = new ExpiringObject<number>({
+      initialValue: 7,
+      timeToLiveMS: 100,
+      logLevel: LoggerLevelName.info,
+    });
+    const val: number = await expObject.fetch();
+    expect(val).toEqual(7);
+    await PromiseRatchet.wait(101);
+    const val2: number = await expObject.fetch();
+    expect(val2).toBeNull();
+  });
+
+  test('should regen the object', async () => {
+    const expObject: ExpiringObject<number> = new ExpiringObject<number>({
+      initialValue: 7,
+      timeToLiveMS: 100,
+      generator: async () => 8,
+      logLevel: LoggerLevelName.info,
+    });
+    const val: number = await expObject.fetch();
+    expect(val).toEqual(7);
+    await PromiseRatchet.wait(101);
+    const val2: number = await expObject.fetch();
+    expect(val2).toEqual(8);
+  });
+
+  test('should return time remaining', async () => {
+    const expObject: ExpiringObject<number> = new ExpiringObject<number>({
+      initialValue: 7,
+      timeToLiveMS: 10_000,
+      logLevel: LoggerLevelName.info,
+    });
+    const val: number = await expObject.fetch();
+    expect(val).toEqual(7);
+    const rem: number = await expObject.fetchCacheObjectTimeRemainingMS();
+    expect(rem).toBeGreaterThan(0);
+    expect(rem).toBeLessThanOrEqual(10_000);
+  });
+});

package/src/lang/expiring-object.ts

@@ -0,0 +1,84 @@
+/*
+  Wraps an object with an expiring wrapper
+ */
+
+import { Logger } from '../logger/logger.js';
+import { ErrorRatchet } from './error-ratchet.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+
+export class ExpiringObject<T> {
+  private _config: ExpiringObjectConfig<T>;
+  private _cacheObject: T;
+  private _lastUpdatedEpochMS: number;
+  private _timeRemainingMS: (lastUpdatedEpochMS: number) => Promise<number>;
+
+  constructor(inputConfig?: ExpiringObjectConfig<T>) {
+    this._config = Object.assign({}, this.defaultConfig(), inputConfig || {});
+    if (this._config.overrideTimeRemainingMS && this._config.timeToLiveMS) {
+      ErrorRatchet.throwFormattedErr('Cannot define both time to live and overrideTimeRemainingMS');
+    }
+    if (!this._config.overrideTimeRemainingMS && !this._config.timeToLiveMS) {
+      ErrorRatchet.throwFormattedErr('Must define exactly one of timeToLiveMS or overrideTimeRemainingMS');
+    }
+    if (this._config.initialValue) {
+      this.update(this._config.initialValue);
+    }
+    this._timeRemainingMS = this._config.overrideTimeRemainingMS || this.defaultTimeRemainingMS;
+  }
+
+  private defaultConfig(): ExpiringObjectConfig<T> {
+    const rval: ExpiringObjectConfig<T> = {
+      generator: null,
+      initialValue: null,
+      logLevel: LoggerLevelName.debug,
+      overrideTimeRemainingMS: null,
+      timeToLiveMS: 1_000 * 60, // Default TTL is 1 minute
+    };
+    return rval;
+  }
+
+  private async defaultTimeRemainingMS(lastUpdatedEpochMS: number): Promise<number> {
+    let rval = 0;
+    if (lastUpdatedEpochMS) {
+      const ageMS: number = new Date().getTime() - lastUpdatedEpochMS;
+      rval = Math.max(0, this._config.timeToLiveMS - ageMS);
+    }
+    return rval;
+  }
+
+  public update(newValue: T, doNotUpdateClock = false): void {
+    this._cacheObject = newValue;
+    if (!doNotUpdateClock) {
+      this._lastUpdatedEpochMS = new Date().getTime();
+    }
+    Logger.logByLevel(this._config.logLevel, 'Updated cache value to %j', newValue);
+  }
+
+  public async fetchCacheObjectTimeRemainingMS(): Promise<number> {
+    return this._timeRemainingMS(this._lastUpdatedEpochMS);
+  }
+
+  public async fetch(): Promise<T> {
+    const remainMS: number = await this._timeRemainingMS(this._lastUpdatedEpochMS);
+    if (!remainMS) {
+      this._cacheObject = null;
+      this._lastUpdatedEpochMS = null;
+    }
+    if (!this._cacheObject) {
+      if (this._config.generator) {
+        const newValue: T = await this._config.generator();
+        Logger.logByLevel(this._config.logLevel, 'Auto call to generator returned %j', newValue);
+        this.update(newValue);
+      }
+    }
+    return this._cacheObject;
+  }
+}
+
+export class ExpiringObjectConfig<T> {
+  timeToLiveMS?: number;
+  generator?: () => Promise<T>;
+  initialValue?: T;
+  logLevel?: LoggerLevelName;
+  overrideTimeRemainingMS?: (lastUpdatedEpochMS: number) => Promise<number>;
+}

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

@@ -0,0 +1,177 @@
+import { GeolocationRatchet, RatchetGeoLocation, RatchetLocationBounds, RatchetLocationBoundsMap } from './geolocation-ratchet.js';
+import fs from 'fs';
+import { NumberRatchet } from './number-ratchet.js';
+import path from 'path';
+import { EsmRatchet } from './esm-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#geolocationRatchet', function () {
+  test('should canonicalize', function () {
+    expect(GeolocationRatchet.combineBounds([])).toBeNull();
+    expect(GeolocationRatchet.combineBounds(null)).toBeNull();
+  });
+
+  test('should canonicalize', function () {
+    const bounds: RatchetLocationBounds = {
+      origin: {
+        lat: 4,
+        lng: 3,
+      },
+      extent: {
+        lat: 2,
+        lng: 5,
+      },
+    };
+
+    const result: RatchetLocationBounds = GeolocationRatchet.canonicalizeBounds(bounds);
+    expect(result.origin.lat).toEqual(2);
+    expect(result.origin.lng).toEqual(3);
+    expect(result.extent.lat).toEqual(4);
+    expect(result.extent.lng).toEqual(5);
+  });
+
+  /*
+          test('should generate the right distance', function() {
+              const whLat: number = 38.8976805;
+              const whLng: number = -77.0387238;
+
+              const senLat: number = 38.8956636;
+              const senLng: number = -77.0269061;
+
+              let result: number = GeolocationRatchet.distanceBetweenLocations(whLat, whLng, senLat, senLng);
+
+              result = parseFloat(result.toFixed(4));
+              expect(result).toEqual(.6506);
+          });
+
+          test('should generate the right offset', function() {
+              const lat: number = 37.26383;
+              const miles: number = 1;
+
+              const result1: number = GeolocationRatchet.degreeOfLatLngInMiles(lat);
+              expect(result1).toEqual(55.0509);
+
+              const result2: number = GeolocationRatchet.degreeOfLatLngInMiles(0);
+              expect(result2).toEqual(69.172);
+
+              const result3: number = GeolocationRatchet.degreeOfLatLngInMiles(lat*-1);
+              expect(result3).toEqual(55.0509);
+
+          });
+
+
+          test('should generate the right offset', function() {
+              const lat: number = 37.26383;
+              const miles: number = 1;
+
+              const result1: number = GeolocationRatchet.milesInDegLatLng(miles, lat);
+              expect(result1).toEqual(1/55.0509);
+
+              const result2: number = GeolocationRatchet.milesInDegLatLng(miles, 0);
+              expect(result2).toEqual(1/69.172);
+
+              const result3: number = GeolocationRatchet.milesInDegLatLng(miles, lat*-1);
+              expect(result3).toEqual(1/55.0509);
+
+          });
+
+
+          test('should cluster', function() {
+              const locations: RatchetGeoLocation[] = fs.readFileSync('test/data/sample_geo_locations.csv').toString()
+                  .split('\n').map(line => {
+                      const vals: string[] = line.split(',');
+                      if (!!vals && vals.length === 2) {
+                          return {
+                              lat: NumberRatchet.safeNumber(vals[0]),
+                              lng: NumberRatchet.safeNumber(vals[1])
+                          }
+                      } else {
+                          return null;
+                      }
+                  }).filter(s => !!s);
+              const bounds: RatchetLocationBounds[] = locations.map(l => GeolocationRatchet.locationToBounds(l, 10));
+              // Logger.info('Got: %j', locations);
+              const reduced: RatchetLocationBounds[] = GeolocationRatchet.clusterGeoBounds(bounds, 2, 5);
+
+              expect(reduced.length).toBeLessThanOrEqual(10);
+
+              Logger.info('Reduced %d to %d', bounds.length, reduced.length);
+
+
+          });
+
+
+
+
+
+          test('should build a bounds map', function() {
+              const locations: RatchetGeoLocation[] = fs.readFileSync('test/data/sample_geo_locations.csv').toString()
+                  .split('\n').map(line => {
+                      const vals: string[] = line.split(',');
+                      if (!!vals && vals.length === 2) {
+                          return {
+                              lat: NumberRatchet.safeNumber(vals[0]),
+                              lng: NumberRatchet.safeNumber(vals[1])
+                          }
+                      } else {
+                          return null;
+                      }
+                  }).filter(s => !!s);
+              const bounds: RatchetLocationBounds[] = locations.map(l => GeolocationRatchet.locationToBounds(l, 10));
+              const mapping: RatchetLocationBoundsMap = GeolocationRatchet.buildRatchetLocationBoundsMap(bounds);
+
+              expect(mapping).toBeTruthy();
+
+
+          });
+       */
+
+  test('should calc point in bounds', function () {
+    const input: string = fs
+      .readFileSync(path.join(EsmRatchet.fetchDirName(import.meta.url), '../../../../test-data/sample_geo_locations.csv'))
+      .toString();
+
+    const locations: RatchetGeoLocation[] = input
+      .split('\n')
+      .map((line) => {
+        const vals: string[] = line.split(',');
+        if (!!vals && vals.length === 2) {
+          return {
+            lat: NumberRatchet.safeNumber(vals[0]),
+            lng: NumberRatchet.safeNumber(vals[1]),
+          };
+        } else {
+          return null;
+        }
+      })
+      .filter((s) => !!s);
+    const bounds: RatchetLocationBounds[] = locations.map((l) => GeolocationRatchet.locationToBounds(l, 10));
+    const mapping: RatchetLocationBoundsMap = GeolocationRatchet.buildRatchetLocationBoundsMap(bounds);
+    const testPoint1: RatchetGeoLocation = locations[100];
+    const testPoint2: RatchetGeoLocation = { lng: 5, lat: 5 };
+    const testPoint3: RatchetGeoLocation = {
+      lat: 40.7566,
+      lng: -73.9887,
+    };
+    const testPoint4: RatchetGeoLocation = {
+      lat: 33.74616,
+      lng: -84.3708,
+    };
+    const testPoint5: RatchetGeoLocation = {
+      lat: 37.790336,
+      lng: -122.405399,
+    };
+
+    const pt1In: boolean = GeolocationRatchet.pointInAnyBound(testPoint1, bounds);
+    const pt2In: boolean = GeolocationRatchet.pointInAnyBound(testPoint2, bounds);
+    const pt3In: boolean = GeolocationRatchet.pointInAnyBound(testPoint3, bounds);
+    const pt4In: boolean = GeolocationRatchet.pointInAnyBound(testPoint4, bounds);
+    const pt5In: boolean = GeolocationRatchet.pointInRatchetLocationBoundsMap(testPoint5, mapping);
+
+    expect(pt1In).toBeTruthy();
+    expect(pt2In).toBeFalsy();
+    expect(pt3In).toBeTruthy();
+    expect(pt4In).toBeTruthy();
+    expect(pt5In).toBeTruthy();
+  });
+});