# co-author-to-username
> Fetches the GitHub username for a co-author, if possible. ๐
Latest version **0.1.3** (published 2025-05-27) ยท MIT license ยท 0 weekly downloads
## Install
```sh
npm install co-author-to-username
pnpm add co-author-to-username
yarn add co-author-to-username
bun add co-author-to-username
```
## Health
**Score 60/100 (C)** โ status: stable.
Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.
Warnings: low downloads; pre 1.0.
Negative: stale.
## Facts
| | |
|---|---|
| Version | 0.1.3 |
| Published | 2025-05-27 |
| First published | 2023-11-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 2 |
| Unpacked size | 12.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 3 |
| Author | Josh Goldberg |
| Maintainers | joshuakgoldberg |
## Links
- npm: https://www.npmjs.com/package/co-author-to-username
- Repository: https://github.com/JoshuaKGoldberg/co-author-to-username
- Homepage: https://github.com/JoshuaKGoldberg/co-author-to-username#readme
- Issues: https://github.com/JoshuaKGoldberg/co-author-to-username/issues
- npm.io page: https://npm.io/package/co-author-to-username
## Dependencies (2)
- [octokit](https://npm.io/package/octokit.md) ^5.0.0
- [cached-factory](https://npm.io/package/cached-factory.md) ^0.1.0
## Recent versions
- 0.1.3 (latest) โ 2025-05-27
- 0.1.2 โ 2025-04-03
- 0.1.1 โ 2024-08-10
- 0.1.0 โ 2023-11-24
## README
co-author-to-username
Fetches the GitHub username for a co-author, if possible.
๐
## Usage
```shell
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`](https://github.com/JoshuaKGoldberg/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](https://octokit.github.io) 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"
```
### `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](https://github.com/JoshuaKGoldberg/cached-factory) 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`](./.github/CONTRIBUTING.md), then [`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md).
Thanks! ๐
## Contributors
> ๐ This package was templated with [`create-typescript-app`](https://github.com/JoshuaKGoldberg/create-typescript-app) using the [Bingo engine](https://create.bingo).
---
_Source: https://npm.io/package/co-author-to-username ยท Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
