Native Node module spread calls such as `path.join(...args)` fail despite spread calls being documented as supported

[Cruel]

Description

Perry documents the spread operator in calls as supported, and node:path / path.join as supported, but spreading a valid string array into path.join() fails at runtime.

I initially encountered this in a larger application, but it reduces to a very small standalone repro.

Minimal reproduction

repro.ts:

import path from 'node:path';

console.log('direct:', path.join('/tmp/x', 'project.json'));

const parts = ['/tmp/x', 'project.json'];
console.log('spread:', path.join(...parts));

Using Perry 0.5.1220:

pnpm add -D @perryts/perry@0.5.1220
pnpm exec perry compile repro.ts --target linux --output repro
./repro

Actual behavior

The direct call succeeds:

direct: /tmp/x/project.json

The equivalent spread call then throws:

TypeError: The "path" argument must be of type string.
    at <anonymous>

and exits nonzero.

Expected behavior

Both forms should be equivalent:

direct: /tmp/x/project.json
spread: /tmp/x/project.json

Node 24.18.0 produces the expected output.

Why I expected this to be supported

The Perry 0.5.1220 README marks:

• functions/rest parameters as supported;
• the spread operator in calls and literals as supported;
• path.join as supported.

The runtime parity documentation also lists path.join([...paths]) as supported without a caveat.

Perry's own parity suite contains a spread invocation of path.join in:

test-parity/node-suite/path/join/type-errors-extra.ts

using:

path.join(...args)

That fixture appears to test invalid argument types, but does not include the corresponding valid-string-array case.

Current main

I also checked current Perry main.

At the time of testing:

commit: 0328a63bbc1b582bfdbb0842a957aac861bd84d7
version: 0.5.1413

I noticed that the current source contains an internal comment in the native-module call lowering code describing:

ns.method(...arr)

as a separate runtime spread gap.

That appears to be the same category as:

path.join(...parts)

So this may already be a known implementation limitation internally.

I could not find a corresponding user-facing compatibility caveat or a specific issue tracking this case, and the public compatibility documentation currently appears to describe both spread calls and path.join as supported.

If this gap is already tracked elsewhere, please feel free to close this as a duplicate.

Additional observation

The problem does not require a rest parameter. This also fails:

const parts = ['/tmp/x', 'project.json'];
path.join(...parts);

while this succeeds:

path.join('/tmp/x', 'project.json');

A wrapper using a rest parameter therefore fails for the same reason:

function joinPath(...parts: string[]): string {
  return path.join(...parts);
}

Workaround

Avoiding a spread into the native module function works:

function joinPath(...parts: string[]): string {
  if (parts.length === 0) {
    return '.';
  }

  let result = parts[0]!;
  for (let index = 1; index < parts.length; index += 1) {
    result = path.join(result, parts[index]!);
  }

  return result;
}

Environment

• Perry: 0.5.1220
• Package: @perryts/perry
• Target: linux
• Host: Linux x86_64
• Node used to invoke the Perry toolchain: 24.18.0

[proggeramlug]

Fixed by #7726, with a correction in #7734 (both on main once #7734 lands).

Your repro now matches node exactly, in every call form:

direct: /tmp/x/project.json
spread: /tmp/x/project.json

Root cause — as you suspected from the internal comment, it was not a path bug. Every native-module fast path in lower_call consumes its arguments positionally, and a spread argument lowers to one expression holding the whole array, so path.join(...parts) reached the one-argument arm as PathNormalize(<array>). The same fold made util.format(...args) inspect its array instead of formatting it and fs.existsSync(...args) test an array for existence, so the fix is the whole node-core module namespace surface rather than path alone: a spread call now declines the fast-path chain and goes through the variadic runtime dispatch, which also reproduces Node's ERR_INVALID_ARG_TYPE (with its code) for genuinely invalid segments.

On the fixture you spotted — you were exactly right that node-suite/path/join/type-errors-extra.ts does not cover the valid-string-array case, and that is precisely why the bug survived: it only spreads segments Node rejects, so the broken lowering and the correct one both throw ERR_INVALID_ARG_TYPE and the test stayed green for the bug's whole life. node-suite/path/join/spread.ts now supplies the valid cases (namespace / namespace-import / require-alias / named-import / posix / win32 / sub-namespace alias / value-read / in-loop), with siblings for path.resolve and util.format, plus lowering-verdict unit tests that assert the spread call is diverted and that the non-spread fast path still fires.

Still open, found while testing this — a few neighbours in the same family that are not covered by these two PRs, in case you hit them:

• events.listenerCount(...args) — nm_dispatch_events has no arm for it, so it yields undefined
• Object.assign(target, ...sources) — the sources array is passed as one argument ({"0":{…},"1":{…}} rather than a merge); not a node module, so a separate family
• Buffer.concat(list) through a type-erased receiver — broken independently of spread

Thanks for the unusually well-researched report — the main commit hash, the pointer at the internal comment, and the note about the existing fixture all shortened this considerably.

[Cruel]

Good job, thanks. This is a quick moving project.
I tried this fix and it appears to work.
I've encountered some other issues I have to make workarounds for. Working on them right now, actually. I'll probably draft a report on a couple issues later once I'm done. 👍