co-author-to-username

Fetches the GitHub username for a co-author, if possible. 📇

Usage

npm i co-author-to-username

coAuthorToUsername

This package exports a coAuthorToUsername function that can be used to fetch the corresponding GitHub user from a commit-to-co-author-style co-author:

1. If the given co-author has a username, that username is returned directly
2. If the given co-author has an email, the Octokit API is used to search for the first matching user on that exact email

import { coAuthorToUsername } from "co-author-to-username";

await coAuthorToUsername({ email: "[email protected]" });
// Result: "JoshuaKGoldberg"

await coAuthorToUsername({ username: "JoshuaKGoldberg" });
// Result: "JoshuaKGoldberg"

If no corresponding username is found, the function resolves with undefined.

coAuthorToUsername Options

coAuthorToUsername may take in an optional options object with a fetcher property. fetcher can be either an Octokit or your own function to take in an email: string and return a Promise<string | undefined> for the equivalent email. This can be useful if you want to use your own caching fetcher and/or stub out network requests in tests.

await coAuthorToUsername(
	{ email: "[email protected]" },
	{ fetcher: async (email) => email.split("@")[0] },
);
// Result: "mock-data"

createCachingCoAuthorToUsername

As a convenience, this package also exports a createCachingCoAuthorToUsername that can be used to create a version of coAuthorToUsername that caches its email lookups. It uses a CachedFactory from the cached-factory package to store results keyed by emails.

import { createCachingCoAuthorToUsername } from "co-author-to-username";

const cachingCoAuthorToUsername = createCachingCoAuthorToUsername();

await cachingCoAuthorToUsername({ email: "[email protected]" });
// Result: "JoshuaKGoldberg" (via a network request)

await cachingCoAuthorToUsername({ email: "[email protected]" });
// Result: "JoshuaKGoldberg" (cached)

Note that the cachingCoAuthorToUsername functions created by createCachingCoAuthorToUsername cannot be given options. createCachingCoAuthorToUsername must be given any options.

createCachingCoAuthorToUsername Options

createCachingCoAuthorToUsername may take in an optional options object with a fetcher property. It works the same and serves similar purposes to coAuthorToUsername's fetcher.

const cachingCoAuthorToUsername = createCachingCoAuthorToUsername({
	fetcher: async (email) => email.split("@")[0],
});

await cachingCoAuthorToUsername({ email: "[email protected]" });
// Result: "mock-data" (via the fetcher option)

await cachingCoAuthorToUsername({ email: "[email protected]" });
// Result: "mock-data" (cached)

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 📇

Contributors

Josh Goldberg 🔧 🐛 💻 🚧 👀 📖 🚇 🖋 🤔 📆

💝 This package was templated with create-typescript-app using the Bingo engine.