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

package/src/2d/transformation-matrix.ts

@@ -0,0 +1,19 @@
+/*
+From https://graphicmaths.com/pure/matrices/matrix-2d-transformations/
+
+Matrix is the form:
+
+ a b u
+ c d v
+ 0 0 1
+
+ */
+
+export interface TransformationMatrix {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  u?: number;
+  v?: number;
+}

package/src/build/build-information.ts

@@ -0,0 +1,8 @@
+export interface BuildInformation {
+  version?: string;
+  hash?: string;
+  branch?: string;
+  tag?: string;
+  timeBuiltISO?: string;
+  notes?: string;
+}

package/src/build/ratchet-common-info.ts

@@ -0,0 +1,19 @@
+import { BuildInformation } from './build-information.js';
+
+export class RatchetInfo {
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static buildInformation(): BuildInformation {
+    const val: BuildInformation = {
+      version: 'LOCAL-SNAPSHOT',
+      hash: 'LOCAL-HASH',
+      branch: 'LOCAL-BRANCH',
+      tag: 'LOCAL-TAG',
+      timeBuiltISO: 'LOCAL-TIME-ISO',
+      notes: 'LOCAL-NOTES',
+    };
+    return val;
+  }
+}

package/src/histogram/histogram-entry.ts

@@ -0,0 +1,4 @@
+export interface HistogramEntry<T> {
+  item: T;
+  count: number;
+}

package/src/histogram/histogram.spec.ts

@@ -0,0 +1,25 @@
+import { Histogram } from './histogram.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#histogram', function () {
+  test('should count the values correctly', function () {
+    const histogram: Histogram<string> = new Histogram<string>();
+
+    histogram.update('a');
+    histogram.update('a');
+    histogram.update('b');
+    histogram.update('c');
+
+    expect(histogram.getTotalCount()).toEqual(4);
+
+    expect(histogram.countForValue('a')).toEqual(2);
+    expect(histogram.countForValue('b')).toEqual(1);
+    expect(histogram.countForValue('c')).toEqual(1);
+    expect(histogram.countForValue('d')).toEqual(0);
+
+    expect(histogram.percentForValue('a')).toEqual(0.5);
+    expect(histogram.percentForValue('b')).toEqual(0.25);
+    expect(histogram.percentForValue('c')).toEqual(0.25);
+    expect(histogram.percentForValue('d')).toEqual(0);
+  });
+});

package/src/histogram/histogram.ts

@@ -0,0 +1,61 @@
+import { HistogramEntry } from './histogram-entry.js';
+
+/**
+ * Implements a simple histogram (for each object, how many times does it appear)
+ */
+export class Histogram<T> {
+  private entries: HistogramEntry<T>[] = [];
+
+  public update(val: T, addValue = 1): void {
+    if (val) {
+      const entry: HistogramEntry<T> = this.entries.find((e) => e.item === val);
+      if (entry) {
+        entry.count += addValue;
+      } else {
+        this.entries.push({
+          item: val,
+          count: addValue,
+        } as HistogramEntry<T>);
+      }
+    }
+  }
+
+  public sort(): void {
+    this.entries.sort((a, b) => {
+      let rval: number = b.count - a.count;
+      if (rval === 0) {
+        rval = String(b.item).localeCompare(String(a.item));
+      }
+      return rval;
+    });
+  }
+
+  // No need for second level sort, since the same key can only be in there once
+  public sortKeys(): void {
+    this.entries.sort((a, b) => String(b.item).localeCompare(String(a.item)));
+  }
+
+  public reverse(): void {
+    this.entries.reverse();
+  }
+
+  public getEntries(): HistogramEntry<T>[] {
+    return this.entries;
+  }
+
+  public getTotalCount(): number {
+    let rval = 0;
+    this.entries.forEach((h) => (rval += h.count));
+    return rval;
+  }
+
+  public countForValue(val: T): number {
+    const entry: HistogramEntry<T> = this.entries.find((test) => test.item === val);
+    return entry ? entry.count : 0;
+  }
+
+  public percentForValue(val: T): number {
+    const total: number = this.getTotalCount();
+    return total === 0 ? 0 : this.countForValue(val) / total;
+  }
+}

package/src/jwt/common-jwt-token.ts

@@ -0,0 +1,17 @@
+/**
+ * This is meant to be an object that wraps up the standard JWT fields along with some other helpful fields
+ * in a type-safe way.  This is used in my Epsilon library, although it can be easily used elsewhere.
+ *
+ * In the case of a sudo situation, use the proxy field.  For example, if I am alice, but I am running as
+ * bob, bob should be in the user field and alice should be in the proxy field.  While this may seem somewhat
+ * backwards, it allows the majority of code to proceed as if bob is logged in, and only code that cares that a
+ * proxy is going on (e.g., audit trail code) needs to even check the proxy field.
+ *
+ * Note: other interfaces can extend this token to gain more functionality
+ */
+import { JwtTokenBase } from './jwt-token-base.js';
+
+export interface CommonJwtToken<T> extends JwtTokenBase {
+  user: T; // Data for the authenticated user
+  proxy: T; // Data for the proxy user (if any)
+}

package/src/jwt/expired-jwt-handling.ts

@@ -0,0 +1,5 @@
+export const enum ExpiredJwtHandling {
+  RETURN_NULL,
+  THROW_EXCEPTION,
+  ADD_FLAG,
+}

package/src/jwt/jwt-decode-only-ratchet.ts

@@ -0,0 +1,26 @@
+import { jwtDecode } from 'jwt-decode';
+import { ExpiredJwtHandling } from './expired-jwt-handling.js';
+import { JwtTokenBase } from './jwt-token-base.js';
+import { JwtPayloadExpirationRatchet } from './jwt-payload-expiration-ratchet.js';
+
+/**
+ * This is a stepped-down version of the original JwtRatchet which is
+ * now relocated to ratchet-node-only, as it depends on crypto and
+ * stream libraries that aren't available in the browser (and common
+ * is meant to work on both the browser and node).
+ *
+ * This can decode a token, and verify expiration, but it can't check
+ * the signature since it lacks the libraries (and keys!) for that.
+ */
+export class JwtDecodeOnlyRatchet {
+  public static decodeTokenNoVerify<T extends JwtTokenBase>(
+    token: string,
+    expiredHandling: ExpiredJwtHandling = ExpiredJwtHandling.RETURN_NULL,
+    inDecodeFuntion?: (val: string) => T,
+  ): T {
+    const decodeFunction: (val: string) => T = inDecodeFuntion ?? jwtDecode;
+    let decoded: T = decodeFunction(token);
+    decoded = JwtPayloadExpirationRatchet.processPayloadExpiration<T>(decoded, expiredHandling);
+    return decoded;
+  }
+}

package/src/jwt/jwt-payload-expiration-ratchet.ts

@@ -0,0 +1,45 @@
+import { ExpiredJwtHandling } from './expired-jwt-handling.js';
+import { JwtTokenBase } from './jwt-token-base.js';
+import { Logger } from '../logger/logger.js';
+import { DurationRatchet } from '../lang/duration-ratchet.js';
+
+export class JwtPayloadExpirationRatchet {
+  private static readonly EXPIRED_FLAG_NAME: string = '__jwtServiceExpiredFlag';
+
+  public static processPayloadExpiration<T extends JwtTokenBase>(payload: T, expiredHandling: ExpiredJwtHandling): T {
+    if (payload) {
+      const nowSeconds: number = Math.floor(Date.now() / 1000);
+      // A backwards compatibility hack since some of my old code used to incorrectly write the exp field in milliseconds
+      const expSeconds: number = payload?.exp && payload.exp > nowSeconds * 100 ? Math.floor(payload.exp / 1000) : payload?.exp;
+      const nbfSeconds: number = payload?.nbf && payload.nbf > nowSeconds * 100 ? Math.floor(payload.nbf / 1000) : payload?.nbf;
+
+      if ((expSeconds && nowSeconds >= expSeconds) || (nbfSeconds && nowSeconds <= nbfSeconds)) {
+        // Only do this if expiration is defined
+        const age: number = nowSeconds - expSeconds;
+        Logger.debug('JWT token expired or before NBF : on %d, %s ago', payload.exp, DurationRatchet.formatMsDuration(age * 1000));
+        switch (expiredHandling) {
+          case ExpiredJwtHandling.THROW_EXCEPTION:
+            throw new Error('JWT Token was expired');
+          case ExpiredJwtHandling.ADD_FLAG:
+            payload[JwtPayloadExpirationRatchet.EXPIRED_FLAG_NAME] = true;
+            break;
+          default:
+            payload = null;
+            break;
+        }
+      }
+    }
+    return payload;
+  }
+
+  public static hasExpiredFlag(ob: any): boolean {
+    return ob && ob[JwtPayloadExpirationRatchet.EXPIRED_FLAG_NAME] === true;
+  }
+
+  public static removeExpiredFlag(ob: any) {
+    if (ob) {
+      // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+      delete ob[JwtPayloadExpirationRatchet.EXPIRED_FLAG_NAME];
+    }
+  }
+}

package/src/jwt/jwt-token-base.ts

@@ -0,0 +1,14 @@
+/**
+ * Defines the common fields expected in a JWT token according to the RFC
+ * https://www.rfc-editor.org/rfc/rfc7519.html
+ */
+
+export interface JwtTokenBase {
+  iss?: string; // Issuer
+  sub?: string; // Subject
+  aud?: string; // Audience
+  exp?: number; // Expiration time
+  nbf?: number; // Not Before
+  iat?: number; // Issued at (time of creation)
+  jti?: string; // Unique ID for the token
+}

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

@@ -0,0 +1,79 @@
+import { ArrayRatchet, MatchReport } from './array-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+const sortedArr: any[] = [
+  {
+    n: 'test1',
+    v: 1,
+  },
+  {
+    n: 'test1',
+    v: 2,
+  },
+  {
+    n: 'test1',
+    v: 4,
+  },
+  {
+    n: 'test1',
+    v: 4,
+  },
+  {
+    n: 'test1',
+    v: 7,
+  },
+  {
+    n: 'test1',
+    v: 12,
+  },
+  {
+    n: 'test1',
+    v: 25,
+  },
+  {
+    n: 'test1',
+    v: 30,
+  },
+];
+
+describe('#extractSubarrayFromSortedByNumberField', function () {
+  test('should extract the subarray', function () {
+    const subArr1: any[] = ArrayRatchet.extractSubarrayFromSortedByNumberField(sortedArr, 'v', 5, 14);
+    expect(subArr1.length).toEqual(2);
+
+    const subArr2: any[] = ArrayRatchet.extractSubarrayFromSortedByNumberField(sortedArr, 'v', null, 4);
+    expect(subArr2.length).toEqual(4);
+
+    const subArr3: any[] = ArrayRatchet.extractSubarrayFromSortedByNumberField(sortedArr, 'v', 7, null);
+    expect(subArr3.length).toEqual(4);
+  });
+});
+
+describe('#compareTwoArrays', function () {
+  test('should create a match report', function () {
+    const arr1: string[] = ['a', 'b', 'c'];
+    const arr2: string[] = ['a', 'e', 'i', 'o', 'u'];
+
+    const report: MatchReport<string> = ArrayRatchet.compareTwoArrays(arr1, arr2, (a, b) => a.localeCompare(b));
+
+    expect(report).toBeTruthy();
+    expect(report.setOneOnly.length).toEqual(2);
+    expect(report.setTwoOnly.length).toEqual(4);
+    expect(report.matching.length).toEqual(1);
+  });
+});
+
+describe('#findSplit', function () {
+  test('should find the split', function () {
+    // All values past the split point should be larger than the target
+    const split10: number = ArrayRatchet.findSplit(sortedArr, 'v', 10);
+    const split4: number = ArrayRatchet.findSplit(sortedArr, 'v', 4);
+    const split0: number = ArrayRatchet.findSplit(sortedArr, 'v', 0);
+    const split32: number = ArrayRatchet.findSplit(sortedArr, 'v', 32);
+
+    expect(split10).toEqual(4);
+    expect(split4).toEqual(3);
+    expect(split0).toEqual(null);
+    expect(split32).toEqual(7);
+  });
+});

package/src/lang/array-ratchet.ts

@@ -0,0 +1,141 @@
+/*
+    Functions for working with arrays
+*/
+
+import { RequireRatchet } from './require-ratchet.js';
+import { MapRatchet } from './map-ratchet.js';
+
+export class ArrayRatchet {
+  public static wrapElementsInArray(input: any[]): any[][] {
+    return input.map((i) => [i]);
+  }
+
+  public static compareTwoArrays<T>(ar1: T[], ar2: T[], fn: ComparisonFunction<T>): MatchReport<T> {
+    ar1.sort(fn);
+    ar2.sort(fn);
+
+    let id1 = 0;
+    let id2 = 0;
+    const rval: MatchReport<T> = {
+      matching: [],
+      setOneOnly: [],
+      setTwoOnly: [],
+    };
+
+    while (id1 < ar1.length && id2 < ar2.length) {
+      const aVal: T = ar1[id1];
+      const pVal: T = ar2[id2];
+      const comp: number = fn(aVal, pVal);
+
+      if (comp === 0) {
+        rval.matching.push(aVal);
+        id1++;
+        id2++;
+      } else if (comp < 0) {
+        rval.setOneOnly.push(aVal);
+        id1++;
+      } else {
+        rval.setTwoOnly.push(pVal);
+        id2++;
+      }
+    }
+
+    if (id1 < ar1.length - 1) {
+      rval.setOneOnly = rval.setOneOnly.concat(ar1.slice(id1));
+    }
+    if (id2 < ar2.length - 1) {
+      rval.setTwoOnly = rval.setTwoOnly.concat(ar2.slice(id2));
+    }
+
+    return rval;
+  }
+
+  /**
+   * Given a sorted array of type T with a field named fieldName of type R, perform
+   * binary search to find the top and bottom bounds and extract the result
+   * @param input Array to select from
+   * @param fieldDotPath Path of the field
+   * @param minInclusive min value of field to include
+   * @param maxExclusive max value of field to include
+   */
+  public static extractSubarrayFromSortedByNumberField<T>(
+    input: T[],
+    fieldDotPath: string,
+    minInclusive: number,
+    maxExclusive: number,
+  ): T[] {
+    if (!input || input.length === 0) {
+      return input;
+    }
+
+    let bottomIdx: number = minInclusive === null ? 0 : ArrayRatchet.findSplit(input, fieldDotPath, minInclusive) || 0;
+    const topIdx: number = maxExclusive === null ? input.length : ArrayRatchet.findSplit(input, fieldDotPath, maxExclusive);
+
+    const bottomValue: number = MapRatchet.findValueDotPath(input[bottomIdx], fieldDotPath);
+    if (bottomIdx === input.length - 1 && bottomValue < minInclusive) {
+      // Highest value is still larger than min
+      return [];
+    }
+
+    // For min inclusive, have to handle this case
+    // Since it has to be able to handle the value===min case
+    if (bottomIdx < input.length && bottomIdx < topIdx && bottomValue < minInclusive) {
+      bottomIdx++;
+    }
+
+    return input.slice(bottomIdx, topIdx + 1);
+  }
+
+  /**
+   * Given a sorted array, find the location in the array where all the entries
+   * above that index have a value larger that the target (the index and under
+   * are less than or equal to the target)
+   * @param input Array to select from
+   * @param fieldName Name of the field
+   * @param target the value to search for
+   */
+  public static findSplit(input: any[], fieldDotPath: string, target: number): number {
+    RequireRatchet.notNullOrUndefined(input);
+    RequireRatchet.notNullOrUndefined(fieldDotPath);
+    RequireRatchet.notNullOrUndefined(target);
+
+    if (input.length === 0 || MapRatchet.findValueDotPath(input[0], fieldDotPath) > target) {
+      return null;
+    }
+
+    let min = 0;
+    let max: number = input.length;
+    let rval: number = null;
+
+    while (rval === null) {
+      const curIdx: number = Math.floor((min + max) / 2);
+      const curVal: number = MapRatchet.findValueDotPath(input[curIdx], fieldDotPath);
+      if (min === max || min === max - 1) {
+        rval = min;
+      } else if (curVal <= target) {
+        min = curIdx;
+      } else {
+        max = curIdx;
+      }
+    }
+    return rval;
+  }
+
+  public static shuffleInPlace(array: any[]): void {
+    if (array?.length) {
+      // Ignore nulls and non-arrays
+      for (let i = array.length - 1; i >= 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [array[i], array[j]] = [array[j], array[i]];
+      }
+    }
+  }
+}
+
+export type ComparisonFunction<T> = (t1: T, t2: T) => number;
+
+export interface MatchReport<T> {
+  matching: T[];
+  setOneOnly: T[];
+  setTwoOnly: T[];
+}

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

@@ -0,0 +1,48 @@
+import { Base64Ratchet } from './base64-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#base64', function () {
+  test('should parse a Uint8Array from base64', function () {
+    const result: Uint8Array = Base64Ratchet.base64StringToUint8Array('dGVzdHVzZXI6dGVzdHBhc3M=');
+    expect(result).toBeTruthy();
+    expect(result.length).toEqual(17);
+  });
+
+  test('should parse a string from base64', function () {
+    const result: string = Base64Ratchet.base64StringToString('dGVzdHVzZXI6dGVzdHBhc3M=');
+    expect(result).toBeTruthy();
+    expect(result.length).toEqual(17);
+  });
+
+  test('should round-trip a string', function () {
+    const testString = 'teststring';
+    const enc: string = Base64Ratchet.generateBase64VersionOfString(testString);
+    const result: string = Base64Ratchet.base64StringToString(enc);
+    expect(result).toBeTruthy();
+    expect(result).toEqual(testString);
+  });
+
+  test('should round-trip an object', function () {
+    const testOb: any = { a: 'teststring', b: 27 };
+    const enc: string = Base64Ratchet.safeObjectToBase64JSON(testOb);
+    const result: any = Base64Ratchet.safeBase64JSONParse(enc);
+    expect(result).toBeTruthy();
+    expect(result.a).toEqual(testOb.a);
+    expect(result.b).toEqual(testOb.b);
+  });
+
+  test('should work on special characters', function () {
+    const src = '✓ à la mode';
+    const b64: string = Base64Ratchet.generateBase64VersionOfString(src);
+    const back: string = Base64Ratchet.base64StringToString(b64);
+    expect(b64).toEqual('4pyTIMOgIGxhIG1vZGU=');
+    expect(back).toEqual(src);
+  });
+
+  test('should work on arbitrary data', function () {
+    const srcB64 = '7zo_JDdubAcOMnLtkoth_rLRc6Zj5RKRpNGv_nTVYY4';
+    const back: Uint8Array = Base64Ratchet.base64UrlStringToBytes(srcB64);
+    expect(back).toBeTruthy();
+    expect(back.length).toEqual(32);
+  });
+});