common-fp 0.1.0

package/dist/prepend.d.cts

@@ -0,0 +1,2 @@
+import { default as prepend } from '@common-fp/common-fp-types/prepend'
+export = prepend

package/dist/prepend.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/prepend'

package/dist/prepend.mjs

@@ -0,0 +1,13 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+
+const prepend = start => {
+  assertArgIsType(start, 'start', 'string', 'append')
+
+  return base => {
+    assertArgIsType(base, 'base', 'string', 'append')
+
+    return start + base
+  }
+}
+
+export default prepend

package/dist/prune-end.cjs

@@ -0,0 +1,18 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const validatePruneArg = require('./internal/validate-prune-arg.cjs')
+
+const pruneEnd = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let endIdx = aString.length - 1
+    while (charsToPrune.has(aString[endIdx])) endIdx -= 1
+
+    return aString.slice(0, endIdx + 1)
+  }
+}
+
+module.exports = pruneEnd

package/dist/prune-end.d.cts

@@ -0,0 +1,2 @@
+import { default as pruneEnd } from '@common-fp/common-fp-types/prune-end'
+export = pruneEnd

package/dist/prune-end.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/prune-end'

package/dist/prune-end.mjs

@@ -0,0 +1,18 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import validatePruneArg from './internal/validate-prune-arg.mjs'
+
+const pruneEnd = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let endIdx = aString.length - 1
+    while (charsToPrune.has(aString[endIdx])) endIdx -= 1
+
+    return aString.slice(0, endIdx + 1)
+  }
+}
+
+export default pruneEnd

package/dist/prune-start.cjs

@@ -0,0 +1,18 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const validatePruneArg = require('./internal/validate-prune-arg.cjs')
+
+const pruneStart = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let startIdx = 0
+    while (charsToPrune.has(aString[startIdx])) startIdx += 1
+
+    return aString.slice(startIdx)
+  }
+}
+
+module.exports = pruneStart

package/dist/prune-start.d.cts

@@ -0,0 +1,2 @@
+import { default as pruneStart } from '@common-fp/common-fp-types/prune-start'
+export = pruneStart

package/dist/prune-start.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/prune-start'

package/dist/prune-start.mjs

@@ -0,0 +1,18 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import validatePruneArg from './internal/validate-prune-arg.mjs'
+
+const pruneStart = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let startIdx = 0
+    while (charsToPrune.has(aString[startIdx])) startIdx += 1
+
+    return aString.slice(startIdx)
+  }
+}
+
+export default pruneStart

package/dist/prune.cjs

@@ -0,0 +1,21 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const validatePruneArg = require('./internal/validate-prune-arg.cjs')
+
+const prune = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let startIdx = 0
+    while (charsToPrune.has(aString[startIdx])) startIdx += 1
+
+    let endIdx = aString.length - 1
+    while (charsToPrune.has(aString[endIdx])) endIdx -= 1
+
+    return aString.slice(startIdx, endIdx + 1)
+  }
+}
+
+module.exports = prune

package/dist/prune.d.cts

@@ -0,0 +1,2 @@
+import { default as prune } from '@common-fp/common-fp-types/prune'
+export = prune

package/dist/prune.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/prune'

package/dist/prune.mjs

@@ -0,0 +1,21 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import validatePruneArg from './internal/validate-prune-arg.mjs'
+
+const prune = pruneArg => {
+  validatePruneArg(pruneArg)
+  const charsToPrune = new Set(pruneArg)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'prune')
+
+    let startIdx = 0
+    while (charsToPrune.has(aString[startIdx])) startIdx += 1
+
+    let endIdx = aString.length - 1
+    while (charsToPrune.has(aString[endIdx])) endIdx -= 1
+
+    return aString.slice(startIdx, endIdx + 1)
+  }
+}
+
+export default prune

package/dist/randomly-keep.cjs

@@ -0,0 +1,83 @@
+const assertArgIsInt = require('@common-fp/shared-internals/assert-arg-is-int')
+const getFn = require('@common-fp/shared-internals/get-fn')
+const getRandomInt = require('@common-fp/shared-internals/get-random-int')
+
+const randomlyKeep = num => {
+  assertArgIsInt(num, 'num', 'randomlyKeep', {
+    nonNegative: true,
+  })
+
+  return collection => {
+    const fn = getFn(typeToFn, collection, 'collection', 'randomlyKeep')
+    return fn(collection, num)
+  }
+}
+
+const typeToFn = {
+  array: randomlyKeep_array,
+  map: randomlyKeep_map,
+  object: randomlyKeep_object,
+  set: randomlyKeep_set,
+}
+
+function randomlyKeep_array(arr, num) {
+  const result = []
+
+  let numToTake = num
+  const valsToChooseFrom = [...arr]
+  while (numToTake > 0 && valsToChooseFrom.length) {
+    const randomIdx = getRandomInt(0, valsToChooseFrom.length - 1)
+    const pluckedVal = valsToChooseFrom.splice(randomIdx, 1)[0]
+    result.push(pluckedVal)
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_map(aMap, num) {
+  const result = new Map()
+
+  let numToTake = num
+  const keysToChooseFrom = [...aMap.keys()]
+  while (numToTake > 0 && keysToChooseFrom.length) {
+    const idx = getRandomInt(0, keysToChooseFrom.length - 1)
+    const randomKey = keysToChooseFrom.splice(idx, 1)[0]
+    result.set(randomKey, aMap.get(randomKey))
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_object(obj, num) {
+  const result = {}
+
+  let numToTake = num
+  const keysToChooseFrom = Object.keys(obj)
+  while (numToTake > 0 && keysToChooseFrom.length) {
+    const idx = getRandomInt(0, keysToChooseFrom.length - 1)
+    const randomKey = keysToChooseFrom.splice(idx, 1)[0]
+    result[randomKey] = obj[randomKey]
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_set(aSet, num) {
+  const result = new Set()
+
+  let numToTake = num
+  const valsToChooseFrom = [...aSet]
+  while (numToTake > 0 && valsToChooseFrom.length) {
+    const randomIdx = getRandomInt(0, valsToChooseFrom.length - 1)
+    const pluckedVal = valsToChooseFrom.splice(randomIdx, 1)[0]
+    result.add(pluckedVal)
+    numToTake -= 1
+  }
+
+  return result
+}
+
+module.exports = randomlyKeep

package/dist/randomly-keep.d.cts

@@ -0,0 +1,2 @@
+import { default as randomlyKeep } from '@common-fp/common-fp-types/randomly-keep'
+export = randomlyKeep

package/dist/randomly-keep.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/randomly-keep'

package/dist/randomly-keep.mjs

@@ -0,0 +1,83 @@
+import assertArgIsInt from '@common-fp/shared-internals/assert-arg-is-int'
+import getFn from '@common-fp/shared-internals/get-fn'
+import getRandomInt from '@common-fp/shared-internals/get-random-int'
+
+const randomlyKeep = num => {
+  assertArgIsInt(num, 'num', 'randomlyKeep', {
+    nonNegative: true,
+  })
+
+  return collection => {
+    const fn = getFn(typeToFn, collection, 'collection', 'randomlyKeep')
+    return fn(collection, num)
+  }
+}
+
+const typeToFn = {
+  array: randomlyKeep_array,
+  map: randomlyKeep_map,
+  object: randomlyKeep_object,
+  set: randomlyKeep_set,
+}
+
+function randomlyKeep_array(arr, num) {
+  const result = []
+
+  let numToTake = num
+  const valsToChooseFrom = [...arr]
+  while (numToTake > 0 && valsToChooseFrom.length) {
+    const randomIdx = getRandomInt(0, valsToChooseFrom.length - 1)
+    const pluckedVal = valsToChooseFrom.splice(randomIdx, 1)[0]
+    result.push(pluckedVal)
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_map(aMap, num) {
+  const result = new Map()
+
+  let numToTake = num
+  const keysToChooseFrom = [...aMap.keys()]
+  while (numToTake > 0 && keysToChooseFrom.length) {
+    const idx = getRandomInt(0, keysToChooseFrom.length - 1)
+    const randomKey = keysToChooseFrom.splice(idx, 1)[0]
+    result.set(randomKey, aMap.get(randomKey))
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_object(obj, num) {
+  const result = {}
+
+  let numToTake = num
+  const keysToChooseFrom = Object.keys(obj)
+  while (numToTake > 0 && keysToChooseFrom.length) {
+    const idx = getRandomInt(0, keysToChooseFrom.length - 1)
+    const randomKey = keysToChooseFrom.splice(idx, 1)[0]
+    result[randomKey] = obj[randomKey]
+    numToTake -= 1
+  }
+
+  return result
+}
+
+function randomlyKeep_set(aSet, num) {
+  const result = new Set()
+
+  let numToTake = num
+  const valsToChooseFrom = [...aSet]
+  while (numToTake > 0 && valsToChooseFrom.length) {
+    const randomIdx = getRandomInt(0, valsToChooseFrom.length - 1)
+    const pluckedVal = valsToChooseFrom.splice(randomIdx, 1)[0]
+    result.add(pluckedVal)
+    numToTake -= 1
+  }
+
+  return result
+}
+
+export default randomlyKeep

package/dist/replace-all-matches.cjs

@@ -0,0 +1,33 @@
+const assertArgTypeIsOneOf = require('@common-fp/shared-internals/assert-arg-type-is-one-of')
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const getType = require('@common-fp/shared-internals/get-type')
+
+const replaceAllMatches = (search, replacement) => {
+  validateInput(search, replacement)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'replaceAllMatches')
+
+    return aString.replaceAll(search, replacement)
+  }
+}
+
+function validateInput(search, replacement) {
+  const searchType = getType(search)
+  assertArgTypeIsOneOf(
+    searchType,
+    'search',
+    ['regexp', 'string'],
+    'replaceAllMatches'
+  )
+  assertArgIsType(replacement, 'replacement', 'string', 'replaceAllMatches')
+
+  if (searchType === 'regexp' && !search.global) {
+    const errMsg =
+      'When passing a regex to replaceAllMatches, it must be global.' +
+      " In other words, add the the 'g' flag."
+    throw new Error(errMsg)
+  }
+}
+
+module.exports = replaceAllMatches

package/dist/replace-all-matches.d.cts

@@ -0,0 +1,2 @@
+import { default as replaceAllMatches } from '@common-fp/common-fp-types/replace-all-matches'
+export = replaceAllMatches

package/dist/replace-all-matches.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/replace-all-matches'

package/dist/replace-all-matches.mjs

@@ -0,0 +1,33 @@
+import assertArgTypeIsOneOf from '@common-fp/shared-internals/assert-arg-type-is-one-of'
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import getType from '@common-fp/shared-internals/get-type'
+
+const replaceAllMatches = (search, replacement) => {
+  validateInput(search, replacement)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'replaceAllMatches')
+
+    return aString.replaceAll(search, replacement)
+  }
+}
+
+function validateInput(search, replacement) {
+  const searchType = getType(search)
+  assertArgTypeIsOneOf(
+    searchType,
+    'search',
+    ['regexp', 'string'],
+    'replaceAllMatches'
+  )
+  assertArgIsType(replacement, 'replacement', 'string', 'replaceAllMatches')
+
+  if (searchType === 'regexp' && !search.global) {
+    const errMsg =
+      'When passing a regex to replaceAllMatches, it must be global.' +
+      " In other words, add the the 'g' flag."
+    throw new Error(errMsg)
+  }
+}
+
+export default replaceAllMatches

package/dist/replace-first-match.cjs

@@ -0,0 +1,38 @@
+const assertArgTypeIsOneOf = require('@common-fp/shared-internals/assert-arg-type-is-one-of')
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const getType = require('@common-fp/shared-internals/get-type')
+
+const replaceFirstMatch = (search, replacement) => {
+  validateInput(search, replacement)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'replaceFirstMatch')
+
+    return aString.replace(search, replacement)
+  }
+}
+
+//
+//------------------//
+// Helper Functions //
+//------------------//
+
+function validateInput(search, replacement) {
+  const searchType = getType(search)
+  assertArgTypeIsOneOf(
+    searchType,
+    'search',
+    ['regexp', 'string'],
+    'replaceFirstMatch'
+  )
+  if (searchType === 'regexp' && search.global) {
+    const errMsg =
+      'When passing a regex to replaceFirstMatch, it cannot be global.' +
+      "  In other words, remove the 'g' flag."
+    throw new Error(errMsg)
+  }
+
+  assertArgIsType(replacement, 'replacement', 'string', 'replaceFirstMatch')
+}
+
+module.exports = replaceFirstMatch

package/dist/replace-first-match.d.cts

@@ -0,0 +1,2 @@
+import { default as replaceFirstMatch } from '@common-fp/common-fp-types/replace-first-match'
+export = replaceFirstMatch

package/dist/replace-first-match.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/replace-first-match'

package/dist/replace-first-match.mjs

@@ -0,0 +1,38 @@
+import assertArgTypeIsOneOf from '@common-fp/shared-internals/assert-arg-type-is-one-of'
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import getType from '@common-fp/shared-internals/get-type'
+
+const replaceFirstMatch = (search, replacement) => {
+  validateInput(search, replacement)
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'replaceFirstMatch')
+
+    return aString.replace(search, replacement)
+  }
+}
+
+//
+//------------------//
+// Helper Functions //
+//------------------//
+
+function validateInput(search, replacement) {
+  const searchType = getType(search)
+  assertArgTypeIsOneOf(
+    searchType,
+    'search',
+    ['regexp', 'string'],
+    'replaceFirstMatch'
+  )
+  if (searchType === 'regexp' && search.global) {
+    const errMsg =
+      'When passing a regex to replaceFirstMatch, it cannot be global.' +
+      "  In other words, remove the 'g' flag."
+    throw new Error(errMsg)
+  }
+
+  assertArgIsType(replacement, 'replacement', 'string', 'replaceFirstMatch')
+}
+
+export default replaceFirstMatch

package/dist/return-first-arg.cjs

@@ -0,0 +1,4 @@
+// also known as the 'identity' function
+const returnFirstArg = firstArg => firstArg
+
+module.exports = returnFirstArg

package/dist/return-first-arg.d.cts

@@ -0,0 +1,2 @@
+import { default as returnFirstArg } from '@common-fp/common-fp-types/return-first-arg'
+export = returnFirstArg

package/dist/return-first-arg.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/return-first-arg'

package/dist/return-first-arg.mjs

@@ -0,0 +1,4 @@
+// also known as the 'identity' function
+const returnFirstArg = firstArg => firstArg
+
+export default returnFirstArg

package/dist/return-undefined.cjs

@@ -0,0 +1,4 @@
+// also known as "no operation" or "noop"
+const returnUndefined = () => undefined
+
+module.exports = returnUndefined

package/dist/return-undefined.d.cts

@@ -0,0 +1,2 @@
+import { default as returnUndefined } from '@common-fp/common-fp-types/return-undefined'
+export = returnUndefined

package/dist/return-undefined.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/return-undefined'

package/dist/return-undefined.mjs

@@ -0,0 +1,4 @@
+// also known as "no operation" or "noop"
+const returnUndefined = () => undefined
+
+export default returnUndefined

package/dist/reverse.cjs

@@ -0,0 +1,8 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+
+const reverse = anArray => {
+  assertArgIsType(anArray, 'anArray', 'array', 'reverse')
+  return [...anArray].reverse()
+}
+
+module.exports = reverse

package/dist/reverse.d.cts

@@ -0,0 +1,2 @@
+import { default as reverse } from '@common-fp/common-fp-types/reverse'
+export = reverse

package/dist/reverse.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/reverse'

package/dist/reverse.mjs

@@ -0,0 +1,8 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+
+const reverse = anArray => {
+  assertArgIsType(anArray, 'anArray', 'array', 'reverse')
+  return [...anArray].reverse()
+}
+
+export default reverse

package/dist/round-to-nearest.cjs

@@ -0,0 +1,51 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const truncateToNChars = require('@common-fp/shared-internals/truncate-to-n-chars')
+
+const roundToNearest = precision => {
+  validatePrecision(precision)
+  const numPrecision =
+    precision.includes('.') ?
+      precision.length - 2 // 2 accounts for the leading "0."
+    : -precision.length + 1
+
+  return aNumber => {
+    assertArgIsType(aNumber, 'aNumber', 'number', 'roundToNearest')
+
+    /**
+     * implementation based off lodash.  Essentially we're
+     *   1. shifting the exponent based off the precision passed
+     *   2. rounding the shifted result
+     *   3. shifting it back and returning the value
+     *
+     * per lodash this gets around pesky floating point issues
+     */
+    const [base, exp] = aNumber.toExponential().split('e')
+    const shiftedNum = Math.round(base + 'e' + (Number(exp) + numPrecision))
+
+    const [shiftedBase, shiftedExp] = shiftedNum.toExponential().split('e')
+    return Number(shiftedBase + 'e' + (Number(shiftedExp) - numPrecision))
+  }
+}
+
+function validatePrecision(precision) {
+  assertArgIsType(precision, 'precision', 'string', 'roundToNearest')
+  if (precision.includes('.')) {
+    if (!/^0\.0{0,9}1$/.test(precision)) {
+      const truncatedPrecision = truncateToNChars(15, precision)
+      throw new Error(
+        'With a decimal, roundToNearest requires a precision passing the regex /^0\\.0{0,9}1$/' +
+          `\n  precision: ${truncatedPrecision}`
+      )
+    }
+  } else {
+    if (!/^10{0,9}$/.test(precision)) {
+      const truncatedPrecision = truncateToNChars(15, precision)
+      throw new Error(
+        'Without a decimal, roundToNearest requires a precision passing the regex /^10{0,9}$/' +
+          `\n  precision: ${truncatedPrecision}`
+      )
+    }
+  }
+}
+
+module.exports = roundToNearest

package/dist/round-to-nearest.d.cts

@@ -0,0 +1,2 @@
+import { default as roundToNearest } from '@common-fp/common-fp-types/round-to-nearest'
+export = roundToNearest

package/dist/round-to-nearest.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/round-to-nearest'