matching

matching

Emit rows of a primary stream whose key is present in a probe stream — a sorted-stream semi-join filter. Whole rows pass through unchanged; there is no combine and no Cartesian product. The opposite of unmatched.

import matching from 'stream-sorting/sorted/matching.js';

// keep orders whose customerId appears in the activeCustomers stream
for await (const order of matching(
  {input: orders, key: o => o.customerId},
  {input: activeCustomers, key: c => c.id}
)) {
  // each order with a matching active customer
}

primary and probe are {input, key?} descriptors, each sorted by its key (key defaults to identity — so probe can be a bare stream of keys). The result is an AsyncIterable of primary's rows. Primary duplicates are preserved (this is a filter, not a dedup); probe duplicates are ignored.

Options

Option	Type	Default	Description
compareKey	(a, b) => number	natural order	Orders keys. compareKey OR lessKey. Composite keys need an explicit one.
lessKey	(a, b) => boolean	—	Strict-less key comparator. compareKey OR lessKey.

Closely related to keyed intersection, but it keeps the primary's whole rows rather than emitting shared values. An out-of-order primary throws at runtime.

See also

unmatched, join, intersection.