callWithNamedArgs

callWithNamedArgs is a utility library for JavaScript and TypeScript that allows you to call functions with named arguments instead of only relying on the order of parameters.

Table of Contents

• Need
• Installation
• Usage
• Contributing
  • New issues
  • Merge requests
• License

Need

In JavaScript and TypeScript if you want to call a function you always have to pass all parameters in the correct order this can be inconvenient, especially when a function has many parameters with default or optional values.

function exampleFunction(param1 = true, param2 = 'default', param3 = 42) {
    console.log(param1, param2, param3);
}
// If you want to call the function with it's  default value except for param3 you have to do this
exampleFunction(true, 'default', 100); // I have to look up the default value for param1 and 2 and manually pass them here

With callWithNamedArgs you can call functions with named arguments, making it easier to skip optional parameters and improve code readability.

import { callWithNamedArgs } from 'call-with-named-args';
function exampleFunction(param1 = true, param2 = 'default', param3 = 42) {
    console.log(param1, param2, param3);
}
// Now you can call the function with named arguments
callWithNamedArgs(exampleFunction, [], { param3: 100 }); // No need to pass param1 and param2, they will use their default values

Installation

This library is available on npm, you can install it to your project using one of the following commands

npm install call-with-named-args
yarn add call-with-named-args
pnpm add call-with-named-args

Usage

The function callWithNamedArgs takes 1 to 4 parameters:

1. fn: The function you want to call.
2. positional: An array of positional arguments to be passed to the function.
3. named: An object containing named arguments to be passed to the function.
4. extra: An array of all arguments given to a destructured rest parameter.

import { callWithNamedArgs } from 'call-with-named-args';
function exampleFunction(param1 = true, param2 = 'default', param3 = 42, ...rest) {
    console.log(param1, param2, param3, rest);
}
// Call the function with positional arguments
callWithNamedArgs(exampleFunction, [false, 'custom']); // Outputs: false 'custom' 42 []
// Call the function with named arguments
callWithNamedArgs(exampleFunction, [], { param3: 100 }); // Outputs: true 'default' 100 []
// Call the function with extra arguments
callWithNamedArgs(exampleFunction, [], {}, [1, 2, 3]); // Outputs: true 'default' 42 [1, 2, 3]
// Call the function with a mix of positional, named, and extra arguments
callWithNamedArgs(exampleFunction, [false], { param3: 100 }, [1, 2, 3]); // Outputs: false 'default' 100 [1, 2, 3]

As you can see, whenerver an argument wasn't passed it used it's default value.

Contributing

New issues

If you find a bug or have a feature request, please open an issue on the repository and I will try to answer it as soon as possible

Merge requests

If you want to contribute to the project, feel free to open a merge request for one of the existing issues, I will review it and merge it if it is good.
If you want to add a new feature, please open an issue first to discuss it with me before opening a pull request

If you do end up opening a pull request, there are some rules that you need to follow:

• Make sure to write tests for your code, I have a pipeline that checks for them and the coverage's threshold is set to 100% so every case must be covered
• Format the code using pnpm format so that it has the same style as the rest of the project
• Lint the code using pnpm lint to ensure code quality
• If at some point you need to add an exception to the linting/formatting/testing coverage threshold, you need to write a comment explaining why it is needed
• Please write your code in a clean and readable way, I will not merge your code until I am satisfied with it
• If needed, you should write documentation for your code in the README.md file so that people using the library can understand how it works

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License