feat(collections): add setBatch for explicit key/value pairs

[CaptainAni187]

Closes #1613

set() derives every key from its value, either from a key string or a keygen function. As #1613 describes, that breaks down when the key isn't part of the data — the workaround is to attach the key to the value anyway, and sometimes to delete it again inside the keygen:

collections.set('my-collection', (item) => {
  const key = item.key;
  delete item.key;
  return key;
}, items)

setBatch(name, items) takes the pairs directly:

collections.setBatch('my-collection', [
  { key: 'a', value: ['some', 'strings'] },
  { key: 'b', value: ['more', 'strings'] },
])

Why a separate function rather than overloading set()

The issue asks for set(name, items) but then notes overloading "isn't great in docs" and that "a setBatch() function might be a cleaner alternative". I went with the separate function, for a reason beyond docs: set() currently rejects fewer than three arguments explicitly —

if (argCount < 3) {
  const e = new Error('ILLEGAL_ARGUMENTS');
  e.fix = 'Make sure to pass three arguments to: set(name, key/keygen, values)';

— and there's a test pinning that behaviour (should throw if only two args passed). A two-argument overload would have to reverse that guard and weaken the error for genuine mistakes, since set(name, values) with a forgotten keygen would then be indistinguishable from a batch call. Keeping the two entry points separate leaves that error intact.

Happy to switch to an overload if you'd prefer the shape in the issue title.

Implementation notes

The batching and upload loop is now a shared uploadValues() helper instead of being duplicated. set()'s behaviour is unchanged, including its log output — the helper takes the collection name as written by the caller for logging, so a lazy state reference still logs the way it did before.

setBatch validates each item and fails with the same style of structured error the module already uses: ILLEGAL_ARGUMENTS when items isn't an array or an entry isn't an object, and KEY_ERROR when an entry has no string key.

Values are JSON.stringify'd exactly as in set(), so a value which is itself an array round-trips as one — that's the case the issue calls out.

Tests

Six tests added alongside the existing set tests: setting multiple pairs, setting a value that carries no key of its own, and the four validation paths.

• packages/collections: 98 passing, up from 92 — the six new tests, no other change.
• pnpm lint: identical output before and after (0 errors, 14 pre-existing warnings).

Changeset included as a minor bump.

Note for anyone building locally: packages/collections tests need @openfn/language-common built first, and that needs pnpm build:tools before it, otherwise the build fails on an unbuilt @openfn/adaptor-apis.

[CaptainAni187]

Closing this for now to tidy up my open PRs. Happy to reopen if it's still useful.