This project is unmaintained. ts-pattern is a better execution of the idea.
๐ต Tell me when will you be mine? / Tell me quando quando quando ๐ต
npm i quando
yarn add quando
JavaScript has poor support for conditional expressions, and handling scenarios with multiple clauses is impossible. It's awkward when handling conditions in JSX which encourages an expression oriented approach and doesn't provide conditional elements found in a templating language like Handlebars.
Some proposals would bring more powerful conditional expressions to JavaScript like do and pattern matching, but they are a long way off and may never happen. In an ideal world, this library would be made redundant by these proposals making it into the language. However, Quando is for the time we spend waiting.
Here's an example that handles the status of an API call using the Match
function:
function Example() {
const { status, error, data } = useQuery("repoData", () =>
fetch("https://api.github.com/repos/richeyryan/quando").then(res =>
res.json(),
),
);
return (
<div>
{Match(status)
.where("error", () => <>"An error has occured: " {error.message}</>)
.where("loading", "Loading...")
.end(() => (
<>
<h1>{data.name}</h1>
<p>{data.description}</p>
<strong>๐ {data.subscribers_count}</strong>{" "}
<strong>โจ {data.stargazers_count}</strong>{" "}
<strong>๐ด {data.forks_count}</strong>
</>
))}
</div>
);
}
Compatibility
The API aims to avoid clashing with current or potential future JavaScript features. We avoid reserved words where possible, and When
is capitalized to avoid conflicts with the pattern matching proposal.
Each function has a chainable API or fluent interface. You must complete the chain with the end
method, which will return the result of your expression. You can also provide the default value with the end method if there are no matches in your condition.
Lazy Evaluation
The result parameter of any condition can be a function. If the condition is truthy, the function gets called, which prevents issues like in the example above where we get an error if we try to read data.name
before it's defined.
The equivalent of an if statement, returns the first clause where the condition is truthy. Returns the default if there is no match.
import { When } from "quando";
When(status === "loading", <Loading />)
.elseWhen(status === "error", <Error message="Failed to load user" />)
.elseWhen(status === "success", <User user={user} />)
.end();
Returns the clause if the condition is falsy. Returns the default if the condition is truthy.
import { Unless } from "quando";
Unless(user, "Select a user to continue");
A very rough approximation of pattern matching. Basically an expression version of a switch statement.
The first parameter of where
can be a value that strictly matches (===
) the comparable passed to Match
. Otherwise, it can be a function which takes the comparable as a parameter and returns true
if it matches or false
if it doesn't.
The second parameter can be any value or a function that is called only when the comparable is matched.
Match("John")
.where("John", "guitar")
.where("George", "guitar")
.where("Paul", "bass")
.where("Ringo", "drums")
.end();
Examples of using each function can be found in the examples
folder. You can run them like this:
yarn build
node examples/examples.js
Any contributions of interesting examples would be much appreciated.
Each of the functions above are factories that create an instance of a class. There is a class for each of the functions. Each class is a facade over the Matcher
class, they make the public fluent interface and each call passes through to the Matcher
which handles the actual matching logic.
You can import the Matcher
class and the extractResult
function which helps with results that are passed as functions. Using them both you can create your own factory function and inject your own matching logic into the Matcher
class.