github-url-parser

A TypeScript-friendly GitHub URL parser for npm.

Installation

npm install github-url-parser

Usage

import { parseGitHubUrl } from "github-url-parser";

const result = parseGitHubUrl(
  "https://github.com/AlightSoulmate/github-url-parser/blob/main/package.json"
);

console.log(result);

{
  owner: "AlightSoulmate",
  repo: "github-url-parser",
  domain: "github.com",
  type: "github",
  kind: "blob",
  committish: "main",
  repoUrl: "https://github.com/AlightSoulmate/github-url-parser",
  browseUrl: "https://github.com/AlightSoulmate/github-url-parser/blob/main/package.json",
  apiUrl: "https://api.github.com/repos/AlightSoulmate/github-url-parser/contents/package.json?ref=main",
  httpsUrl: "https://github.com/AlightSoulmate/github-url-parser.git",
  sshUrl: "[email protected]:AlightSoulmate/github-url-parser.git",
  ref: "main",
  path: "package.json",
  rawUrl: "https://raw.githubusercontent.com/AlightSoulmate/github-url-parser/main/package.json"
}

API

parseGitHubUrl(url)

Parses url and returns a metadata object for supported GitHub URLs. Returns null when the input cannot be parsed as a supported GitHub resource.

Supported Inputs

https://github.com/user/repo
https://github.com/user/repo.git
[email protected]:user/repo.git
github:user/repo
user/repo

https://github.com/user/repo/tree/main/src
https://github.com/user/repo/blob/main/src/index.js
https://github.com/user/repo/issues/123
https://github.com/user/repo/pull/456
https://github.com/user/repo/commit/d34ce11
https://github.com/user/repo/compare/main...dev
https://github.com/user/repo/releases
https://github.com/user/repo/releases/tag/v1.0.0
https://github.com/user/repo/releases/latest
https://github.com/user/repo/tags
https://github.com/user/repo/branches
https://github.com/user/repo/discussions
https://github.com/user/repo/discussions/123
https://github.com/user/repo/actions
https://github.com/user/repo/actions/runs/123456789

Result Object

{
  owner: "user",
  repo: "repo",
  domain: "github.com",
  type: "github",
  kind: "repo",
  committish: null,
  repoUrl: "https://github.com/user/repo",
  browseUrl: "https://github.com/user/repo",
  apiUrl: "https://api.github.com/repos/user/repo",
  httpsUrl: "https://github.com/user/repo.git",
  sshUrl: "[email protected]:user/repo.git"
}

Additional fields are included for specific resource types:

| kind | URL type | Additional fields | | --- | --- | --- | | repo | Repository or remote | None | | blob | File browser URL | ref, path, rawUrl | | tree | Directory browser URL | ref, path, rawUrl: null | | issue | Issue URL | number | | pull | Pull request URL | number | | commit | Commit URL | sha | | release | Release tag URL | tag | | releases | Releases collection | collection | | latest-release | Latest release URL | selector | | compare | Compare URL | range, baseRef, headRef | | tags | Tags collection | collection | | branches | Branches collection | collection | | discussions | Discussions collection | collection | | discussion | Discussion URL | number | | actions | Actions collection | collection | | workflow-run | Workflow run URL | runId |

Examples

SSH remote

parseGitHubUrl("[email protected]:user/repo.git");
// {
//   owner: "user",
//   repo: "repo",
//   domain: "github.com",
//   type: "github",
//   kind: "repo",
//   committish: null,
//   repoUrl: "https://github.com/user/repo",
//   browseUrl: "https://github.com/user/repo",
//   apiUrl: "https://api.github.com/repos/user/repo",
//   httpsUrl: "https://github.com/user/repo.git",
//   sshUrl: "[email protected]:user/repo.git"
// }

Repository shorthand

parseGitHubUrl("github:AlightSoulmate/github-url-parser#v0.1.0");
// {
//   owner: "AlightSoulmate",
//   repo: "github-url-parser",
//   domain: "github.com",
//   type: "github",
//   kind: "repo",
//   committish: "v0.1.0",
//   repoUrl: "https://github.com/AlightSoulmate/github-url-parser",
//   browseUrl: "https://github.com/AlightSoulmate/github-url-parser/tree/v0.1.0",
//   apiUrl: "https://api.github.com/repos/AlightSoulmate/github-url-parser",
//   httpsUrl: "https://github.com/AlightSoulmate/github-url-parser.git#v0.1.0",
//   sshUrl: "[email protected]:AlightSoulmate/github-url-parser.git#v0.1.0"
// }

Issue

parseGitHubUrl("https://github.com/user/repo/issues/123");
// {
//   owner: "user",
//   repo: "repo",
//   domain: "github.com",
//   type: "github",
//   kind: "issue",
//   committish: null,
//   repoUrl: "https://github.com/user/repo",
//   browseUrl: "https://github.com/user/repo/issues/123",
//   apiUrl: "https://api.github.com/repos/user/repo/issues/123",
//   httpsUrl: "https://github.com/user/repo.git",
//   sshUrl: "[email protected]:user/repo.git",
//   number: 123
// }

File URL

parseGitHubUrl("https://github.com/user/repo/blob/main/src/index.js");
// {
//   owner: "user",
//   repo: "repo",
//   domain: "github.com",
//   type: "github",
//   kind: "blob",
//   committish: "main",
//   repoUrl: "https://github.com/user/repo",
//   browseUrl: "https://github.com/user/repo/blob/main/src/index.js",
//   apiUrl: "https://api.github.com/repos/user/repo/contents/src/index.js?ref=main",
//   httpsUrl: "https://github.com/user/repo.git",
//   sshUrl: "[email protected]:user/repo.git",
//   ref: "main",
//   path: "src/index.js",
//   rawUrl: "https://raw.githubusercontent.com/user/repo/main/src/index.js"
// }

Compare

parseGitHubUrl("https://github.com/user/repo/compare/main...dev");
// {
//   owner: "user",
//   repo: "repo",
//   domain: "github.com",
//   type: "github",
//   kind: "compare",
//   committish: null,
//   repoUrl: "https://github.com/user/repo",
//   browseUrl: "https://github.com/user/repo/compare/main...dev",
//   apiUrl: "https://api.github.com/repos/user/repo/compare/main...dev",
//   httpsUrl: "https://github.com/user/repo.git",
//   sshUrl: "[email protected]:user/repo.git",
//   range: "main...dev",
//   baseRef: "main",
//   headRef: "dev"
// }

Behavior Notes

• Only github.com URLs are supported.
• API URLs and raw file URLs are generated strings; they are not validated with the GitHub API.

Development

npm test

Runs both AVA and TSD test.

License

MIT