anyfamily API reference

anyfamily is the whole any* family in one install: eight micro Intl tools behind a single import.

It has no API of its own. The published module is a re-export — under half a kilobyte of ESM that forwards eight names and their types. Every option, every default and every edge case belongs to the package the name came from, so this page is a map rather than a reference: each row below links to the real one.

import { anywhen, anyamount, anyword } from 'anyfamily'

anywhen(post.createdAt, { mode: 'relative' })   // "3 hours ago"
anyamount(1999, { mode: 'currency', currency: 'EUR' })  // "€1,999.00"
anyword.count('世界 test')                       // 2

npm install anyfamily
# or
pnpm add anyfamily
# or
yarn add anyfamily

Node 18+, ESM and CJS builds with types for both. The eight packages come along as dependencies; none of them depends on anything else.

Eight names, one per package. The bare call does the job; the extras hang off the same name. Follow a row for its options, its modes and its edge cases.

.parts means the same thing everywhere: the formatted output as an array of typed pieces, for when you need to style the currency symbol apart from the digits, or the unit apart from the number.

The eight are written to one convention, which is most of what makes them worth installing together. Learn one and the next is already familiar.

anywhen(date)                 // the string — the bare call is the job
anywhen.parts(date)           // the pieces, when you need to style them
anyword.count(text)           // the extras hang off the same name
anyword.truncate(text, 20)
anyamount.symbol('USD')
anylong.supported             // a flag, same rule

Three rules hold across all of them: one exported name per package; the locale is always an option called locale, taking a tag or a fallback chain; and nothing reads ambient state you did not pass, so the same arguments give the same output on a server and in a browser.

anywhen(date,  { locale: 'de-DE' })
anymany(items, { locale: ['xx-Nope', 'de-DE'] })   // fallback chain
anyplural(n, forms, { locale: 'ru' })

anylocale is the one exception, and deliberately: it answers questions about a locale rather than formatting in one, so the tag is its argument instead of an option.

The usual worry about a meta-package: does installing eight ship eight? Through a bundler, no.

The ESM build is a flat list of re-exports and the package sets sideEffects: false, so an import you never use has no reference left to keep it alive and the bundler drops it. Importing anywhen from anyfamily costs exactly what importing it from anywhen costs.

// what the published ESM build is, in full
import { anywhen } from 'anywhen'
import { anyamount } from 'anyamount'
// …six more
export { anywhen, anyamount, /* …six more */ }

Two honest caveats, both worth knowing before you rely on it:

None of this touches disk: node_modules holds all eight either way. Tree-shaking is about what reaches the browser.

Three ways in, same code behind all of them.

Switching is a find-and-replace on the import line — the names and signatures are identical either way, and mixing the two is fine as long as the versions agree.

- import { anywhen } from 'anywhen'
- import { anyamount } from 'anyamount'
+ import { anywhen, anyamount } from 'anyfamily'

The meta carries its own version and depends on the eight by caret range, not by exact pin.

"dependencies": {
  "anywhen":   "^2.0.1",
  "anyamount": "^2.0.1",
  …
  "anylocale": "^1.0.1"
}

So the meta's number does not track the packages' numbers, and it does not need to. A fix or a feature released in anywhen reaches you on your next install without anything happening here — the caret already covers it. The meta is republished for its own reasons: a new export to forward, a new type, a major that moves a range.

Every package in the family is released together through changesets, leaves before metas, so a published meta never points at a version that is not on npm yet.

The one number that is paired: anyfamily and anyfamily-react move together, so the same version of each wraps the same set of packages.

Five of the eight rest on Intl APIs that have been everywhere for years. Three are newer and can be missing on an older runtime, so they carry a flag — feature-detect with it rather than with a version table.

import { anylong, anyword, anylocale } from 'anyfamily'

anylong.supported     // Intl.DurationFormat
anyword.supported     // Intl.Segmenter
anylocale.supported   // Intl Locale Info

const elapsed = anylong.supported ? anylong(ms) : `${Math.round(ms / 1000)}s`

Where a flag is false, calling that package throws. The other five need no flag and have none — asking for anywhen.supported gets you undefined, not a warning.

Every option and result type from the eight is re-exported, so a typed wrapper needs one import instead of eight.

import type {
  Locale,
  AnywhenOptions, DateInput, Thresholds,
  AnyamountOptions, Unit, SingleUnit,
  AnymanyOptions, Sort,
  AnyaroundOptions, AnyaroundInfo, Display,
  AnylongOptions, DurationInput, DurationRecord,
  AnypluralOptions, Forms, PluralCategory,
  AnywordOptions, AnywordTruncateOptions, Granularity,
  AnylocaleInfo, Direction, Weekday,
} from 'anyfamily'

Names that repeat across packages are prefixed here, since they cannot all be Mode. The rule is mechanical — the package name in front, the original after.

Mode           -> AnywhenMode, AnyamountMode, AnyaroundMode
Style          -> AnywhenStyle, AnyamountStyle, AnyaroundStyle
SmartOptions   -> AnyamountSmartOptions, AnyaroundSmartOptions
CurrencyOptions-> AnyamountCurrencyOptions, AnyaroundCurrencyOptions

Locale is exported once, unprefixed: a tag or a fallback chain, structurally identical in all eight.

A few things worth knowing before you ship: