First off, love the library - though I will admit the learning curve felt unnecessarily steep (or rather, I feel like I had to read the entire README to get a complete understanding of the library and the value it brings). Some suggested improvements:
-
Implement a table of contents: when you heavily depend on a library throughout your project (as you would if you were using esresult) you often initially spend a bit of time cross-referencing/searching through the documentation. Larger libraries often have websites dedicated to documentation (see: date-fns), whereas you often have to rely on the README for smaller repositories. When this is the case, it's important you can quickly access the information you want without having to scroll/read through the entire readme (see: zod for a great example). Even as a first time user, I'm probably not interested in reading through your entire README, a table of contents quickly allows me to navigate to the areas I'm interested in.
-
Swap out yarn installation example for npm - in terms of usage, npm is more popular than yarn. You should either swap out the yarn installation example for npm (particularly as its the default package manager), or add two installation instructions - one for npm and one for yarn (and I'd argue your npm installation instruction should come first). If you're looking for mass adoption of the library, you'll be hoping new developers pick it up, and many of them won't understand the implications of npm versus yarn, and by defaulting to your installation instructions may very well find themselves with both a yarn.lock and package-lock.json file.
-
Add a motivation/why at the top of your README. I think it's enough to begin your README with:
esresult is a zero-dependency, TypeScript-first utility for better error-handling patterns in your code by making domain-specific errors an explicit part of a function's public API.
However, you then need to clearly state the motivation for the project: what problem are you trying to solve, and then whats the quick elevator pitch for how you solve the problem? What's wrong with default try/catch error handling in javascript and then abstractly (without getting into implementation), how does your library fix it?
- Add a basic example: once you've introduced your library, explained the problem and given a high level overview of what your library does, and shown how to install it, you should give me a very simple/basic example (Getting Started). In as few lines as possible, what is the most common practical application of your library to resolve error handling? Pick a common problem and show how it can be resolved with esresult:
Getting started
For example, you may often need to write a function which takes as input from the user a potential JSON request body, hit a remote API with details within that request body, and return a portion of that to the user. Without esresult, this may look something like:
async function handleCreateUserRequest(request) {
let body;
try {
body = JSON.parse(request);
} catch (err) {
return {
error: "Invalid request body";
};
}
try {
const response = await fetch('https://example.com/users', {
method: 'post',
headers: {
'content-type': 'application/json',
},
body: JSON.stringify({ username: request.username }),
});
const data = await response.json();
if (data.valid) {
return {
error: "Error creating user",
};
}
return data;
} catch (err) {
return {
error: 'Unknown error';
}
}With esresult, you could rewrite this function as:
async function handleCreateUserRequest(request) {
..
}This is a bad example. Ideally though, you should give a real-world example of how one might currently write a common function/design pattern without esresult, how they then may write the same function with esresult, and clearly demonstrate/articulate the advantage of the latter.
- Remove motivation links or clearly explain how you're different - you mention you're motivated by neverthrow and provide a link. I click through to that link and see a library with more usage, more stars and more complete documentation. I now have to read through all of neverthrow's documentation to understand how they work and how they're different to esresult (assuming I read the complete esresult documentation). I feel like you're overestimating people's willingness to read up on library documentation before running a quick
npm install. Short on time, I would just opt with neverthrow.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent