co-author-to-username

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

Usage

``shell
npm i co-author-to-username
`

$3

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

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

await coAuthorToUsername({ email: "github@joshuakgoldberg.com" });
// 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 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.

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

$3

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.

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

const cachingCoAuthorToUsername = createCachingCoAuthorToUsername();

await cachingCoAuthorToUsername({ email: "github@joshuakgoldberg.com" });
// Result: "JoshuaKGoldberg" (via a network request)

await cachingCoAuthorToUsername({ email: "github@joshuakgoldberg.com" });
// 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.

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

await cachingCoAuthorToUsername({ email: "mock-data@example.com" });
// Result: "mock-data" (via the fetcher option)

await cachingCoAuthorToUsername({ email: "mock-data@example.com" });
// 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.