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

package/src/lang/time-zone-ratchet.spec.ts

@@ -0,0 +1,51 @@
+import { TimeZoneRatchet } from './time-zone-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+const tz: TimeZoneRatchet = TimeZoneRatchet.PACIFIC;
+
+describe('#currentHour', function () {
+  test('should return 0- 23', function () {
+    const result: number = tz.currentHour();
+    expect(result).toBeGreaterThanOrEqual(0);
+    expect(result).toBeLessThanOrEqual(23);
+  });
+});
+
+describe('#startOfTodayEpochSeconds', function () {
+  test('should never be more than now or more than 86400 seconds in the past', function () {
+    const now: number = tz.nowEpochSeconds(); //  Math.floor(new Date().getTime() / 1000);
+    const start: number = tz.startOfTodayEpochSeconds();
+    const result: number = now - start;
+    expect(result).toBeGreaterThanOrEqual(0);
+    expect(result).toBeLessThanOrEqual(86400);
+  });
+});
+
+describe('#dailySlotCount', function () {
+  test('should return 86400', function () {
+    const result: number = tz.dailySlotCount(1000);
+    expect(result).toEqual(86400);
+  });
+});
+
+describe('#currentTimeSlotIdx', function () {
+  // CAW 2020-11-01 : This actually fails on the day of spring forward/fall back because of the extra hour!
+  test.skip('should return same as current hour', function () {
+    const curHour: number = tz.currentHour();
+    const hourSlot: number = 1000 * 60 * 60;
+    const curSlot: number = tz.currentTimeSlotIdx(hourSlot);
+
+    expect(curSlot).toEqual(curHour);
+  });
+});
+
+describe('#matchingTimeSlotIdx', function () {
+  // CAW 2020-11-01 : This actually fails on the day of spring forward/fall back because of the extra hour!
+  test.skip('should return same as current hour', function () {
+    const curHour: number = tz.currentHour();
+    const hourSlot: number = 1000 * 60 * 60;
+    const matchSlot: number = tz.matchingTimeSlotIdx(new Date().getTime(), hourSlot);
+
+    expect(matchSlot).toEqual(curHour);
+  });
+});

package/src/lang/time-zone-ratchet.ts

@@ -0,0 +1,148 @@
+import { DateTime } from 'luxon';
+
+/*
+    Functions for working with dates specifically a given time zone
+    TODO: Refactor the 'today' slots to work in terms of the 'matching' slot endpoints
+*/
+
+export class TimeZoneRatchet {
+  public static PACIFIC = new TimeZoneRatchet('America/Los_Angeles');
+
+  constructor(private timezoneIanaName: string) {
+    if (!timezoneIanaName || timezoneIanaName.trim().length === 0) {
+      throw 'Timezone cannot be null or empty';
+    }
+  }
+
+  public get ianaName(): string {
+    return this.timezoneIanaName;
+  }
+
+  // Returns 0-23
+  public currentHour(): number {
+    const rval = DateTime.local().setZone(this.timezoneIanaName).hour;
+    return rval;
+  }
+
+  private toEpochSeconds(dt: DateTime) {
+    return Math.round(dt.toMillis() / 1000);
+  }
+
+  public nowEpochSeconds(): number {
+    return Math.floor(DateTime.local().setZone(this.timezoneIanaName).toSeconds());
+  }
+
+  // Returns midnight in the current timezone in epoch seconds
+  public startOfTodayEpochSeconds(): number {
+    const startOfToday = this.toEpochSeconds(
+      DateTime.local().setZone(this.timezoneIanaName).set({ hour: 0, minute: 0, second: 0, millisecond: 0 }),
+    );
+    return startOfToday;
+  }
+
+  // Returns midnight of the passed timestamp in the current timezone in epoch seconds
+  public startOfMatchingDayEpochSeconds(inputTS: number): number {
+    const startOfToday = this.toEpochSeconds(DateTime.fromMillis(inputTS).set({ hour: 0, minute: 0, second: 0, millisecond: 0 }));
+    return startOfToday;
+  }
+
+  // Returns midnight of the passed timestamp in the current timezone in epoch ms
+  public startOfMatchingDayEpochMS(inputTS: number): number {
+    return this.startOfMatchingDayEpochSeconds(inputTS) * 1000;
+  }
+
+  // Returns the start of the current hour in epoch seconds
+  public startOfCurrentHourEpochSeconds(): number {
+    const rval = this.toEpochSeconds(DateTime.local().setZone(this.timezoneIanaName).set({ minute: 0, second: 0, millisecond: 0 }));
+    return rval;
+  }
+
+  // Returns the start of the current minute in epoch seconds
+  public startOfCurrentMinuteEpochSeconds(): number {
+    const rval = this.toEpochSeconds(DateTime.local().setZone(this.timezoneIanaName).set({ second: 0, millisecond: 0 }));
+    return rval;
+  }
+
+  // Returns the start of the current second in epoch seconds
+  public startOfCurrentSecondEpochSeconds(): number {
+    const rval = this.toEpochSeconds(DateTime.local().setZone(this.timezoneIanaName).set({ millisecond: 0 }));
+    return rval;
+  }
+
+  // Returns midnight in the current timezone in epoch ms
+  public startOfTodayEpochMS(): number {
+    const startOfToday = DateTime.local().setZone(this.timezoneIanaName).set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).toMillis();
+    return startOfToday;
+  }
+
+  /**
+   * Returns the number of slots in a day (simple math)
+   * @param {number} slotWidthMs
+   * @returns {number} containing the number of slots in a day (last one may be partial)
+   */
+  public dailySlotCount(slotWidthMs: number): number {
+    return Math.ceil(86400000 / slotWidthMs);
+  }
+
+  /**
+   * Imagine a day cut into N 'slots', each slotWidthMS wide - then there are
+   * 86,400,000 / slotWidthMS slots available, indexed from 0 on up.  This function
+   * returns that index
+   * @param {number} slotWidthMs
+   * @returns {number} containing the current index
+   */
+  public currentTimeSlotIdx(slotWidthMs: number): number {
+    if (slotWidthMs < 1) {
+      throw new Error('Cannot process with slot less than one ms wide');
+    }
+
+    const startOfToday = this.startOfTodayEpochMS();
+    const now = new Date().getTime();
+    const delta = now - startOfToday;
+    const idx = Math.floor(delta / slotWidthMs);
+    return idx;
+  }
+
+  /**
+   * Imagine a day cut into N 'slots', each slotWidthMS wide - then there are
+   * 86,400,000 / slotWidthMS slots available, indexed from 0 on up.  This function
+   * returns that index
+   * @param timestamp Number of the epochMS to check
+   * @param slotWidthMs Number of the width of each slot in MS
+   */
+  public matchingTimeSlotIdx(timestamp: number, slotWidthMs: number): number {
+    if (slotWidthMs < 1) {
+      throw new Error('Cannot process with slot less than one ms wide');
+    }
+
+    const startOfDay = this.startOfMatchingDayEpochMS(timestamp);
+    const delta = timestamp - startOfDay;
+
+    const idx = Math.floor(delta / slotWidthMs);
+    return idx;
+  }
+
+  /**
+   * Given the definition of slotWidth and currentTimeSlotIdx from above, return the ms that is the
+   * start of the slot that "now" falls within.
+   * @param {number} slotWidthMs
+   * @returns {number}
+   */
+  public startOfCurrentSlotEpochMS(slotWidthMs: number): number {
+    const startOfToday = this.startOfTodayEpochMS();
+    const currentIdx = this.currentTimeSlotIdx(slotWidthMs);
+    return startOfToday + currentIdx * slotWidthMs;
+  }
+
+  /**
+   * Given the definition of slotWidth and currentTimeSlotIdx from above, return the ms that is the
+   * start of the slot that the passed timestamp falls within.
+   * @param {number} slotWidthMs
+   * @returns {number}
+   */
+  public startOfMatchingSlotEpochMS(timestamp: number, slotWidthMs: number): number {
+    const startOfDay = this.startOfMatchingDayEpochMS(timestamp);
+    const currentIdx = this.matchingTimeSlotIdx(timestamp, slotWidthMs);
+    return startOfDay + currentIdx * slotWidthMs;
+  }
+}

package/src/lang/timeout-token.spec.ts

@@ -0,0 +1,12 @@
+import { TimeoutToken } from './timeout-token.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#timeoutToken', function () {
+  test('should return the correct value for isTimeoutToken', function () {
+    const tt: TimeoutToken = new TimeoutToken('title', 20000);
+    const ntt: any = { a: 'b' };
+
+    expect(TimeoutToken.isTimeoutToken(tt)).toBeTruthy();
+    expect(TimeoutToken.isTimeoutToken(ntt)).toBeFalsy();
+  });
+});

package/src/lang/timeout-token.ts

@@ -0,0 +1,21 @@
+import { Logger } from '../logger/logger.js';
+import { LoggerLevelName } from '../logger/logger-level-name.js';
+
+export class TimeoutToken {
+  private __timeoutTokenFlagField = true;
+
+  constructor(
+    private title: string,
+    private timeoutMS: number,
+  ) {
+    Object.setPrototypeOf(this, TimeoutToken.prototype);
+  }
+
+  public writeToLog(logLevel: LoggerLevelName = LoggerLevelName.warn): void {
+    Logger.logByLevel(logLevel, 'Timed out after %d ms waiting for results of %s', this.timeoutMS, this.title);
+  }
+
+  public static isTimeoutToken(value: any): boolean {
+    return !!value && !!value['__timeoutTokenFlagField'];
+  }
+}

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

@@ -0,0 +1,22 @@
+import { Uint8ArrayRatchet } from './uint-8-array-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#Uint8Array', function () {
+  test('should combine uint8 arrays', function () {
+    const arrayOne: Uint8Array = new Uint8Array([2, 4, 8]);
+    const arrayTwo: Uint8Array = new Uint8Array([16, 32, 64]);
+    const result: Uint8Array = Uint8ArrayRatchet.mergeArrays([arrayOne, arrayTwo]);
+    expect(result).toBeTruthy();
+    expect(result.length).toEqual(6);
+    expect(result[0]).toEqual(2);
+    expect(result[5]).toEqual(64);
+  });
+
+  test('should compare arrays', function () {
+    const arrayOne: Uint8Array = new Uint8Array([2, 4, 8]);
+    const arrayOneX: Uint8Array = new Uint8Array([2, 4, 8]);
+    const arrayTwo: Uint8Array = new Uint8Array([16, 32, 64]);
+    expect(Uint8ArrayRatchet.deepEqual(arrayOne, arrayTwo)).toBeFalsy();
+    expect(Uint8ArrayRatchet.deepEqual(arrayOne, arrayOneX)).toBeTruthy();
+  });
+});

package/src/lang/uint-8-array-ratchet.ts

@@ -0,0 +1,48 @@
+// Uint8Array is the common denominator between node and web apis
+// https://medium.com/@naveenkumarasinghe/javascript-lost-in-binaries-buffer-blob-uint8array-arraybuffer-ed8d2b4de44a
+export class Uint8ArrayRatchet {
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  // Taken from https://stackoverflow.com/questions/49129643/how-do-i-merge-an-array-of-uint8arrays
+  public static mergeArrays(myArrays: Uint8Array[]): Uint8Array {
+    let rval: Uint8Array = null;
+    if (myArrays?.length) {
+      // Get the total length of all arrays.
+      let length = 0;
+      myArrays.forEach((item) => {
+        length += item.length;
+      });
+
+      // Create a new array with total length and merge all source arrays.
+      rval = new Uint8Array(length);
+      let offset = 0;
+      myArrays.forEach((item) => {
+        rval.set(item, offset);
+        offset += item.length;
+      });
+    }
+    return rval;
+  }
+
+  public static deepEqual(arr1: Uint8Array, arr2: Uint8Array): boolean {
+    let rval = false;
+    if (arr1 && arr2 && arr1.length === arr2.length) {
+      let mismatch = false;
+      for (let i = 0; i < arr1.length && !mismatch; i++) {
+        mismatch = arr1[i] !== arr2[i];
+      }
+      rval = !mismatch;
+    }
+    return rval;
+  }
+
+  // Taken from https://stackoverflow.com/a/22114687
+  public static deepCopy(src: Uint8Array): Uint8Array {
+    const tmp: ArrayBuffer = new ArrayBuffer(src.byteLength);
+    const dst: Uint8Array = new Uint8Array(tmp);
+    dst.set(new Uint8Array(src));
+    return dst;
+  }
+}

package/src/lang/web-stream-ratchet.spec.ts

@@ -0,0 +1,12 @@
+import { WebStreamRatchet } from './web-stream-ratchet.js';
+import { describe, expect, test } from 'vitest';
+
+describe('#WebStreamRatchet', function () {
+  test('should roundtrip from string to stream and back', async () => {
+    const input = 'test';
+    const r: ReadableStream = WebStreamRatchet.stringToWebReadableStream('test');
+    const out: string = await WebStreamRatchet.webReadableStreamToString(r);
+
+    expect(input).toEqual(out);
+  });
+});

package/src/lang/web-stream-ratchet.ts

@@ -0,0 +1,96 @@
+import { ErrorRatchet } from './error-ratchet.js';
+import { StringRatchet } from './string-ratchet.js';
+import { Uint8ArrayRatchet } from './uint-8-array-ratchet.js';
+import { Logger } from '../logger/logger.js';
+
+/**
+ * This class is specifically for dealing with web streams, NOT
+ * node streams (ie, ReadableStream and WriteableStream, NOT
+ * Readable and Writeable, and CERTAINLY not the FS based streams)
+ */
+export class WebStreamRatchet {
+  // Prevent instantiation
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  private constructor() {}
+
+  public static async webReadableStreamToUint8Array(stream: ReadableStream): Promise<Uint8Array> {
+    const out: Uint8Array[] = [];
+    const writer: WritableStream = new WritableStream(
+      {
+        async write(chunk, _controller): Promise<any> {
+          if (typeof chunk === 'string') {
+            out.push(StringRatchet.stringToUint8Array(chunk));
+          } else {
+            out.push(chunk);
+          }
+
+          return null;
+        },
+        abort(reason) {
+          ErrorRatchet.throwFormattedErr('StringWebWritableStream failure : %s', reason);
+        },
+      },
+      {
+        highWaterMark: 3,
+        size: () => 1,
+      },
+    );
+    try {
+      Logger.debug('Starting pipe');
+      await stream.pipeTo(writer, { preventAbort: true, preventCancel: true, preventClose: true });
+      Logger.debug('Completed pipe');
+      return Uint8ArrayRatchet.mergeArrays(out);
+    } catch (err) {
+      Logger.error('Caught error while trying to convert to array : %s', err, err);
+      throw err;
+    }
+  }
+  public static async webReadableStreamToString(stream: ReadableStream): Promise<string> {
+    const buf: Uint8Array = await WebStreamRatchet.webReadableStreamToUint8Array(stream);
+    return new TextDecoder().decode(buf);
+  }
+
+  public static stringToWebReadableStream(input: string): ReadableStream {
+    //if (typeof ReadableStream !== 'undefined') {
+    //  ErrorRatchet.throwFormattedErr('ReadableStream not supported on this platform');
+    // }
+
+    const rval: ReadableStream = new ReadableStream<string>(
+      {
+        start(controller) {
+          if (input) {
+            controller.enqueue(input); // May as well write it all
+          }
+          controller.close();
+          return null;
+        },
+      },
+      {
+        highWaterMark: input ? input.length : null,
+      },
+    );
+    return rval;
+  }
+
+  public static uint8ArrayToWebReadableStream(input: Uint8Array): ReadableStream {
+    //if (typeof ReadableStream !== 'undefined') {
+    //  ErrorRatchet.throwFormattedErr('ReadableStream not supported on this platform');
+    // }
+
+    const rval: ReadableStream = new ReadableStream<Uint8Array>(
+      {
+        start(controller) {
+          if (input) {
+            controller.enqueue(input); // May as well write it all
+          }
+          controller.close();
+          return null;
+        },
+      },
+      {
+        highWaterMark: input ? input.length : null,
+      },
+    );
+    return rval;
+  }
+}

package/src/logger/classic-single-line-log-message-formatter.ts

@@ -0,0 +1,19 @@
+import { LogMessage } from './log-message.js';
+import { LogMessageFormatter } from './log-message-formatter.js';
+import { LoggerMeta } from './logger-meta.js';
+import { StringRatchet } from '../lang/string-ratchet.js';
+
+export class ClassicSingleLineLogMessageFormatter implements LogMessageFormatter {
+  public formatMessage(msg: LogMessage, meta: LoggerMeta): string {
+    let tmp: string = null;
+
+    if (msg) {
+      tmp = '';
+      tmp += meta?.options?.trace ? meta.options.trace + ' ' : '';
+
+      tmp += '[' + msg.lvl + '] ';
+      tmp += StringRatchet.format(msg?.messageSource ?? '', ...(msg.subsVars || []));
+    }
+    return tmp;
+  }
+}

package/src/logger/log-message-builder.ts

@@ -0,0 +1,60 @@
+import { LoggerLevelName } from './logger-level-name.js';
+import { LogMessage } from './log-message.js';
+
+export class LogMessageBuilder {
+  private wrapped: LogMessage;
+
+  constructor(lvl: LoggerLevelName, messageSource?: string) {
+    if (!lvl) {
+      throw Error('Cannot set level to null/undefined');
+    }
+    this.wrapped = { lvl: lvl, timestamp: Date.now(), messageSource: messageSource };
+  }
+
+  public clone(): LogMessageBuilder {
+    const rval: LogMessageBuilder = new LogMessageBuilder(this.wrapped.lvl, this.wrapped.messageSource);
+    rval.wrapped = Object.assign({}, this.wrapped);
+    return rval;
+  }
+
+  public level(lvl: LoggerLevelName): LogMessageBuilder {
+    if (!lvl) {
+      throw Error('Cannot set level to null/undefined');
+    }
+    this.wrapped.lvl = lvl;
+    return this;
+  }
+
+  public timestamp(val: number): LogMessageBuilder {
+    if (!val) {
+      throw Error('Cannot set timestamp to null/undefined');
+    }
+    this.wrapped.timestamp = val;
+    return this;
+  }
+
+  public messageSource(val: string): LogMessageBuilder {
+    this.wrapped.messageSource = val;
+    return this;
+  }
+
+  public subVars(val: any[]): LogMessageBuilder {
+    this.wrapped.subsVars = val || [];
+    return this;
+  }
+
+  public params(val: Record<string, string | number | boolean>): LogMessageBuilder {
+    this.wrapped.params = val || {};
+    return this;
+  }
+
+  public p(name: string, value: string | number | boolean): LogMessageBuilder {
+    this.wrapped.params = this.wrapped.params || {};
+    this.wrapped.params[name] = value;
+    return this;
+  }
+
+  public toMessage(): LogMessage {
+    return Object.assign({}, this.wrapped);
+  }
+}

package/src/logger/log-message-format-type.ts

@@ -0,0 +1,11 @@
+// NOTE: This is a psuedo-enum to fix some issues with Typescript enums.  See: https://exploringjs.com/tackling-ts/ch_enum-alternatives.html for details
+
+export const LogMessageFormatType = {
+  ClassicSingleLine: 'ClassicSingleLine',
+  SingleLineNoLevel: 'SingleLineNoLevel',
+  StructuredJson: 'StructuredJson',
+
+  None: 'None',
+} as const;
+
+export type LogMessageFormatType = (typeof LogMessageFormatType)[keyof typeof LogMessageFormatType];

package/src/logger/log-message-formatter.ts

@@ -0,0 +1,6 @@
+import { LogMessage } from './log-message.js';
+import { LoggerMeta } from './logger-meta.js';
+
+export interface LogMessageFormatter {
+  formatMessage(msg: LogMessage, meta: LoggerMeta): string;
+}

package/src/logger/log-message-processor.ts

@@ -0,0 +1,6 @@
+import { LogMessage } from './log-message.js';
+
+export interface LogMessageProcessor {
+  label?(): string;
+  process(msg: LogMessage): LogMessage;
+}

package/src/logger/log-message.ts

@@ -0,0 +1,9 @@
+import { LoggerLevelName } from './logger-level-name.js';
+
+export interface LogMessage {
+  lvl: LoggerLevelName;
+  timestamp: number;
+  messageSource: string;
+  subsVars?: any[];
+  params?: Record<string, string | number | boolean>;
+}

package/src/logger/log-snapshot.ts

@@ -0,0 +1,6 @@
+import { LogMessage } from './log-message.js';
+
+export interface LogSnapshot {
+  logMessagesTruncated: number;
+  messages: LogMessage[];
+}