@orioro/util 0.0.0 → 0.2.0

package/jest.config.js

@@ -0,0 +1,6 @@
+export default {
+  transformIgnorePatterns: [
+    // Ignore all node_modules except those that need transpiling
+    '/node_modules/(?!dot-prop).+\\.js$'
+  ]
+};

package/package.json

@@ -1,37 +1,37 @@
 {
   "name": "@orioro/util",
-  "version": "0.0.0",
-  "description": "",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "scripts": {
-    "test": "jest --coverage",
-    "serve": "browser-sync start --server demo --watch --ignore **/*/index.js --no-ui --no-ghost-mode",
-    "dev-serve": "npm run serve & rollup --config ./rollup/dev.config.js --watch",
-    "dev-test": "jest --watch",
-    "dev-bundle": "rollup --config ./rollup/dev.config.js",
-    "build": "rm -rf dist && rollup --config ./rollup/build.config.js",
-    "prepublish": "npm run build"
+  "version": "0.2.0",
+  "packageManager": "yarn@4.0.2",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./*": "./dist/*"
   },
-  "author": "",
-  "license": "ISC",
   "publishConfig": {
     "access": "public"
   },
+  "license": "ISC",
+  "scripts": {
+    "build:watch": "rollup --config ./rollup.config.mjs --watch",
+    "build": "rollup --config ./rollup.config.mjs",
+    "test": "jest",
+    "dev": "jest --watch"
+  },
   "devDependencies": {
-    "@babel/core": "^7.1.2",
-    "@babel/plugin-proposal-object-rest-spread": "^7.0.0",
-    "@babel/preset-env": "^7.1.0",
-    "babel-core": "^7.0.0-bridge.0",
-    "babel-jest": "^23.6.0",
-    "browser-sync": "^2.24.7",
-    "jest": "^23.6.0",
-    "rollup": "^0.66.4",
-    "rollup-plugin-babel": "^4.0.3",
-    "rollup-plugin-commonjs": "^9.1.8",
-    "rollup-plugin-node-resolve": "^3.4.0"
+    "@orioro/dev": "0.0.0",
+    "@types/clone-deep": "^4.0.4",
+    "@types/jest": "^29.5.12",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "rollup": "^4.13.0"
   },
   "dependencies": {
-    "mingo": "^2.3.5"
+    "dot-prop": "^8.0.2",
+    "eventemitter3": "^5.0.1",
+    "fast-copy": "^3.0.2",
+    "traverse": "^0.6.9",
+    "type-fest": "^4.18.1"
   }
-}
+}

package/rollup.config.mjs

@@ -0,0 +1,6 @@
+import { rollupConfig } from '@orioro/dev/ts/rollup.mjs'
+
+export default rollupConfig((base) => ({
+  ...base,
+  plugins: [...base.plugins],
+}))

package/src/PromiseLikeEventEmitter/index.ts

@@ -0,0 +1,35 @@
+import EventEmitter from 'eventemitter3'
+
+export class PromiseLikeEventEmitter<
+  T,
+  EventTypes extends EventEmitter.ValidEventTypes = {},
+> extends EventEmitter<EventTypes> {
+  private promise: Promise<T>
+  public resolve!: (value: T | PromiseLike<T>) => void
+  public reject!: (reason?: any) => void
+
+  constructor() {
+    super()
+    this.promise = new Promise<T>((resolve, reject) => {
+      this.resolve = resolve
+      this.reject = reject
+    })
+  }
+
+  public then<TResult = T, TError = any>(
+    onFulfilled?: ((value: T) => TResult | PromiseLike<TResult>) | null,
+    onRejected?: ((reason: any) => TError | PromiseLike<TError>) | null,
+  ): Promise<TResult | TError> {
+    return this.promise.then(onFulfilled, onRejected)
+  }
+
+  public catch<TError = any>(
+    onRejected?: ((reason: any) => TError | PromiseLike<TError>) | null,
+  ): Promise<T | TError> {
+    return this.promise.catch(onRejected)
+  }
+
+  public finally(onFinally?: (() => void) | null | undefined): Promise<T> {
+    return this.promise.finally(onFinally)
+  }
+}

package/src/array/arrayChunk.ts

@@ -0,0 +1,7 @@
+export function arrayChunk<T>(array: T[], chunkSize: number): T[][] {
+  const chunks: T[][] = []
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize))
+  }
+  return chunks
+}

package/src/array/index.ts

@@ -0,0 +1 @@
+export * from './arrayChunk'

package/src/debug/debugFn/index.ts

@@ -0,0 +1,48 @@
+import { Merge } from 'type-fest'
+import { generateDeterministicId } from './util'
+import copy from 'fast-copy'
+
+type AnyFn = (...args: any[]) => any
+
+export type FnCallLog<FnType extends AnyFn = AnyFn> = {
+  type: 'call'
+  callId: string
+  fnName: string
+  args: Parameters<FnType>
+}
+
+export type FnResultLog<FnType extends AnyFn = AnyFn> = Merge<
+  FnCallLog<FnType>,
+  {
+    type: 'result'
+    result: ReturnType<FnType>
+  }
+>
+
+export type FnDebugLog<FnType extends AnyFn = AnyFn> =
+  | FnCallLog<FnType>
+  | FnResultLog<FnType>
+
+export function debugFn<FnType extends AnyFn = AnyFn>(
+  fnName: string,
+  fn: FnType,
+  logCall?: (log: FnCallLog<FnType>) => void,
+  logResult?: (log: FnResultLog<FnType>) => void,
+) {
+  return function (...args: Parameters<FnType>): ReturnType<FnType> {
+    const callId = generateDeterministicId([fnName, fn, ...args])
+
+    if (typeof logCall === 'function') {
+      // Deep clone args, so that we may detect mutations later on
+      logCall({ type: 'call', callId, args: copy(args), fnName })
+    }
+
+    const result = fn(...args)
+
+    if (typeof logResult === 'function') {
+      logResult({ type: 'result', callId, args, result, fnName })
+    }
+
+    return result
+  }
+}

package/src/debug/debugFn/util.ts

@@ -0,0 +1,27 @@
+function stringifyReplacer(key: string, value: any): any {
+  if (typeof value === 'function') {
+    // Convert functions to a consistent string representation
+    return `function:${value.toString()}`
+  }
+  return value
+}
+
+function simpleHash(str: string): string {
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i)
+    hash = (hash << 5) - hash + char
+    hash |= 0 // Convert to 32bit integer
+  }
+  // Ensure the hash is positive to avoid '-' signals
+  hash = Math.abs(hash)
+  return hash.toString(36) // Convert to base36 to ensure the result is alphanumeric
+}
+
+export function generateDeterministicId(args: any[]): string {
+  // Convert arguments to a JSON string using the custom replacer
+  const argsString = JSON.stringify(args, stringifyReplacer)
+
+  // Generate a simple hash of the string
+  return simpleHash(argsString)
+}

package/src/debug/deepFreeze.ts

@@ -0,0 +1,26 @@
+type AnyObjOrArray = any[] | { [key: string]: any }
+
+export function deepFreeze<T extends AnyObjOrArray = AnyObjOrArray>(
+  object: T,
+): T {
+  Object.freeze(object)
+
+  if (Array.isArray(object)) {
+    // Handle the array case
+    object.forEach((item) => {
+      if (item && typeof item === 'object' && !Object.isFrozen(item)) {
+        deepFreeze(item)
+      }
+    })
+  } else {
+    // Handle the object case
+    Object.keys(object).forEach((key) => {
+      const value = object[key]
+      if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        deepFreeze(value)
+      }
+    })
+  }
+
+  return object
+}

package/src/debug/index.ts

@@ -0,0 +1,3 @@
+export * from './wait'
+export * from './deepFreeze'
+export * from './debugFn'

package/src/debug/wait.ts

@@ -0,0 +1,14 @@
+export async function wait<ResultType = any>(
+  ms: number = 1000,
+  result?: ResultType | Error,
+): Promise<ResultType> {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      if (result instanceof Error) {
+        reject(result)
+      } else {
+        resolve(result as ResultType)
+      }
+    }, ms)
+  })
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from './PromiseLikeEventEmitter'
+export * from './debug'
+export * from './interpolate'
+export * from './maybeFn'
+export * from './promise'
+export * from './resolvePaths'
+export * from './switchValue'
+export * from './typeOf'
+export * from './validate'

package/src/interpolate/index.spec.ts

@@ -0,0 +1,20 @@
+import { interpolate } from './'
+
+describe('interpolate', () => {
+  test('basic', () => {
+    // const date = new Date('2024-05-02T08:42:51.303Z')
+    expect(
+      interpolate(
+        'Hello ${ name }! Today is ${now.day}, ${now.hour}:${now.min}',
+        {
+          name: 'World',
+          now: {
+            day: '02',
+            hour: '08',
+            min: '51',
+          },
+        },
+      ),
+    ).toEqual('Hello World! Today is 02, 08:51')
+  })
+})

package/src/interpolate/index.ts

@@ -0,0 +1,64 @@
+import { getProperty } from 'dot-prop'
+
+/**
+ * /\$\{\s*([\w$.]+)\s*\}/g
+ * ![](docs/resources/interpolation_regexp.png)
+ *
+ * RegExp used for matching interpolation expressions.
+ * Allows a non-interrupted sequence of alphanumeric chars ([A-Za-z0-9_]),
+ * dollar signs ($) and dots (.) wrapped in curly braces ({})
+ * with or without any number of whitespace chars (' ') between braces and the
+ * value identifier.
+ *
+ * Some resources on RegExp safety concerning RegExp Denial of Service (ReDOS)
+ * through Catastrophic backtracking, for future study and reference:
+ *
+ * - [Catastrophic backtracking](https://www.regular-expressions.info/catastrophic.html)
+ * - [Regular expression visualizer](https://github.com/CJex/regulex)
+ * - [Validator.js](https://github.com/validatorjs/validator.js)
+ * - [Stack Overflow interesting question](https://stackoverflow.com/questions/63127145/safe-regex-patterns-from-redos-attack)
+ * - [Catastrophic backtracking - JavaScript Info](https://javascript.info/regexp-catastrophic-backtracking#preventing-backtracking)
+ * - [Google re2 library](https://github.com/google/re2)
+ * - [Google re2 for Node.js - re2](https://github.com/uhop/node-re2/)
+ *
+ * @const {RegExp} INTERPOLATION_REGEXP
+ */
+const INTERPOLATION_REGEXP = /\$\{\s*([\w$.]+)\s*\}/g
+
+/**
+ * @function $stringInterpolate
+ * @param {String} template Basic JS template string like `${value.path}` value
+ *                          interpolation. It is possible to access nested properties
+ *                          through dot `.` notation. Keywords between braces are
+ *                          only interpreted as paths to the value. No logic
+ *                          supported: loops, conditionals, etc.
+ * @param {Object | Array} data Data context to be used for interpolation
+ */
+export function interpolate(
+  template: string,
+  data: { [key: string]: any } | any[],
+  { maxLength = 10000 }: { maxLength?: number } = {}
+): string {
+  if (template.length > maxLength) {
+    throw new Error(`Template exceeds maxLength ${maxLength}`)
+  }
+
+  return template.replace(INTERPOLATION_REGEXP, (_, path) => {
+    const value = getProperty(data, path)
+
+    switch (typeof value) {
+      case 'number': {
+        return value + ''
+      }
+      case 'string': {
+        return value
+      }
+      default: {
+        console.warn(
+          `Attempting to use non interpolatable value in interpolate ${value}`,
+        )
+        return ''
+      }
+    }
+  })
+}

package/src/maybeFn.ts

@@ -0,0 +1,3 @@
+export function maybeFn(input: any, ...args: any[]) {
+  return typeof input === 'function' ? input(...args) : input
+}

package/src/promise/batchFn.spec.ts

@@ -0,0 +1,92 @@
+import { SKIPPED, batchFn } from './batchFn'
+import { wait } from '../debug'
+
+describe('basic', () => {
+  test('basic', async () => {
+    const DELAY = 100
+    const BATCH_SIZE = 3
+    const entries = 'abcdefghijklmnopqrstuvwxyz1234567890'.split('')
+
+    const onItemStart = jest.fn()
+    const onItemSkip = jest.fn()
+    const onProgress = jest.fn()
+    const onBatchStart = jest.fn()
+    const onBatchProgress = jest.fn()
+
+    const batchToUpperCase = batchFn(
+      async (input: string) => {
+        await wait(DELAY)
+
+        if (input === 'd') {
+          throw new Error('ARBITRARY_INVALID_INPUT')
+        }
+
+        return input.toUpperCase()
+      },
+      {
+        batchSize: BATCH_SIZE,
+        skip: async (input: string) => {
+          switch (input) {
+            case 'k':
+            case 'w': {
+              return true
+            }
+            default: {
+              return false
+            }
+          }
+        },
+      },
+    )
+
+    const startTime = performance.now()
+    const promise = batchToUpperCase(entries)
+
+    promise.on('itemStart', onItemStart)
+    promise.on('itemSkip', onItemSkip)
+    promise.on('progress', onProgress)
+    promise.on('batchStart', onBatchStart)
+    promise.on('batchProgress', onBatchProgress)
+
+    const result = await promise
+    const endTime = performance.now()
+
+    expect(onItemStart).toHaveBeenCalledTimes(entries.length)
+    expect(onItemSkip).toHaveBeenCalledTimes(2)
+    expect(onBatchStart).toHaveBeenCalledTimes(
+      Math.ceil(entries.length / BATCH_SIZE),
+    )
+    expect(onBatchProgress).toHaveBeenCalledTimes(
+      Math.ceil(entries.length / BATCH_SIZE),
+    )
+
+    expect(result).toEqual(
+      entries.map((entry, index) => {
+        switch (entry) {
+          case 'd': {
+            return new Error('ARBITRARY_INVALID_INPUT')
+          }
+          case 'k':
+          case 'w': {
+            return SKIPPED
+          }
+          default: {
+            return entry.toUpperCase()
+          }
+        }
+      }),
+    )
+
+    //
+    // Expect the execution time to be approximately
+    // DELAY * batch count
+    //
+    const executionTime = endTime - startTime
+    expect(executionTime).toBeGreaterThan(
+      Math.ceil(entries.length / BATCH_SIZE) * DELAY,
+    )
+    expect(executionTime).toBeLessThan(
+      Math.ceil(entries.length / BATCH_SIZE) * DELAY + 100,
+    )
+  })
+})

package/src/promise/batchFn.ts

@@ -0,0 +1,176 @@
+import { arrayChunk } from '../array'
+import { promiseReduce } from './promiseReduce'
+import { PromiseLikeEventEmitter } from '../PromiseLikeEventEmitter'
+
+type BatchFnOptions = {
+  skip?: (input: any) => Promise<boolean> | boolean
+  batchSize?: number
+}
+
+type Batch = {
+  index: number
+  items: any[]
+}
+
+export const SKIPPED = Symbol()
+
+type EventTypes = {
+  batchStart: (data: { batch: Batch }) => void
+  batchProgress: (data: {
+    batch: Batch
+    progress: number
+    results: any[]
+  }) => void
+  itemStart: (data: { batch: Batch; item: any }) => void
+  itemSkip: (data: { batch: Batch; item: any }) => void
+  progress: (data: {
+    type: 'data' | 'skip' | 'error'
+    batch: Batch
+    item: any
+    result: any
+    progress: number
+  }) => void
+  results: (data: { results: any[] }) => void
+  error: (err: Error) => void
+}
+
+export function batchFn(
+  fn: (input: any) => Promise<any> | any,
+  { batchSize = 10, skip }: BatchFnOptions = {},
+) {
+  return function batchExec(
+    items: any[],
+  ): PromiseLikeEventEmitter<any[], EventTypes> {
+    const batches = arrayChunk(items, batchSize)
+
+    const promise = new PromiseLikeEventEmitter<any[], EventTypes>()
+
+    // const events = new EventEmitter<EventTypes>()
+
+    let progressCount = 0
+
+    const resultsPromise = promiseReduce(
+      batches,
+      async (acc, batchItems, index) => {
+        const batch = {
+          index,
+          items: batchItems,
+        }
+
+        promise.emit('batchStart', {
+          batch,
+        })
+
+        //
+        // A batch items are executed in parallell
+        //
+        const batchResults: any[] = await Promise.all(
+          batchItems.map(async (item) => {
+            try {
+              promise.emit('itemStart', {
+                batch,
+                item,
+              })
+
+              const itemSkip = await (typeof skip === 'function' && skip(item))
+
+              if (itemSkip) {
+                promise.emit('itemSkip', {
+                  batch,
+                  item,
+                })
+              }
+
+              const itemResult = itemSkip ? SKIPPED : await fn(item)
+
+              progressCount += 1
+
+              promise.emit('progress', {
+                type: itemSkip ? 'skip' : 'data',
+                batch,
+                progress: progressCount / items.length,
+                item,
+                result: itemResult,
+              })
+
+              return itemResult
+            } catch (err) {
+              progressCount += 1
+
+              promise.emit('progress', {
+                type: 'error',
+                batch,
+                progress: progressCount / items.length,
+                item,
+                result: err,
+              })
+
+              return err
+            }
+          }),
+        )
+
+        promise.emit('batchProgress', {
+          batch,
+          progress: batch.index + 1 / batches.length,
+          results: batchResults,
+        })
+
+        return [...acc, ...batchResults]
+      },
+      [] as any[],
+    )
+
+    resultsPromise.then(
+      (results) => {
+        promise.resolve(results)
+        promise.emit('results', {
+          results,
+        })
+      },
+      (err) => {
+        promise.reject(err)
+        promise.emit('error', err)
+      },
+    )
+
+    return promise
+  }
+}
+
+type ParsedBatchResults = {
+  results: any[]
+  errors: Error[]
+  skipped: any[]
+}
+
+export function parseBatchedResults(
+  inputs: any,
+  results: any[],
+): ParsedBatchResults {
+  return results.reduce(
+    (acc, result, index) => {
+      if (result === SKIPPED) {
+        return {
+          ...acc,
+          skipped: [...acc.skipped, inputs[index]],
+        }
+      } else if (result instanceof Error) {
+        return {
+          ...acc,
+          errors: [...acc.errors, result],
+        }
+      } else {
+        return {
+          ...acc,
+          results: [...acc.results, result],
+        }
+      }
+    },
+    {
+      results: [],
+      errors: [],
+      skipped: [],
+    } as ParsedBatchResults,
+  )
+}

package/src/promise/index.ts

@@ -0,0 +1,3 @@
+export * from './promiseReduce'
+export * from './resolveNestedPromises'
+export * from './batchFn'

package/src/promise/promiseReduce.ts

@@ -0,0 +1,15 @@
+export function promiseReduce<ItemType = any, AccType = any>(
+  inputArr: ItemType[],
+  reducerFn: (
+    acc: AccType,
+    input: ItemType,
+    index: number,
+  ) => AccType | Promise<AccType>,
+  initial: AccType,
+) {
+  return inputArr.reduce(
+    (prevPromise, input, index) =>
+      prevPromise.then((acc) => reducerFn(acc, input, index)),
+    Promise.resolve(initial) as Promise<AccType>,
+  )
+}