github-url-parser

A TypeScript-friendly GitHub URL parser for npm.

Installation

npm install github-url-parser

Usage

import{parseGitHubUrl}from"github-url-parser";constresult=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: "git@github.com: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
git@github.com: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: "git@github.com: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("git@github.com: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: "git@github.com: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: "git@github.com: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: "git@github.com: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: "git@github.com: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: "git@github.com: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