atomic-fns 1.1.7 → 2.0.0

package/README.md

@@ -1,100 +1,445 @@
 # atomic-fns
 
-[Read the Docs](https://atomic-stack.github.io/atomic-fns/)
+A utility library with no runtime dependencies that fills the gaps the platform leaves: collection helpers and data structures, object paths, deep equality and cloning, exact decimal arithmetic, array operations, function and async helpers, strings, numbers, ids, hashing and encoding.
 
-## Like Lodash, but in TypeScript and for ESNext.
+Install from npm with `npm install atomic-fns`, or from JSR with `deno add jsr:@atomic-stack/atomic-fns`.
 
-Stop shipping code built for browsers from 2015.
+## Import
 
-You may prefer this library because:
+```ts
+import { Decimal, keys, Heap } from 'atomic-fns'
+import { SortedMap } from 'atomic-fns/collections'
+```
+
+Every export is available from the root and its area subpath. [docs/design.md](https://github.com/adrian2x/atomic-fns/blob/main/docs/design.md) describes the API and its rules.
+
+Supports Node `^24.22.3 || >=26.13.1`, Deno, Bun, browsers at Baseline and workers. Published types support TypeScript 6.0 and later.
+
+The 1.x line lives on the [`1.x` branch](https://github.com/adrian2x/atomic-fns/tree/1.x).
+
+## Collections
+
+Sorted maps and sets, trees, heap, deque, LRU cache, trie, frozen set and bisect: the data structures the platform does not ship. No dependencies, no Node APIs.
+
+### Conventions
+
+- Classes use `Map` and `Set` method names where the concept matches: `get`, `set`, `has`, `delete`, `clear`, `size`, `keys`, `values`, `entries`, `forEach(callback(value, key, collection))` and `[Symbol.iterator]`. `Deque` follows Array's names instead: `push`, `pop`, `shift`, `unshift`, `at`, `set(index, value)` and `includes`.
+- Sorted structures and the bisect functions take an optional comparator `(a, b) => number`. The default orders numbers and bigints by value (compared exactly with each other) and strings by UTF-16 code units, as `<` does. `NaN` throws `RangeError`; mixed strings and numbers, `null`, `undefined` and every other value throw `TypeError` asking for a comparator. Keys the comparator calls equal are the same key.
+- `Heap`, `Deque` and `FrozenSet` membership is SameValueZero, as in `Set` and `includes`.
+- Errors are native `TypeError` and `RangeError`, never custom classes.
+
+### Ordered maps and sets
+
+```ts
+import { SortedMap, SortedSet, SplayTree } from 'atomic-fns/collections'
+
+const scores = new SortedMap([
+  ['carol', 7],
+  ['alice', 9]
+])
+scores.set('bob', 8)
+;[...scores.keys()] // ['alice', 'bob', 'carol']
+scores.at(-1) // ['carol', 7]
+scores.rank('bob') // 1
+scores.ceiling('b') // ['bob', 8]
+scores.entriesBetween('a', 'c') // [['alice', 9], ['bob', 8]]
+scores.removeRange('a', 'b') // 1 (alice)
+const snapshot = scores.clone() // O(1), copy-on-write
+
+const ids = new SortedSet([30, 10, 20])
+ids.higher(10) // 20
+
+const byDate = new SortedMap<Date, string>(undefined, (a, b) => a.getTime() - b.getTime())
+```
+
+`SortedMap` is a copy-on-write B+ tree with subtree counts: lookups, `at` and `rank` take O(log n), range queries O(log n + k), and `updateRange` and `removeRange` are atomic, so a throwing callback or comparator leaves the map unchanged. A comparator that returns a non-finite number, or does not return 0 for a key against itself, is rejected before anything changes. `SortedSet` has the same ordered queries over values (`first`, `last`, `lower`, `higher`, `floor`, `ceiling`, `at`, `rank`, `valuesBetween`). `SplayTree` is an ordered map on a randomized splay tree, for skewed access patterns: `get` and `has` move the key they find to the root with probability 0.5, and `firstKey`, `lastKey`, `lower` and `higher` always do.
+
+### Heap, Deque, LRUCache
+
+```ts
+import { Deque, Heap, LRUCache } from 'atomic-fns/collections'
+
+const tasks = new Heap([5, 1, 3]) // pass (a, b) => b - a for a max-heap
+tasks.pop() // 1
+
+const recent = new Deque<number>([], { maxlen: 3 })
+recent.push(1, 2, 3, 4) // 3, the new size
+;[...recent] // [2, 3, 4]
+recent.unshift(0) // 3
+;[...recent] // [0, 2, 3]
+
+const cache = new LRUCache<string, string>(100)
+cache.set('/a', '<html>')
+cache.get('/a') // refreshes recency; has() does not
+```
+
+### Trie and FrozenSet
+
+```ts
+import { FrozenSet, Trie } from 'atomic-fns/collections'
+
+const words = new Trie(['car', 'cart', 'cat'])
+;[...words.withPrefix('car')] // ['car', 'cart']
+
+const roles = new FrozenSet(['admin', 'editor'])
+roles.add('guest') // throws TypeError
+```
 
-* **TypeScript & docs**: Includes type declaration files and js with JSDocs for best in class experience.
-* **Zero deps**: Built from scratch with no runtime dependencies or polyfills.
-* **ESNext**: Uses modern idiomatic syntax, data structures, and control flow techniques.
-* **Modular**: Pick what you need. Supports tree-shaking, no side effects, and works with all bundlers.
-* **Lazy**: Leverage generators, iterators, and functional composition.
-* **Tests**: All modules have comprehensive test suites and 100% test coverage.
+### Bisect
 
-## Docs
+```ts
+import { binarySearch, bisectLeft, bisectRight, insort } from 'atomic-fns/collections'
 
-📖 Available at [atomic-fns](https://atomic-stack.github.io/atomic-fns/)
+bisectLeft([1, 2, 2, 3], 2) // 1
+bisectRight([1, 2, 2, 3], 2) // 3
+insort([1, 3], 2) // [1, 2, 3]
+binarySearch([1, 3, 5], 4) // -3: absent, belongs at index 2
+const rows = [{ id: 1 }, { id: 4 }]
+bisectLeft(rows, { id: 3 }, (a, b) => a.id - b.id) // 1; lo and hi follow the comparator
+```
+
+## Objects, arrays and helpers
+
+Lodash's intent on today's platform: object paths, deep equality and cloning, iteration over every shape, array set operations, function and async helpers, strings, numbers, ids, hashing and encoding.
+
+### Collections, objects and arrays
+
+#### Iteration over every shape (`atomic-fns/collections`)
+
+```ts
+import {
+  countBy,
+  entries,
+  filter,
+  groupBy,
+  includes,
+  map,
+  size,
+  sortBy
+} from 'atomic-fns/collections'
+
+entries({ a: 1 }) // [['a', 1]]
+countBy(['one', 'two', 'three'], (s) => s.length) // { 3: 2, 5: 1 }, null prototype
+map(new Map([['x', 1]]), (value, key) => `${key}=${value}`) // ['x=1']
+size('👍🏽') // 2 code points
+includes(new Set([NaN]), NaN) // true: SameValueZero
+filter({ a: 1, b: 2 }, (value) => value > 1) // [2]
+groupBy([6.1, 4.2, 6.3], Math.floor) // { 4: [4.2], 6: [6.1, 6.3] }, null prototype
+sortBy(users, [(u) => u.name, (u) => u.age]) // stable; null and undefined keys last
+```
+
+One rule per shape: arrays and typed arrays give their indices (holes skipped), strings their code points, a `Map` its keys, a `Set` its members, any other iterable its positions, and any other object its own enumerable string keys; `null`, `undefined` and other primitives are empty. Callbacks receive `(value, key, collection)`. `forEach` visits every entry, as the native method does; `some`, `every` and `find` stop early. Key helpers (`sortBy`, `orderBy`, `minBy`, `maxBy`) order numbers, bigints and strings; `null` and `undefined` keys sort last, and `minBy` and `maxBy` skip them. Comparing a `NaN` key throws `RangeError`, and comparing a key of any other type, or a string against a number, throws `TypeError`. Every callback is a function: lodash's `'name'` and `{ active: true }` shorthands are `(u) => u.name` and `matches({ active: true })`.
+
+#### Objects (`atomic-fns/object`)
+
+```ts
+import { cloneDeep, get, matches, merge, omit, pick, set } from 'atomic-fns/object'
+
+get({ a: [{ b: 1 }] }, 'a[0].b') // 1
+get({ 'a.b': 1 }, "['a.b']") // 1
+set({}, 'a.b', 1) // { a: { b: 1 } }
+pick({ a: { b: 1, c: 2 } }, 'a.b') // { a: { b: 1 } }
+omit({ user: { name: 'a', password: 'p' } }, 'user.password') // { user: { name: 'a' } }
+merge({ a: [{ b: 2 }] }, { a: [{ c: 3 }] }) // { a: [{ b: 2, c: 3 }] }
+cloneDeep({ when: new Date(0), tags: new Set(['a']) })
+users.filter(matches({ address: { city: 'Oslo' } }))
+```
+
+A `__proto__`, `constructor` or `prototype` path segment that is not own data of a non-function object reads as missing. `set` throws `TypeError` and `unset` returns `false` for these segments unless they are own data of a plain object or array, and for inherited intermediate steps. `set` writes a terminal `constructor` or `prototype` as own data, refusing an existing own accessor or non-writable property. `merge` copies these three keys as own data and refuses to replace an own `constructor` function with an object. `defaults` and `defaultsDeep` fill `constructor` and `prototype` as own data but skip `__proto__` unless the target has a null prototype; `defaultsDeep` never descends into inherited values. `cloneDeep` copies plain objects, arrays, `Map`, `Set`, `Date`, `RegExp`, typed arrays, `DataView`, buffers and boxed primitives with their prototype and symbol keys, and keeps class instances, functions, errors and promises by reference. `cloneDeep` keeps cycles and shared references; `merge` and `defaultsDeep` keep cycles but give each key its own copy of a shared source plain object or array. Deep walks stop past 1000 levels of nesting with a `RangeError`.
+
+`omit` copies own enumerable string and symbol keys of objects, and elements and own enumerable symbol keys of arrays; `defaults` and `defaultsDeep` consider own enumerable string and symbol keys of each source.
+
+For non-null objects other than arrays and without string, numeric or symbol index signatures, literal tuples of individual top-level keys without `.`, `[` or `]` give `pick` and `omit` exact `Pick` and `Omit` result types; union keys and non-tuple lists of those keys give partial results, and other calls return `Partial<T>`.
+
+#### Arrays (`atomic-fns/array`)
+
+```ts
+import { chunk, difference, range, remove, uniqBy, xor, zip } from 'atomic-fns/array'
 
-## Get Started
+range(1, 10, 3) // [1, 4, 7]
+chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+zip(['a', 'b'], [1, 2]) // [['a', 1], ['b', 2]]
+difference([2, 1, 2, 3], [2]) // [1, 3]
+uniqBy([2.1, 1.2, 2.3], Math.floor) // [2.1, 1.2]
+xor([2, 1], [2, 3]) // [1, 3]
+remove(xs, (n) => n % 2 === 0) // removes in place, returns the removed
+```
+
+Set operations keep the order of first appearance, drop duplicates and compare with SameValueZero unless a key or equality function is given. Where one native call does the job, use it: `[...new Set(xs)]` for `uniq`, `xs.filter(Boolean)` for `compact`, `xs.filter((x) => x !== y)` for `without`, `xs.flat()` for `flatten`, `xs.toSpliced(i, 0, x)` for `insert`, `Array.from({ length: n }, (_, i) => fn(i))` for `times`, `zip(...rows)` for `unzip`, and `xs.toSorted((a, b) => a - b)` for `sort` and `sorted` on numbers (without a comparator, `toSorted` orders by string).
+
+### Equality, hashing, ids, encoding and type checks
+
+#### Deep equality (`atomic-fns/object`)
 
-This library is available as an [npm package](https://www.npmjs.com/package/atomic-fns).
+```ts
+import { isEqual, isEqualWith } from 'atomic-fns/object'
 
-To install the package you need to have [npm](https://www.npmjs.com/get-npm) (or [yarn](https://yarnpkg.com/getting-started/install)) installed and then run:
+class Point {
+  constructor(
+    public x: number,
+    public y: number
+  ) {}
+  equals(other: Point): boolean {
+    return this.x === other.x && this.y === other.y
+  }
+}
 
-```bash
-npm install atomic-fns
+isEqual({ a: [1, { b: NaN }] }, { a: [1, { b: NaN }] }) // true: SameValueZero at the leaves
+isEqual(new Map([[1, 'x']]), new Map([[1, 'x']])) // true
+isEqual(new Set([{}]), new Set([{}])) // false: members are matched by SameValueZero
+isEqual(new Point(1, 2), new Point(1, 2)) // false: class instances compare by identity
+isEqualWith([new Point(1, 2)], [new Point(1, 2)], (x, y) =>
+  x instanceof Point && y instanceof Point ? x.equals(y) : undefined
+) // true
 ```
 
-## How to use
+Plain objects, arrays, `arguments`, Dates, RegExps (source, flags and `lastIndex`, with SameValueZero for `lastIndex`), typed arrays, `DataView` and buffers, boxed primitives and errors (name, message, own `cause` and `errors`, and own enumerable properties, not `stack`) compare by content, from any realm. `Map` compares by key membership and then value, `Set` by membership; both match by SameValueZero, so object keys and members match by identity. Other class instances compare by identity. Cycles are compared once, and nesting past 1000 levels throws `RangeError`.
 
-Just import any function or class you need.
+#### `atomic-fns/hash`
+
+```ts
+import { digest, hash, hashString, stableStringify } from 'atomic-fns/hash'
+
+hash({ a: 1, b: 2 }) === hash({ b: 2, a: 1 }) // true: isEqual(a, b) implies hash(a) === hash(b)
+hashString('a') // 3826002220, FNV-1a over UTF-8
+stableStringify({ b: 1, a: 2 }) // '{"a":2,"b":1}'
+await digest('SHA-256', 'abc') // 'ba7816bf...'
+```
 
-```js
-import { sorted, times, uniqueId } from 'atomic-fns'
+`hash` reads at most 8 levels deep, so it never throws on deep, cyclic or huge sparse input (no 1000-level `RangeError`). `stableStringify` calls `toJSON`, as `JSON.stringify` does.
 
-times(5, (i) => i)
-// -> [0, 1, 2, 3, 4]
+#### `atomic-fns/id`
 
-sorted([4, 3, 2, 1])
-// -> [1, 2, 3, 4]
+```ts
+import { nanoid, uniqueId, uuid, uuidv7 } from 'atomic-fns/id'
 
-uniqueId('user_')
-// -> 'user_101225005'
-...
+`user_${uniqueId()}` // 'user_1'
+uuid() // random v4
+uuidv7() // time-ordered: sorts by creation time to the millisecond, and in creation order within one process
+nanoid() // 21 URL-safe characters
 ```
 
-See the full list of [modules](https://atomic-stack.github.io/atomic-fns/modules.html).
+`uniqueId()` takes no prefix and returns the next id from a realm-wide counter as a decimal string; like `crypto.randomUUID`, it ignores arguments passed at runtime, so add a prefix with a template string.
 
-## Data model
-This library features a data model similar to [Python](https://docs.python.org/3/reference/datamodel.html#special-method-names) but not always. Only the missing parts have been implemented, while respecting the JS standards.
+#### `atomic-fns/encoding`
 
-For example, in Python collections, `size()` is a method, while in JS it's just a property. So this library uses `size` property instead of method. Similarly, the `len` function implementation checks for both `length` and `size` since many JS objects have a `length` property.
+```ts
+import { fromBase64, fromHex, toBase64, toHex } from 'atomic-fns/encoding'
 
-## Special method names
-This library adds support for operators using object methods such as:
-  - `obj.eq(other)`  adds custom `obj == other`.
-  - `obj.lt(other)`  adds custom `obj < other`.
-  - `obj.lte(other)`  adds custom `obj <= other`.
-  - `obj.gt(other)`  adds custom `obj > other`.
-  - `obj.gte(other)`  adds custom `obj >= other`.
-  - `obj.compare(other)`  overloads sorting operations.
+const bytes = new Uint8Array([251, 255])
 
-When working with objects, functions in this library use these custom operators for equality and sorting. You can also apply operators to values like `eq(x, y)`, `lte(x, y)`, `compare(x, y)`, etc.
+toBase64('hi') // 'aGk='
+toBase64(bytes, { alphabet: 'base64url', omitPadding: true }) // '-_8'
+fromBase64('aGk=') // Uint8Array [104, 105]
+toHex(new Uint8Array([0, 255])) // '00ff'
+fromHex('00ff') // Uint8Array [0, 255]
+```
 
-## New Types
+#### `atomic-fns/is`
 
-[`Decimal`](https://atomic-stack.github.io/atomic-fns/classes/decimal.Decimal.html) provides support for correct rounded floating point arithmetic, with arbitrary precision.
+```ts
+import { isArrayLike, isError, isNil, isPlainObject } from 'atomic-fns/is'
 
-This fixes precision issues with float arithmetic, for example:
+isPlainObject(Object.create(null)) // true
+isArrayLike('abc') // true
+isError(new TypeError('x')) // true, from any realm
+isNil(undefined) // true
 ```
-0.1 + 0.1 + 0.1
-// 0.30000000000000004
 
-decimal('0.1').add('0.1').add('0.1').toNumber()
-// 0.3
+### Functions, async, strings, numbers and random
+
+#### Functions (`atomic-fns/function`)
+
+```ts
+import { debounce, flow, memoize, once, throttle } from 'atomic-fns/function'
+
+const save = debounce(persist, 300, { maxWait: 2000 }) // 300 ms after the last call, 2 s after the first at most
+const onScroll = throttle(update, 100) // once per 100 ms at most, on the leading and trailing edge
+save()
+save.flush() // runs the pending call now
+const square = memoize((n: number) => n * n) // square(4) is 16, then read from square.cache
+const init = once(setup) // calls setup the first time, then returns its result
+flow(Math.abs, String)(-3) // '3'
 ```
 
-Some common base interfaces and typing patterns you may have seen like `Optional`, `Result`, `Comparable`, `Iterator`, and others.
+`debounce` takes `leading`, `trailing` and `maxWait`; `throttle` takes `leading` and `trailing`. Both return a function with `cancel`, `flush` and `pending`. `memoize` keys on the first argument, or on what its `resolver` returns, and never evicts: `cache` is a `Map` you can clear or replace with any store that has the `Map` interface. `curry` and `compose` complete the module.
+
+`debounce` and `throttle` measure idle windows with `performance.now()` and hold no timer for them when `wait > 0`; held trailing calls use timers, and `wait === 0` keeps a timer until the next macrotask.
 
-### Sorted Containers
-  - [SortedSet](https://atomic-stack.github.io/atomic-fns/classes/collections.SortedSet.html)
-  - [SortedMap](https://atomic-stack.github.io/atomic-fns/classes/collections.SortedMap.html)
-  - [SortedTree](https://atomic-stack.github.io/atomic-fns/classes/collections.SortedTree.html)
+#### Async (`atomic-fns/async`)
 
-### Other Containers
-  - [Deque](https://atomic-stack.github.io/atomic-fns/classes/collections.Deque.html)
-  - [FrozenSet](https://atomic-stack.github.io/atomic-fns/classes/collections.FrozenSet.html)
-  - [LRUCache](https://atomic-stack.github.io/atomic-fns/classes/collections.LRUCache.html)
+```ts
+import { retry, sleep, timeout } from 'atomic-fns/async'
 
+await sleep(100, { signal }) // resolves after 100 ms, rejects with signal.reason on abort
+await timeout(job, 5000) // settles as job does, or rejects with a TimeoutError DOMException
+await retry(() => fetch('/api', { signal: AbortSignal.timeout(5000) }), { retries: 5 }) // 6 attempts at most
+```
 
-## Contributing
-If you want to contribute to the project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on Github, new technologies and and their ecosystems and how to make constructive, helpful bug reports, feature requests and the noblest of all contributions: a good, clean pull request. You will be listed as a **Champion** on the official site as well.
+`retry` waits `minDelay` (100 ms) before the first retry and multiplies the delay by `factor` (2) up to `maxDelay` (10 s), with `jitter` on by default. `shouldRetry(error, attempt)` decides which errors earn another attempt, and `signal` stops the loop. `timeout` stops the wait, not the work: give the work its own signal, as `fetch` gets above, so a timed-out attempt is aborted before the next one starts.
+
+#### Strings (`atomic-fns/string`)
+
+```ts
+import {
+  camelCase,
+  capitalize,
+  kebabCase,
+  slugify,
+  startCase,
+  truncate,
+  words
+} from 'atomic-fns/string'
+
+words('fooBar HTTPServer 11th IDs') // ['foo', 'Bar', 'HTTP', 'Server', '11th', 'IDs']
+camelCase('HTTPServer error') // 'httpServerError'
+kebabCase('fooBar baz') // 'foo-bar-baz'
+startCase('--foo-bar--') // 'Foo Bar'
+capitalize('FRED') // 'Fred'
+slugify('Antoine de Saint-Exupéry') // 'antoine-de-saint-exupery'
+truncate('hi-diddly-ho there, neighborino', { length: 24 }) // 'hi-diddly-ho there, n...'
+```
+
+`words` splits on `Intl.Segmenter` with identifier rules, and `camelCase`, `pascalCase`, `snakeCase`, `kebabCase` and `startCase` build on it. `capitalize` title-cases the first code point and lowercases the rest, so separators stay. `deburr` folds Latin accents, `slugify` makes URL slugs, and `truncate` cuts on grapheme boundaries.
+
+#### Numbers (`atomic-fns/number`)
+
+```ts
+import { clamp, formatBytes, mean, round } from 'atomic-fns/number'
+
+round(1.005, 2) // 1.01
+clamp(15, 0, 10) // 10
+mean([1, 2, 3]) // 2
+formatBytes(1536) // '1.54 kB'
+formatBytes(1536, { binary: true }) // '1.5 KiB'
+```
+
+`round`, `floor` and `ceil` work on the printed decimal, so `1.005` rounds as written. `inRange` and `sum` complete the module.
+
+#### Random (`atomic-fns/random`)
+
+```ts
+import { randomInt, sample, sampleSize, shuffle } from 'atomic-fns/random'
+
+randomInt(1, 6) // 1 to 6, both included
+sample({ a: 1, b: 2 }) // 1 or 2
+sampleSize([1, 2, 3, 4, 5], 2) // two values at distinct positions, such as [4, 1]
+shuffle(new Set(['a', 'b', 'c'])) // a new array, such as ['c', 'a', 'b']
+randomInt(1, 6, { random: () => 0 }) // 1
+```
+
+`random` and `randomInt` (uniform over any span of safe integers) draw numbers; `sample`, `sampleSize` and `shuffle` draw from every collection shape. Each takes `{ random }` to replace `Math.random`. `Math.random` is not cryptographically secure, so never use these for secrets, tokens or one-time codes: use `atomic-fns/id` or `crypto.getRandomValues`.
+
+`sample` and `sampleSize` draw from arrays and typed arrays by reading only selected positions unless an array hole triggers a full scan, but `sampleSize` copies all values for full samples and when `n >= 5 && n >= length / 2`; sparse arrays may consume extra draws, so seeded results can differ from sampling their collected values, and `sampleSize(xs, 0)` reads no values.
+
+## Decimal
+
+Exact decimal arithmetic shaped after the TC39 Decimal draft, with Currency.
+
+```ts
+import { Currency, Decimal } from 'atomic-fns/decimal'
+```
+
+No runtime dependencies, no Node APIs: it runs on the platforms listed above.
+
+### Decimal
+
+A `Decimal` is an immutable exact decimal number. Methods replace operators, so nothing rounds through a binary `Number`.
+
+```ts
+const a = new Decimal('0.1')
+a.add('0.2').toString() // '0.3'
+a.add('0.2').equals('0.3') // true
+new Decimal('19.99').multiply(3).toString() // '59.97'
+new Decimal('7.5').remainder(2).toString() // '1.5'
+```
+
+The constructor and every operand take a `Decimal`, a decimal string (`'-1.5'`, `'.5'`, `'2e-3'`), a bigint, or a finite number, which enters through its shortest round-trip string (`new Decimal(0.1)` is exactly `0.1`). A malformed string or a non-finite number throws `RangeError`; any other type throws `TypeError`.
+
+#### Rounding
+
+`divide` and `sqrt` round to `precision` significant digits (default 34, as the TC39 draft does), while `round` and `toFixed` take fractional `digits`. Each takes one of the `Intl.NumberFormat` rounding modes: `ceil`, `floor`, `expand`, `trunc`, `halfCeil`, `halfFloor`, `halfExpand`, `halfTrunc` and `halfEven` (the default, except for `toFixed`, which defaults to `halfExpand`).
+
+```ts
+new Decimal(1).divide(3).toString() // '0.3333333333333333333333333333333333'
+new Decimal('1e-30').divide(3, { precision: 3 }).toString() // '0.000000000000000000000000000000333'
+new Decimal(2).divide(3, { precision: 2, roundingMode: 'trunc' }).toString() // '0.66'
+new Decimal('2.5').round().toString() // '2'
+new Decimal('2.5').round(0, 'halfExpand').toString() // '3'
+new Decimal('1234').round(-2).toString() // '1200'
+new Decimal(2).sqrt({ precision: 5 }).toString() // '1.4142'
+```
+
+Dividing by zero throws `RangeError`, and so does a quotient too small for the exponent bound.
+
+#### Comparing
+
+`compare` returns -1, 0 or 1, `equals` ignores the written form, and `lessThan`, `lessThanOrEqual`, `greaterThan` and `greaterThanOrEqual` answer the rest. `Decimal.compare` sorts:
+
+```ts
+;['10', '9', '9.5']
+  .map((s) => new Decimal(s))
+  .toSorted(Decimal.compare)
+  .map(String)
+// ['9', '9.5', '10']
+```
+
+`valueOf` throws, so `<`, `+` and `==` cannot silently compare or add a Decimal as a `Number`. Between two Decimals, `==` and `===` compare identity, so use `equals`. Template literals and `String()` still work. In Node, Deno and Bun, `console.log` shows `Decimal { 1.5 }`, through the runtime's `Symbol.for('nodejs.util.inspect.custom')` hook.
+
+#### Converting
+
+```ts
+new Decimal('1.50').toString() // '1.5'
+new Decimal('1e100').toString() // '1e+100'
+new Decimal('1e5').toPlainString() // '100000'
+new Decimal('1.005').toFixed(2) // '1.01'
+new Decimal('1234.5678').toLocaleString('de-DE') // '1.234,568'
+new Decimal('0.1').toNumber() // 0.1
+new Decimal('1.2e3').toBigInt() // 1200n
+JSON.stringify({ price: new Decimal('9.90') }) // '{"price":"9.9"}'
+```
+
+`toString` and `toJSON` switch to scientific form once plain notation would pad more than 64 zeros; `toPlainString` always expands. A short input such as `'1e10000'` becomes 10,001 characters, so prefer `toString` for untrusted values. `toFixed` rounds ties half away from zero, as `Number.prototype.toFixed` does, unless given a rounding mode.
+
+#### Bounds
+
+A Decimal holds at most `Decimal.MAX_DIGITS` (10,000) significant digits, and the exponent of its integer coefficient lies within `Decimal.MAX_EXPONENT` (10,000) either way: `'1.5e-10000'`, stored as 15e-10001, is out of range. `divide` and `sqrt` take a `precision` up to `Decimal.MAX_DIGITS`, and `round` and `toFixed` take `digits` up to `Decimal.MAX_PRECISION` (10,000). Inputs and results past a bound throw `RangeError`, and so do strings longer than 30,032 characters, so a short untrusted string such as `'1e1000000000'` cannot allocate without limit and parse cost is bounded. Each operation still costs time that grows with its operands' digits, so size-limit untrusted lists before summing them.
+
+### Currency
+
+A `Currency` is an exact `amount` (a `Decimal`) and a `currency` code. The code must be three ASCII letters, as ISO 4217 codes are, but the constructor does not check it against the ISO 4217 list.
+
+```ts
+const price = new Currency('19.99', 'usd')
+price.currency // 'USD'
+price.multiply(3).format('en-US') // '$59.97'
+price.add(new Currency('0.01', 'USD')).toString() // '20 USD'
+new Currency(10, 'USD').divide(3).round().toString() // '3.33 USD'
+new Currency('1234.5', 'JPY').round().toString() // '1234 JPY'
+```
+
+`add`, `subtract`, `compare` and the relational methods take another `Currency` and throw `RangeError` when the codes differ; `equals` answers false. `multiply` and `divide` take a plain factor. `round()` rounds to the currency's ISO 4217 minor unit, half to even, not to the digits `Intl` displays, and throws `RangeError` for a code that ISO 4217 gives no minor unit, such as `XAU`, or does not list; `round(digits)` takes any code.
+
+`format(locale, options)`, also `toLocaleString`, formats with `Intl.NumberFormat` in currency style. Unless the options set `maximumFractionDigits`, a significant-digit option, `roundingIncrement` or a non-standard `notation`, the amount keeps its own fraction digits, up to 20:
+
+```ts
+new Currency('0.125', 'USD').format('en-US') // '$0.125'
+new Currency('0.125', 'USD').format('en-US', { maximumFractionDigits: 2 }) // '$0.13'
+new Currency(-5, 'USD').format('en-US', { currencySign: 'accounting' }) // '($5.00)'
+new Currency(5, 'USD').format('en-US', { currencyDisplay: 'name' }) // '5.00 US dollars'
+```
+
+`toString` and `toJSON` give `'12.5 USD'`, and in Node, Deno and Bun `console.log` shows `Currency { 12.5 USD }`. Like `Decimal`, `valueOf` throws.
+
+## Development
+
+```sh
+npm install
+npm run check
+```
 
+`check` runs Biome, the type check, tests with coverage thresholds (90% lines, statements and functions; 85% branches), the build, dist export checks, packed consumer runtime and type checks, publint, Are the Types Wrong? (`attw`), `deno doc --lint`, and a JSR dry run.
 
 ## License
 
-[Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+[Apache License 2.0](https://github.com/adrian2x/atomic-fns/blob/main/LICENSE)

package/dist/array/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Array building blocks (`chunk`, `zip`, `range`, `remove`, `dropWhile`, `takeWhile`) and set
+ * operations (`uniqBy`, `uniqWith` and the `difference`, `intersection`, `union` and `xor`
+ * families), which keep the order of first appearance and compare with SameValueZero unless a key
+ * or equality function is given.
+ * @module array
+ */
+export { chunk, dropWhile, range, remove, takeWhile, zip } from './list.js';
+export { difference, differenceBy, differenceWith, intersection, intersectionBy, union, unionBy, uniqBy, uniqWith, xor, xorBy } from './sets.js';

package/dist/array/index.js

@@ -0,0 +1,9 @@
+/**
+ * Array building blocks (`chunk`, `zip`, `range`, `remove`, `dropWhile`, `takeWhile`) and set
+ * operations (`uniqBy`, `uniqWith` and the `difference`, `intersection`, `union` and `xor`
+ * families), which keep the order of first appearance and compare with SameValueZero unless a key
+ * or equality function is given.
+ * @module array
+ */
+export { chunk, dropWhile, range, remove, takeWhile, zip } from './list.js';
+export { difference, differenceBy, differenceWith, intersection, intersectionBy, union, unionBy, uniqBy, uniqWith, xor, xorBy } from './sets.js';

package/dist/array/list.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Array building blocks: `chunk`, `zip`, `range`, `remove`, `dropWhile`, `takeWhile`.
+ */
+/**
+ * `array` split into consecutive pieces of `size` elements; the last piece holds the rest.
+ * @param array The array to split.
+ * @param size The length of each piece, a positive integer.
+ * @returns A new array of new arrays.
+ * @throws {RangeError} when `size` is not a positive integer, or `array` is a huge sparse array.
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]
+ * ```
+ */
+export declare function chunk<T>(array: readonly T[], size: number): T[][];
+/**
+ * Rows built from the elements at each index of `arrays`: `zip(a, b)[i]` is `[a[i], b[i]]`. The
+ * result is as long as the longest input, and shorter inputs give `undefined`, as lodash does, so
+ * `zip(...zip(a, b))` restores `a` and `b` padded to one length.
+ * @param arrays The arrays to combine.
+ * @returns A new array of rows.
+ * @throws {RangeError} when an input is a huge sparse array.
+ * @example
+ * ```ts
+ * zip(['a', 'b'], [1, 2]) // [['a', 1], ['b', 2]]
+ * zip(...[['a', 1], ['b', 2]]) // [['a', 'b'], [1, 2]]
+ * ```
+ */
+export declare function zip<A extends readonly (readonly unknown[])[]>(...arrays: A): {
+    [K in keyof A]: A[K][number] | undefined;
+}[];
+/**
+ * The numbers from `start` up to, not including, `stop`, `step` apart, with Python's bounds:
+ * `range(stop)` starts at 0, and a negative `step` counts down. Each element is
+ * `start + i * step`, so fractional steps do not drift. Numbers are doubles: past 2^53, or with a
+ * `step` smaller than the gap between doubles near the bounds, neighbouring numbers round to the
+ * same value. The length cap is the longest array the platform allows, not a memory budget, so
+ * bound `stop` yourself when it comes from untrusted input.
+ * @param start The first number, or `stop` when it is the only argument.
+ * @param stop The bound the numbers stop before.
+ * @param step The distance between numbers; defaults to 1.
+ * @returns A new array, empty when `start` is already past `stop`.
+ * @throws {TypeError} when a bound or `step` is not a number.
+ * @throws {RangeError} for a `NaN` or infinite bound, a zero or infinite `step`, or more than
+ * 2^32 - 1 numbers.
+ * @example
+ * ```ts
+ * range(4) // [0, 1, 2, 3]
+ * range(1, 10, 3) // [1, 4, 7]
+ * range(3, 0, -1) // [3, 2, 1]
+ * ```
+ */
+export declare function range(stop: number): number[];
+/** {@link range} from `start`, with an optional `step`. */
+export declare function range(start: number, stop: number, step?: number): number[];
+/**
+ * Remove from `array`, in place, every element `predicate` returns truthy for, and return them,
+ * as lodash does. The predicate gets `(value, index, array)` for the elements present, with the
+ * original indices, before `array` changes; holes are skipped and keep their place next to the
+ * elements around them.
+ * @param array The array to change.
+ * @param predicate Tests one element.
+ * @returns A new array of the removed elements, in order.
+ * @example
+ * ```ts
+ * const xs = [1, 2, 3, 4]
+ * remove(xs, (n) => n % 2 === 0) // [2, 4]
+ * xs // [1, 3]
+ * ```
+ */
+export declare function remove<T, S extends T>(array: T[], predicate: (value: T, index: number, array: T[]) => value is S): S[];
+/** {@link remove} with a predicate that is not a type guard. */
+export declare function remove<T>(array: T[], predicate: (value: T, index: number, array: T[]) => unknown): T[];
+/**
+ * `array` without its leading elements for which `predicate` is truthy. Holes are skipped, as
+ * {@link remove} skips them, and keep their place in the result.
+ * @param array The array to read.
+ * @param predicate Tests one element present; gets `(value, index, array)`.
+ * @returns A new array from the first element that fails.
+ * @example
+ * ```ts
+ * dropWhile([1, 2, 3, 1], (n) => n < 3) // [3, 1]
+ * ```
+ */
+export declare function dropWhile<T>(array: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => unknown): T[];
+/**
+ * The leading elements of `array` for which `predicate` is truthy. Holes are skipped, as
+ * {@link remove} skips them, and keep their place in the result.
+ * @param array The array to read.
+ * @param predicate Tests one element present; gets `(value, index, array)`.
+ * @returns A new array up to the first element that fails.
+ * @example
+ * ```ts
+ * takeWhile([1, 2, 3, 1], (n) => n < 3) // [1, 2]
+ * ```
+ */
+export declare function takeWhile<T, S extends T>(array: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => value is S): S[];
+/** {@link takeWhile} with a predicate that is not a type guard. */
+export declare function takeWhile<T>(array: readonly T[], predicate: (value: T, index: number, array: readonly T[]) => unknown): T[];