Support array-first argument order for higher-order functions

[Copilot]

Higher-order functions like map, filter, fold now accept array-first argument order (e.g., map(items, fn)) in addition to the existing function-first order. Documentation and autocompletions exclusively suggest the array-first form.

Changes

• Array operations (src/functions/array/operations.ts): Modified map, filter, fold, reduce, find, some, every to detect argument order at runtime and handle both forms
• Documentation (docs/syntax.md): Updated all examples to array-first syntax
• Language service (src/language-service/language-service.documentation.ts): Parameter order in autocompletion hints now shows array-first
• Tests: Added 46 tests for array-first usage; updated error message tests

Example

// New preferred syntax (documented)
map([1, 2, 3], x => x * 2)
filter([1, 2, 3, 4], x => x > 2)
fold([1, 2, 3], 0, (acc, x) => acc + x)

// Legacy syntax (still works, not documented)
map(x => x * 2, [1, 2, 3])

Detection logic: if first argument is an array and last is a function → array-first; if first is a function → function-first.

Original prompt

Support array-first argument order: map(items, fn) alongside map(fn, items) for all functions that accept functions. Ensure that all documentation and language server suggestions only suggest the array-first version. The function first version should still work for backwards compatible reasons but should not be encouraged in the documentation of autocompletions.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This pull request adds support for array-first argument order for higher-order array functions (e.g., map([1, 2, 3], x => x * 2)) while maintaining backward compatibility with the existing function-first order. The new array-first syntax is now the documented and recommended approach, with autocompletion hints showing this order exclusively.

Changes:

• Modified seven array operation functions (map, filter, fold, reduce, find, some, every) to detect and support both argument orders at runtime
• Updated all documentation examples in docs/syntax.md to use array-first syntax
• Updated language service parameter hints to show array-first order
• Added 46 comprehensive tests covering both argument orders and edge cases
• Updated error messages to reflect array-first signature

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/functions/array/operations.ts	Implemented runtime argument order detection for all higher-order array functions with backward compatibility
test/functions/functions-array-first-order.ts	Added comprehensive test suite covering array-first usage, backward compatibility, and edge cases
test/functions/functions-array-errors.ts	Updated error message tests to reflect new array-first signature format
docs/syntax.md	Updated all function signatures and examples to demonstrate array-first syntax (with minor typo)
src/language-service/language-service.documentation.ts	Updated autocompletion hints to show array-first parameter order

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Typo: "can than be" should be "can then be".

Suggested change

	These functions can than be used in other functions that require a function argument, such as `map`, `filter` or `fold`:
	These functions can then be used in other functions that require a function argument, such as `map`, `filter` or `fold`:

[Copilot]

The condition else if (arg3 === undefined) at line 69 is problematic. If arg3 is undefined, the function-first detection at line 64 would have already matched (since it checks Array.isArray(arg3) || arg3 === undefined).

This check will only be reached if arg1 is not a function AND arg1 is not an array. In that case, returning undefined silently masks what should be an error. For example:

• fold("string", 0, undefined) would return undefined instead of throwing an error
• fold(123, 0, undefined) would return undefined instead of throwing an error

This should either be removed (so the error is thrown) or the logic should be reconsidered. The behavior is inconsistent with other functions like map, filter, find, some, and every which don't have this special case.

Suggested change

	} else if (arg3 === undefined) {
	return undefined;