Wondering what’s next for npm?Check out our public roadmap! »

    @chocolatey/conjoin
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published

    conjoin

    Build Status NPM Version

    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(+ 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

    SEE ALSO

    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.

    Install

    npm i @chocolatey/conjoin

    DownloadsWeekly Downloads

    54

    Version

    3.0.1

    License

    Artistic-2.0

    Unpacked Size

    28.2 kB

    Total Files

    8

    Last publish

    Collaborators

    • avatar