common-fp 0.1.0

package/dist/truncate-to-n-lines.cjs

@@ -0,0 +1,58 @@
+const assertArgIsType = require('@common-fp/shared-internals/assert-arg-is-type')
+const assertArgIsInt = require('@common-fp/shared-internals/assert-arg-is-int')
+const eol = require('@common-fp/shared-internals/eol')
+
+const truncateToNLines = numLines => {
+  assertArgIsInt(numLines, 'numLines', 'truncateToNLines', {
+    nonNegative: true,
+  })
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'truncateToNLines')
+
+    const { lines, moreLinesExist } = getFirstNLines(numLines, aString)
+    if (moreLinesExist) {
+      if (numLines === 1) lines[0] += '...'
+      else lines.push('...')
+    }
+
+    return lines.join(eol)
+  }
+}
+
+// helper functions
+
+function getFirstNLines(numberOfLinesToGet, aString) {
+  const lines = numberOfLinesToGet > 0 ? [''] : []
+
+  let i = 0
+  let numLinesReached = false
+
+  while (!numLinesReached && i < aString.length) {
+    const currentCharacter = aString[i]
+    const nextCharacter = aString[i + 1]
+
+    if (isNewline(currentCharacter, nextCharacter)) {
+      if (currentCharacter === '\r') i += 1
+
+      numLinesReached = lines.length === numberOfLinesToGet
+      if (!numLinesReached) lines.push('')
+    } else lines[lines.length - 1] += aString[i]
+
+    i += 1
+  }
+
+  return {
+    lines,
+    moreLinesExist: numLinesReached && aString.length !== i,
+  }
+}
+
+function isNewline(currentCharacter, nextCharacter) {
+  return (
+    currentCharacter === '\n' ||
+    (currentCharacter === '\r' && nextCharacter === '\n')
+  )
+}
+
+module.exports = truncateToNLines

package/dist/truncate-to-n-lines.d.cts

@@ -0,0 +1,2 @@
+import { default as truncateToNLines } from '@common-fp/common-fp-types/truncate-to-n-lines'
+export = truncateToNLines

package/dist/truncate-to-n-lines.d.ts

@@ -0,0 +1 @@
+export { default } from '@common-fp/common-fp-types/truncate-to-n-lines'

package/dist/truncate-to-n-lines.mjs

@@ -0,0 +1,58 @@
+import assertArgIsType from '@common-fp/shared-internals/assert-arg-is-type'
+import assertArgIsInt from '@common-fp/shared-internals/assert-arg-is-int'
+import eol from '@common-fp/shared-internals/eol'
+
+const truncateToNLines = numLines => {
+  assertArgIsInt(numLines, 'numLines', 'truncateToNLines', {
+    nonNegative: true,
+  })
+
+  return aString => {
+    assertArgIsType(aString, 'aString', 'string', 'truncateToNLines')
+
+    const { lines, moreLinesExist } = getFirstNLines(numLines, aString)
+    if (moreLinesExist) {
+      if (numLines === 1) lines[0] += '...'
+      else lines.push('...')
+    }
+
+    return lines.join(eol)
+  }
+}
+
+// helper functions
+
+function getFirstNLines(numberOfLinesToGet, aString) {
+  const lines = numberOfLinesToGet > 0 ? [''] : []
+
+  let i = 0
+  let numLinesReached = false
+
+  while (!numLinesReached && i < aString.length) {
+    const currentCharacter = aString[i]
+    const nextCharacter = aString[i + 1]
+
+    if (isNewline(currentCharacter, nextCharacter)) {
+      if (currentCharacter === '\r') i += 1
+
+      numLinesReached = lines.length === numberOfLinesToGet
+      if (!numLinesReached) lines.push('')
+    } else lines[lines.length - 1] += aString[i]
+
+    i += 1
+  }
+
+  return {
+    lines,
+    moreLinesExist: numLinesReached && aString.length !== i,
+  }
+}
+
+function isNewline(currentCharacter, nextCharacter) {
+  return (
+    currentCharacter === '\n' ||
+    (currentCharacter === '\r' && nextCharacter === '\n')
+  )
+}
+
+export default truncateToNLines

package/dist/update.cjs

@@ -0,0 +1,74 @@
+const aOrAn = require('@common-fp/shared-internals/a-or-an')
+const assertArgHasValuesOfType = require('@common-fp/shared-internals/assert-arg-has-values-of-type')
+const assertArgTypeIsOneOf = require('@common-fp/shared-internals/assert-arg-type-is-one-of')
+const ct = require('@common-fp/shared-internals/common-types')
+const getIterator = require('@common-fp/shared-internals/get-iterator')
+const getType = require('@common-fp/shared-internals/get-type')
+
+const update = mapperFns => {
+  const mapperType = getType(mapperFns)
+  assertArgTypeIsOneOf(mapperType, 'mapperFns', ct.entryCollection, 'update')
+  assertArgHasValuesOfType(mapperFns, 'mapperFns', 'function', 'update')
+
+  return collection => {
+    const collType = getType(collection)
+    assertArgTypeIsOneOf(collType, 'collection', ct.entryCollection, 'update')
+    validateCollectionType(collType, mapperType)
+    const fn = typeToFn[collType]
+    const mapperFnsIterator = getIterator('entries', mapperFns, mapperType)
+    return fn(collection, mapperFnsIterator)
+  }
+}
+
+const typeToFn = {
+  array: update_array,
+  map: update_map,
+  object: update_object,
+}
+
+function update_array(arr, mapperFnsIterator) {
+  const result = [...arr]
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (Object.hasOwn(arr, key)) result[key] = fn(arr[key], key, arr)
+  }
+
+  return result
+}
+
+function update_map(aMap, mapperFnsIterator) {
+  const result = new Map(aMap)
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (aMap.has(key)) result.set(key, fn(aMap.get(key), key, aMap))
+  }
+
+  return result
+}
+
+function update_object(obj, mapperFnsIterator) {
+  const result = { ...obj }
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (Object.hasOwn(obj, key)) result[key] = fn(obj[key], key, obj)
+  }
+
+  return result
+}
+
+/**
+ * If mapperFns is an array or map, then collection must match.  This convention
+ * will prevent odd combinations like declaring an array of mappers intended for
+ * objects which happen to have number keys.
+ *
+ * Objects, on the other hand, will be the most common way to declare mappers
+ * - and should apply to array and map collections.
+ */
+function validateCollectionType(collType, mapperType) {
+  if (['array', 'map'].includes(mapperType) && collType !== mapperType) {
+    const msg = `update requires argument 'collection' to be ${aOrAn(mapperType)} since you passed ${aOrAn(mapperType)} for 'mapperFns'`
+    throw new Error(msg)
+  }
+}
+
+module.exports = update

package/dist/update.d.cts

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

package/dist/update.d.ts

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

package/dist/update.mjs

@@ -0,0 +1,74 @@
+import aOrAn from '@common-fp/shared-internals/a-or-an'
+import assertArgHasValuesOfType from '@common-fp/shared-internals/assert-arg-has-values-of-type'
+import assertArgTypeIsOneOf from '@common-fp/shared-internals/assert-arg-type-is-one-of'
+import * as ct from '@common-fp/shared-internals/common-types'
+import getIterator from '@common-fp/shared-internals/get-iterator'
+import getType from '@common-fp/shared-internals/get-type'
+
+const update = mapperFns => {
+  const mapperType = getType(mapperFns)
+  assertArgTypeIsOneOf(mapperType, 'mapperFns', ct.entryCollection, 'update')
+  assertArgHasValuesOfType(mapperFns, 'mapperFns', 'function', 'update')
+
+  return collection => {
+    const collType = getType(collection)
+    assertArgTypeIsOneOf(collType, 'collection', ct.entryCollection, 'update')
+    validateCollectionType(collType, mapperType)
+    const fn = typeToFn[collType]
+    const mapperFnsIterator = getIterator('entries', mapperFns, mapperType)
+    return fn(collection, mapperFnsIterator)
+  }
+}
+
+const typeToFn = {
+  array: update_array,
+  map: update_map,
+  object: update_object,
+}
+
+function update_array(arr, mapperFnsIterator) {
+  const result = [...arr]
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (Object.hasOwn(arr, key)) result[key] = fn(arr[key], key, arr)
+  }
+
+  return result
+}
+
+function update_map(aMap, mapperFnsIterator) {
+  const result = new Map(aMap)
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (aMap.has(key)) result.set(key, fn(aMap.get(key), key, aMap))
+  }
+
+  return result
+}
+
+function update_object(obj, mapperFnsIterator) {
+  const result = { ...obj }
+
+  for (const [key, fn] of mapperFnsIterator) {
+    if (Object.hasOwn(obj, key)) result[key] = fn(obj[key], key, obj)
+  }
+
+  return result
+}
+
+/**
+ * If mapperFns is an array or map, then collection must match.  This convention
+ * will prevent odd combinations like declaring an array of mappers intended for
+ * objects which happen to have number keys.
+ *
+ * Objects, on the other hand, will be the most common way to declare mappers
+ * - and should apply to array and map collections.
+ */
+function validateCollectionType(collType, mapperType) {
+  if (['array', 'map'].includes(mapperType) && collType !== mapperType) {
+    const msg = `update requires argument 'collection' to be ${aOrAn(mapperType)} since you passed ${aOrAn(mapperType)} for 'mapperFns'`
+    throw new Error(msg)
+  }
+}
+
+export default update

package/dist/with-dates-ascending.cjs

@@ -0,0 +1,3 @@
+const withDatesAscending = (left, right) => left.getTime() - right.getTime()
+
+module.exports = withDatesAscending

package/dist/with-dates-ascending.d.cts

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

package/dist/with-dates-ascending.d.ts

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

package/dist/with-dates-ascending.mjs

@@ -0,0 +1,3 @@
+const withDatesAscending = (left, right) => left.getTime() - right.getTime()
+
+export default withDatesAscending

package/dist/with-dates-descending.cjs

@@ -0,0 +1,3 @@
+const withDatesDescending = (left, right) => right.getTime() - left.getTime()
+
+module.exports = withDatesDescending

package/dist/with-dates-descending.d.cts

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

package/dist/with-dates-descending.d.ts

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

package/dist/with-dates-descending.mjs

@@ -0,0 +1,3 @@
+const withDatesDescending = (left, right) => right.getTime() - left.getTime()
+
+export default withDatesDescending

package/dist/with-numbers-ascending.cjs

@@ -0,0 +1,3 @@
+const withNumbersAscending = (left, right) => left - right
+
+module.exports = withNumbersAscending

package/dist/with-numbers-ascending.d.cts

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

package/dist/with-numbers-ascending.d.ts

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

package/dist/with-numbers-ascending.mjs

@@ -0,0 +1,3 @@
+const withNumbersAscending = (left, right) => left - right
+
+export default withNumbersAscending

package/dist/with-numbers-descending.cjs

@@ -0,0 +1,3 @@
+const withNumbersDescending = (left, right) => right - left
+
+module.exports = withNumbersDescending

package/dist/with-numbers-descending.d.cts

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

package/dist/with-numbers-descending.d.ts

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

package/dist/with-numbers-descending.mjs

@@ -0,0 +1,3 @@
+const withNumbersDescending = (left, right) => right - left
+
+export default withNumbersDescending

package/dist/with-strings-ascending.cjs

@@ -0,0 +1,4 @@
+const withStringsAscending = (left, right) =>
+  left.localeCompare(right, undefined, { sensitivity: 'case' })
+
+module.exports = withStringsAscending

package/dist/with-strings-ascending.d.cts

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

package/dist/with-strings-ascending.d.ts

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

package/dist/with-strings-ascending.mjs

@@ -0,0 +1,4 @@
+const withStringsAscending = (left, right) =>
+  left.localeCompare(right, undefined, { sensitivity: 'case' })
+
+export default withStringsAscending

package/dist/with-strings-descending.cjs

@@ -0,0 +1,4 @@
+const withStringsDescending = (left, right) =>
+  right.localeCompare(left, undefined, { sensitivity: 'case' })
+
+module.exports = withStringsDescending

package/dist/with-strings-descending.d.cts

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

package/dist/with-strings-descending.d.ts

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

package/dist/with-strings-descending.mjs

@@ -0,0 +1,4 @@
+const withStringsDescending = (left, right) =>
+  right.localeCompare(left, undefined, { sensitivity: 'case' })
+
+export default withStringsDescending

package/license.txt

@@ -0,0 +1,41 @@
+You can choose between either of the two licenses listed below
+
+WTFNMF
+Zero-Clause BSD
+
+This choice is offered since WTFNMF is not OSI approved.
+
+--------------------
+
+DO WHAT THE FUCK YOU WANT TO BUT IT'S NOT MY FAULT PUBLIC LICENSE
+Version 1, October 2013
+
+Copyright Phil Olson <philip.olson@pm.me>
+
+Everyone is permitted to copy and distribute verbatim or modified
+copies of this license document, and changing it is allowed as long
+as the name is changed.
+
+DO WHAT THE FUCK YOU WANT TO BUT IT'S NOT MY FAULT PUBLIC LICENSE
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. You just DO WHAT THE FUCK YOU WANT TO.
+
+1. Do not hold the author(s), creator(s), developer(s) or
+   distributor(s) liable for anything that happens or goes wrong
+   with your use of the work.
+
+--------------------
+
+Copyright Phil Olson <philip.olson@pm.me>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "common-fp",
+  "description": "FP utilities for the commoner",
+  "private": false,
+  "version": "0.1.0",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./*": {
+      "import": "./dist/*.mjs",
+      "require": "./dist/*.cjs",
+      "types": "./dist/*.d.ts"
+    },
+    "./internal/*": null,
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "fp",
+    "functional",
+    "functional programming",
+    "utilities",
+    "utils",
+    "common-fp"
+  ],
+  "author": "Phil Olson",
+  "license": "SEE LICENSE IN license.txt",
+  "peerDependenciesMeta": {
+    "common-fp-types": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@common-fp/shared-internals": "^0.1.0"
+  },
+  "peerDependencies": {
+    "common-fp-types": "^0.1.0"
+  }
+}

package/readme.md

@@ -0,0 +1,108 @@
+# Welcome to Common FP
+
+Before you start, I suggest visiting [common-fp.org](https://common-fp.org)
+instead. It has all the below information and looks better :)
+
+## Contents
+
+- [Install](#install)
+- [Use](#and-use)
+- [Why Choose Common FP?](#why-choose-common-fp)
+- [Why Not Choose Common FP?](#why-not-choose-common-fp)
+- [Related Links](#related-links)
+
+<br>
+
+## Install
+
+```sh
+$ npm i common-fp
+
+# using typescript?
+$ npm i common-fp-types
+```
+
+<br>
+
+## Use
+
+```js
+import { mapValues } from 'common-fp'
+
+const giveEveryoneAnApple = mapValues(numApples => numApples + 1)
+
+const applesPerPersonObj = {
+  jason: 2,
+  amy: 3,
+}
+
+const resultObj = giveEveryoneAnApple(applesPerPersonObj)
+console.log(resultObj)
+// a new object {
+//   jason: 3,
+//   amy: 4,
+// }
+
+// works on a Map as well (and arrays, and Sets)
+const applesPerPersonMap = new Map([
+  ['jason', 2],
+  ['amy', 3],
+])
+
+const resultMap = giveEveryoneAnApple(applesPerPersonMap)
+console.log(resultMap)
+// a new Map [
+//   ['jason', 3],
+//   ['amy', 4],
+// ]
+```
+
+<br>
+
+## Why Choose Common FP?
+
+You may find Common FP helpful if you...
+
+- are looking for a utility library that works on data types generically.
+  - For example, `mapValues` can map over the values of an array, object, Map or
+    Set, returning you a new instance of the type you passed in.
+- have run into limitations with chaining.
+  - Chaining feels natural until you want to call a function outside the
+    prototype. Then you either need to modify the prototype and account for
+    collisions or use a different approach, such as function composition.
+- are looking for a functional library but without the jargon.
+  - In my experience, some functional concepts are a little too foreign for the
+    broader community and pose a barrier to entry. Common FP attempts to lower
+    that barrier by doing things such as naming the utilities in plain English,
+    not currying, and keeping the source intended for the common devs' eyes.
+
+<br>
+
+## Why Not Choose Common FP?
+
+Common FP is not for everyone. You may prefer other libraries if you...
+
+- are content with your current utilities.
+  - Common FP may feel odd and unnecessary to you. That's fine! Keep writing
+    code in a way that's comfortable for you and your team.
+- are already familiar with functional programming.
+  - If [Ramda](https://ramdajs.com/) or [Sanctuary](https://sanctuary.js.org/)
+    makes sense to you, then Common FP may feel watered down and missing what
+    you like about functional programming.
+- prefer less opinionated code.
+  - Common FP is opinionated and will throw errors when you use it in an
+    unintended way. For example, [mapValues](https://common-fp.org/docs/mapValues)
+    requires you to pass a function, whereas Lodash provides a default. Calling
+    mapValues without a function doesn't make sense to me; thus, I enforce that
+    convention. This is one opinion of many that won't be shared by everyone -
+    which is okay :)
+
+<br>
+
+## Related Links
+
+- Learn more at [common-fp.org](https://common-fp.org)
+- [Reference documentation](https://common-fp.org/docs)
+- [Try it out in-browser](https://common-fp.org/try-it)
+- [View the source](../../pkg/common-fp-types) for `common-fp-types`
+- [Join our Discord](https://discord.gg/N8e7mtfwNM) or [raise a Github issue](https://github.com/common-fp/common-fp/issues/new) if you have questions, suggestions, or anything else.