@chocolatey/conjoin

conjoin

• NAME
• FEATURES
• INSTALLATION
• SYNOPSIS
• DESCRIPTION
  • Why?
• TYPES
• EXPORTS
  • conjoin
  • conjoiner
• OPTIONS
  • last
  • map
  • pair
  • serial
  • with
  • $map
• DEVELOPMENT
• COMPATIBILITY
• SEE ALSO
• VERSION
• AUTHOR
• COPYRIGHT AND LICENSE

NAME

conjoin - a fast and flexible joiner for iterables and arrays with a tiny footprint

FEATURES

• works with ES6+ iterables, plain arrays and array-likes
• custom default, pair, and last separators
• currying (generate a function with baked-in options)
• no dependencies
• < 350 B minified + gzipped
• fully typed (TypeScript)
• CDN builds (UMD) - jsDelivr, unpkg

INSTALLATION

$ npm install @chocolatey/conjoin

SYNOPSIS

import { conjoin, conjoiner } from '@chocolatey/conjoin'

const array = ['foo', 'bar', 'baz', 'quux']
const iterable = new Set(array)
const single = array.slice(0, 1)
const pair = array.slice(0, 2)
const triple = array.slice(0, 3)

works with iterables, arrays, and array-likes

const arrayLike = { length: 4, ...array }

conjoin([])        // ""
conjoin(single)    // "foo"
conjoin(pair)      // "foo and bar"
conjoin(triple)    // "foo, bar and baz"
conjoin(array)     // "foo, bar, baz and quux"
conjoin(iterable)  // "foo, bar, baz and quux"
conjoin(arrayLike) // "foo, bar, baz and quux"

custom separators

conjoin(array, { with: '; ' })   // "foo; bar; baz and quux"
conjoin(array, { last: ' or ' }) // "foo, bar, baz or quux"
conjoin(pair, { pair: '/' })     // "foo/bar"

transform values

const map = (value, index) => JSON.stringify(value)
const $map = JSON.stringify

join(array, { map })  // '"foo", "bar", "baz" and "quux"'
join(array, { $map }) // '"foo", "bar", "baz" and "quux"'

currying

const map = it => it.toUpperCase()
const join = conjoiner({ map })

join(array)                    // "FOO, BAR, BAZ and QUUX"
join(array, { last: ' AND ' }) // "FOO, BAR, BAZ AND QUUX"

serial comma

const join = conjoiner({ serial: ' or ' })

join(pair)  // "foo or bar"
join(array) // "foo, bar, baz, or quux"

DESCRIPTION

This module exports a function which can be used to join array/iterable elements to form a string. The default and last separators can be customized, as well as the separator to use if there are only two elements. Options can be baked into the function by currying.

Why?

I often need to glue a list of values together with a default separator and a different separator for the last two values, e.g. for error messages:

const want = ['string', 'symbol', 'function']
const message = 'Invalid name: expected string, symbol or function'

Several libraries which support this are available on NPM, but most haven't been updated to work with iterables (they throw an error rather than converting), and many come with hardwired, immutable separators. This library aims to be at least as fast as the other implementations, and more flexible, while keeping the package size small.

TYPES

The following types are referenced in the descriptions below.

type Joinable<T> = ArrayLike<T> | Iterable<T>;

type Options<T> = {
    last?: string;
    map?: (value: T, index: number) => any;
    pair?: string;
    serial?: string | boolean;
    with?: string;
    $map?: (value: T) => any;
};

EXPORTS

conjoin

• Type: (values: Joinable<T>, options?: Options<T>) ⇒ string
• Alias: join

import { join } from '@chocolatey/conjoin'

join(single)                  // "foo"
join(pair)                    // "foo and bar"
join(array, { last: ' or ' }) // "foo, bar, baz or quux"

Takes an array-like or iterable and joins its values with the supplied separators.

conjoiner

• Type:
  • <U>(options?: Options<U>) ⇒ (values: Joinable<U>) ⇒ string
  • <U>(options?: Options<U>) ⇒ <T>(values: Joinable<T>, options: Options<T>) ⇒ string
• Alias: joiner

import { joiner } from '@chocolatey/conjoin'

const join = joiner({ last: ' or ' })

join(pair)                  // "foo or bar"
join(triple)                // "foo, bar or baz"
join(array, { with: '/' })  // "foo/bar/baz or quux"
join(array, { last: ': ' }) // "foo, bar, baz: quux"

Returns a function which takes an array/iterable and joins its values with the supplied separators. Options passed to the generated function override the options passed to the generator.

OPTIONS

The conjoin and conjoiner functions take the following options.

last

• Type: string
• Default: " and "

join(array)                   // "foo, bar, baz and quux"
join(array, { last: ' or ' }) // "foo, bar, baz or quux"

The separator to use between the last two values. Used if there are three or more values, or if there are two values and no pair separator is defined.

map

• Type: (value: T, index: number) => any
• Default: undefined

const repeat = (it, i) => String(it).repeat(i + 1)
const toInt = it => parseInt(it)

join(['a', 'b', 'c', 'd'], { map: repeat })    // "a, bb, ccc and dddd"
join(['1.', '2.', '3.', '4.'], { map: toInt }) // "1, 2, 3 and 4"

An optional function to transform each joined value. If supplied, the function is passed the value and its 0-based index within the array/iterable.

Note that functions like parseInt need to be wrapped to ensure the second argument passed to the map function (the index) isn't disallowed or misinterpreted. Rather than wrapping these functions manually, they can be wrapped automatically via the $map option.

pair

• Type: string
• Default: value of the last option

const join = conjoiner({ pair: ' or ', last: ', or ' })

join(single) // "foo"
join(pair)   // "foo or bar"
join(triple) // "foo, bar, or baz"
join(array)  // "foo, bar, baz, or quux"

The separator to use when there are exactly two values. If not supplied, it defaults to the value of the last option.

Can be used in conjunction with last to produce lists in the "Oxford comma" style.

serial

• Type: string | boolean
• Default: undefined

join(pair, { serial: ' or ' })                          // "foo or bar"
join(array, { serial: ' or ' })                         // "foo, bar, baz, or quux"
join(['eats', 'shoots', 'leaves'], { serial: ' and ' }) // "eats, shoots, and leaves"

This option provides a way to create an Oxford-comma-style list with a single option by taking advantage of the fact that the last separator in such lists is the pair separator with a comma prepended. Supplying a serial option of <string> is equivalent to providing a pair option of <string> and a last option of "," + <string>, e.g.:

before

const join = joiner({ pair: ' or ', last: ', or ' })

join(pair)  // "foo or bar"
join(array) // "foo, bar, baz, or quux"

after

const join = joiner({ serial: ' or ' })

join(pair)  // "foo or bar"
join(array) // "foo, bar, baz, or quux"

As a convenience, if the value is true, it's assigned the value of the last option, e.g.:

const array = ['eats', 'shoots', 'leaves']

conjoin(array)                   // "eats, shoots and leaves"
conjoin(array, { serial: true }) // "eats, shoots, and leaves"

const join = joiner({ last: ' or ' })

join(array)                      // "eats, shoots or leaves"
join(array, { serial: true })    // "eats, shoots, or leaves"

with

• Type: string
• Default: ", "

join(pair,   { with: '/' })     // "foo and bar"
join(triple, { with: '/' })     // "foo/bar and baz"
join(triple, { with: ' and ' }) // "foo and bar and baz"

The default separator, used for all but the only (pair) and last separators.

$map

• Type: (value: T) => any
• Default: undefined

const items = ['1.', '2)', '3:', '4/']

join(items, { $map: parseInt })       // "1, 2, 3 and 4"
join(array, { $map: JSON.stringify }) // '"foo", "bar", "baz" and "quux"'

An optional function to transform each joined value.

This is the same as the map option, but the function is automatically wrapped to ensure it's only passed a value rather than a value and its index. This is needed for functions that disallow or misinterpret additional arguments such as parseInt and JSON.stringify.

Assigning a function to $map is the same as assigning its wrapper to map, so the following are equivalent:

const map = it => JSON.stringify(it)

join(array, { map })                  // '"foo", "bar", "baz" and "quux"'
join(array, { $map: JSON.stringify }) // '"foo", "bar", "baz" and "quux"'

DEVELOPMENT

NPM Scripts

The following NPM scripts are available:

• build - compile the library for testing and save to the target directory
• build:release - compile the library for release and save to the target directory
• clean - remove the target directory and its contents
• doctoc - generate the README's TOC (table of contents)
• rebuild - clean the target directory and recompile the library
• test - recompile the library and run the test suite
• test:run - run the test suite
• typecheck - sanity check the library's type definitions

COMPATIBILITY

• Maintained Node.js versions and compatible browsers

SEE ALSO

• array-to-sentence
• join-array
• joinn
• oxford-comma-join
• oxford-join

VERSION

3.0.1

AUTHOR

chocolateboy

COPYRIGHT AND LICENSE

Copyright © 2020 by chocolateboy.

This is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.