co-author-to-username

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

<a href="https://codecov.io/gh/JoshuaKGoldberg/co-author-to-username"><img src="https://codecov.io/gh/JoshuaKGoldberg/co-author-to-username/branch/main/graph/badge.svg" alt="Codecov Test Coverage"></a>
<a href="https://github.com/JoshuaKGoldberg/co-author-to-username/blob/main/.github/CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/code_of_conduct-enforced-21bb42" alt="Contributor Covenant"></a>
<a href="https://github.com/JoshuaKGoldberg/co-author-to-username/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/JoshuaKGoldberg/co-author-to-username?color=21bb42" alt="License: MIT"></a>
<img src="https://img.shields.io/badge/style-prettier-21bb42.svg" alt="Style: Prettier">
<img src="https://img.shields.io/badge/typescript-strict-21bb42.svg" alt="TypeScript: Strict">
<img src="https://img.shields.io/npm/v/create-typescript-app?color=21bb42" alt="npm package version">

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: "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.

await coAuthorToUsername(
	{ email: "mock-data@example.com" },
	{ 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: "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.

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)

Contributors

Josh Goldberg 🔧 🐛 💻 🚧 👀 📖 🚇

> 💙 This package was templated with create-typescript-app.