{"version":3,"file":"formatList.cjs","names":[],"sources":["../../src/string/formatList.ts"],"sourcesContent":["// The English forms `Intl.ListFormat` produces, used where the runtime has no\n// `Intl.ListFormat` at all. `pair` joins exactly two items, which several\n// languages punctuate differently from a longer list.\nconst FALLBACK: Record<string, { pair: string; sep: string; last: string }> = {\n  'conjunction-long': { pair: ' and ', sep: ', ', last: ', and ' },\n  'conjunction-short': { pair: ' & ', sep: ', ', last: ', & ' },\n  'conjunction-narrow': { pair: ', ', sep: ', ', last: ', ' },\n  'disjunction-long': { pair: ' or ', sep: ', ', last: ', or ' },\n  'disjunction-short': { pair: ' or ', sep: ', ', last: ', or ' },\n  'disjunction-narrow': { pair: ' or ', sep: ', ', last: ', or ' },\n  'unit-long': { pair: ', ', sep: ', ', last: ', ' },\n  'unit-short': { pair: ', ', sep: ', ', last: ', ' },\n  'unit-narrow': { pair: ' ', sep: ' ', last: ' ' },\n};\n\nexport interface FormatListOptions {\n  /** `'conjunction'` for \"and\", `'disjunction'` for \"or\", `'unit'` for neither. */\n  type?: 'conjunction' | 'disjunction' | 'unit';\n  /** How wordy the connector is. Defaults to `'long'`. */\n  style?: 'long' | 'short' | 'narrow';\n  /** The locale (default runtime locale). */\n  locale?: string;\n}\n\n/**\n * Joins a list of strings into readable prose.\n *\n * `items.join(', ')` gives `'a, b, c'`, which is not a sentence. This gives\n * `'a, b, and c'` — with the connector, the punctuation before it and the\n * separate form a two-item list takes, all of which differ by language and\n * none of which are worth hand-rolling.\n *\n * Where the runtime provides `Intl.ListFormat` it is used, and the result is\n * as correct as the runtime's locale data. Where it does not — some embedded\n * and edge runtimes ship without it — the English forms are produced instead,\n * so the shape of the output never changes with the host, only the language.\n *\n * @param {string[]} items The strings to join.\n * @param {FormatListOptions} [options] The options object.\n * @returns {string} The joined string, empty for an empty list.\n * @throws {RangeError} If `type` or `style` is not one of its allowed values.\n *\n * @example\n * formatList(['a', 'b', 'c']) //=> 'a, b, and c'\n * formatList(['a', 'b']) //=> 'a and b'\n * formatList(['a']) //=> 'a'\n * formatList([]) //=> ''\n *\n * @example\n * formatList(['a', 'b', 'c'], { type: 'disjunction' }) //=> 'a, b, or c'\n * formatList(['a', 'b', 'c'], { type: 'unit' }) //=> 'a, b, c'\n * formatList(['a', 'b', 'c'], { style: 'short' }) //=> 'a, b, & c'\n *\n * @example\n * formatList(['a', 'b', 'c'], { locale: 'de-DE' }) //=> 'a, b und c'\n */\nexport default function formatList(\n  items: string[] = [],\n  options: FormatListOptions = {},\n): string {\n  const { type = 'conjunction', style = 'long', locale } = options;\n\n  if (type !== 'conjunction' && type !== 'disjunction' && type !== 'unit') {\n    throw new RangeError(\n      \"The type option must be one of 'conjunction', 'disjunction', or 'unit'.\",\n    );\n  }\n\n  if (style !== 'long' && style !== 'short' && style !== 'narrow') {\n    throw new RangeError(\n      \"The style option must be one of 'long', 'short', or 'narrow'.\",\n    );\n  }\n\n  // Checked per call rather than once at import, so a polyfill loaded after\n  // this module is still picked up — and so the fallback can be exercised.\n  if (typeof Intl.ListFormat === 'function') {\n    return new Intl.ListFormat(locale, { type, style }).format(items);\n  }\n\n  if (items.length === 0) {\n    return '';\n  }\n  if (items.length === 1) {\n    return items[0];\n  }\n\n  const forms = FALLBACK[`${type}-${style}`];\n\n  if (items.length === 2) {\n    return items[0] + forms.pair + items[1];\n  }\n\n  return (\n    items.slice(0, -1).join(forms.sep) + forms.last + items[items.length - 1]\n  );\n}\n"],"mappings":"+FAGA,MAAM,EAAwE,CAC5E,mBAAoB,CAAE,KAAM,QAAS,IAAK,KAAM,KAAM,QAAS,EAC/D,oBAAqB,CAAE,KAAM,MAAO,IAAK,KAAM,KAAM,MAAO,EAC5D,qBAAsB,CAAE,KAAM,KAAM,IAAK,KAAM,KAAM,IAAK,EAC1D,mBAAoB,CAAE,KAAM,OAAQ,IAAK,KAAM,KAAM,OAAQ,EAC7D,oBAAqB,CAAE,KAAM,OAAQ,IAAK,KAAM,KAAM,OAAQ,EAC9D,qBAAsB,CAAE,KAAM,OAAQ,IAAK,KAAM,KAAM,OAAQ,EAC/D,YAAa,CAAE,KAAM,KAAM,IAAK,KAAM,KAAM,IAAK,EACjD,aAAc,CAAE,KAAM,KAAM,IAAK,KAAM,KAAM,IAAK,EAClD,cAAe,CAAE,KAAM,IAAK,IAAK,IAAK,KAAM,GAAI,CAClD,EA2CA,SAAwB,EACtB,EAAkB,CAAC,EACnB,EAA6B,CAAC,EACtB,CACR,GAAM,CAAE,OAAO,cAAe,QAAQ,OAAQ,UAAW,EAEzD,GAAI,IAAS,eAAiB,IAAS,eAAiB,IAAS,OAC/D,MAAU,WACR,yEACF,EAGF,GAAI,IAAU,QAAU,IAAU,SAAW,IAAU,SACrD,MAAU,WACR,+DACF,EAKF,GAAI,OAAO,KAAK,YAAe,WAC7B,OAAO,IAAI,KAAK,WAAW,EAAQ,CAAE,OAAM,OAAM,CAAC,CAAC,CAAC,OAAO,CAAK,EAGlE,GAAI,EAAM,SAAW,EACnB,MAAO,GAET,GAAI,EAAM,SAAW,EACnB,OAAO,EAAM,GAGf,IAAM,EAAQ,EAAS,GAAG,EAAK,GAAG,KAMlC,OAJI,EAAM,SAAW,EACZ,EAAM,GAAK,EAAM,KAAO,EAAM,GAIrC,EAAM,MAAM,EAAG,EAAE,CAAC,CAAC,KAAK,EAAM,GAAG,EAAI,EAAM,KAAO,EAAM,EAAM,OAAS,EAE3E"}