README
repository-provider
abstract interface to git repository providers like github, bitbucket, gitlab, gitea, ...
see list of avaliable implementations below
Example
import { Provider } from 'repository-provider';
const provider = new Provider({ token: 'xxx' });
const branch = await provider.branch('myuser/myrepo#myBranch');
for await (const entry of branch.entries('**/*.md')) {
console.log(entry.name);
}
const readme = await branch.entry('README.md');
console.log(await readme.getString());
Derived Providers
list by repository-provider keyword
API
Table of Contents
- Application
- Attribute
- definePropertiesFromOptions
- defaultValues
- setAttribute
- getAttribute
- optionJSON
- mapAttributes
- mapAttributesInverse
- BaseObject
- description
- id
- uuid
- avatarURL
- homePageURL
- MessageDestination
- BaseProvider
- Properties
- equals
- repositoryBases
- normalizeRepositoryName
- normalizeGroupName
- areRepositoryNamesCaseSensitive
- areGroupNamesCaseSensitive
- supportsBase
- parseName
- createRepository
- list
- projects
- milestones
- repositories
- branches
- tags
- hooks
- pullRequests
- name
- fullName
- provider
- url
- toJSON
- repositoryGroupClass
- hookClass
- repositoryClass
- branchClass
- tagClass
- entryClass
- pullRequestClass
- instanceIdentifier
- optionsFromEnvironment
- areOptionsSufficcient
- initialize
- priority
- name
- messageDestination
- Branch
- CommitResult
- Commit
- Hook
- Issue
- Milestone
- MultiGroupProvider
- NamedObject
- Project
- PullRequest
- title
- body
- state
- locked
- merged
- draft
- ContentEntry
- Ref
- isProtected
- RepositoryGroup
- type
- url
- RepositoryOwner
- Repository
- Parameters
- Properties
- fullName
- slug
- provider
- identifier
- equals
- entry
- entries
- maybeEntry
- urls
- url
- cloneURL
- issuesURL
- homePageURL
- condensedName
- isArchived
- isLocked
- isDisabled
- isTemplate
- defaultBranch
- branch
- branches
- createBranch
- addBranch
- deleteBranch
- tag
- tags
- addTag
- delete
- createPullRequest
- addPullRequest
- pullRequests
- pullRequest
- deletePullRequest
- addHook
- createHook
- hooks
- hook
- type
- refId
- toJSON
- attributes
- defaultBranchName
- urls
- issuesURL
- Review
- SingleGroupProvider
- Tag
- asArray
- stripBaseName
- stripBaseNames
- generateBranchName
Application
Extends NamedObject
Parameters
owner
name
options
Attribute
Type: Object
Properties
type
stringwritable
booleanprivate
boolean? should the value be showndescription
stringdefault
any? the default valueenv
(string | Array<string>)? environment variable use to provide the value
definePropertiesFromOptions
- See: Object.definedProperties()
- See: Object.getOwnPropertyDescriptor()
Create properties from options and default options. Already present properties (direct) are skipped. The attribute list from the class will be applied to the options and merged with the given set of properties.
class aClass {
static get attributes() {
return { with_default: { default: 77 }};
}
}
definePropertiesFromOptions(new aClass());
// equivalent to
Object.definedProperties(new aClass(),{ with_default: { value: 77 }})
Parameters
object
Object target objectoptions
Object as passed to object constructor (optional, default{}
)properties
Object object properties (optional, default{}
)attributes
Object (optional, defaultobject.constructor.attributes||[]
)
defaultValues
Get default values.
Parameters
attributes
Objectobject
Returns Object filled with default values
setAttribute
Set Object attribute. The name may be a property path like 'a.b.c'.
Parameters
getAttribute
Deliver attribute value. The name may be a property path like 'a.b.c'.
Parameters
Returns any value associated with the given property name
optionJSON
Create json based on present options. In other words only produce key value pairs if value is defined.
Parameters
object
Objectinitial
Object (optional, default{}
)attributes
Object to operator on (optional, defaultobject.constructor.attributes
)
Returns Object initial + defined values
mapAttributes
Rename attributes. Filters out null, undefined and empty strings.
mapAttributes({a:1},{a:"a'"}) // {"a'": 1}
Parameters
Returns Object keys renamed after mapping
mapAttributesInverse
Same as mapAttributes but with the inverse mapping. Filters out null, undefined and empty strings
Parameters
Returns Object keys renamed after mapping
BaseObject
Parameters
update
Save object attributes in the backing store.
equals
Check for equality
Parameters
other
BaseObject
Returns boolean true if other is present
provider
The provider we live in.
Returns BaseProvider
info
Forwarded to the owner.
Parameters
args
...any
warn
Forwarded to the owner.
Parameters
args
...any
error
Forwarded to the owner.
Parameters
args
...any
repositoryClass
By default we use the owners implementation.
Returns Class as defined in the owner
pullRequestClass
By default we use the owners implementation.
Returns Class as defined in the owner
branchClass
By default we use the owners implementation.
Returns Class as defined in the owner
tagClass
By default we use the owners implementation.
Returns Class as defined in the owner
entryClass
By default we use the owners implementation.
Returns Class as defined in the owner
hookClass
By default we use the owners implementation.
Returns Class as defined in the owner
attributes
Attributes definitions
writableAttributes
Returns Object writable attributes
attributeMapping
Map attributes between external and internal representation.
Returns Object
description
The description of the repository content.
Returns string
id
Unique id within the provider.
Returns string
uuid
Unique id.
Returns string
avatarURL
Avatar.
Returns string
homePageURL
The url of home page.
Returns string
MessageDestination
Type: Object
Parameters
BaseProvider
Extends BaseObject
Properties
messageDestination
MessageDestination
equals
Parameters
other
Returns boolean true if other provider is the same as the receiver
repositoryBases
All supported base urls. For github something like:
- git@github.com
- git://github.com
- git+ssh://github.com
- https://github.com
- git+https://github.com
Returns Array<string> common base urls of all repositories
normalizeRepositoryName
Bring a repository name into its normal form by removing any clutter. like .git suffix or #branch names.
Parameters
Returns string normalized name
normalizeGroupName
Bring a group name into its normal form by removing any clutter. like .git suffix or #branch names.
Parameters
Returns string normalized name
areRepositoryNamesCaseSensitive
Are repository names case sensitive. Overwrite and return false if you want to have case insensitive repository lookup
Returns boolean true
areGroupNamesCaseSensitive
Are repositroy group names case sensitive. Overwrite and return false if you want to have case insensitive group lookup
Returns boolean true
supportsBase
Does the provider support the base name.
Parameters
base
string to be checked
Returns boolean true if base is supported or base is undefined
parseName
Parses repository name and tries to split it into base, group, repository and branch.
Parameters
Returns Object with separated attributes
createRepository
Create a repository.
Parameters
Returns Promise<Repository>
list
List provider objects of a given type.
Parameters
type
string name of the method to deliver typed iterator projects,milestones,hooks,repositories,branches,tagspatterns
(string | Array<string>) group / repository filter
projects
List projects.
Parameters
Returns AsyncIterator<Project> all matching projects of the provider
milestones
List milestones.
Parameters
Returns AsyncIterator<Milestone> all matching milestones of the provider
repositories
List repositories.
Parameters
Returns AsyncIterator<Repository> all matching repos of the provider
branches
List branches.
Parameters
Returns AsyncIterator<Branch> all matching branches of the provider
tags
List tags.
Parameters
Returns AsyncIterator<Tag> all matching tags of the provider
hooks
List hooks.
Parameters
Returns AsyncIterator<Hook> all matching hooks of the provider
pullRequests
List pull requests.
Parameters
Returns AsyncIterator<PullRequest> all matching pullRequests of the provider
name
Deliver the provider name.
Returns string class name by default
fullName
Returns string name
provider
We are our own provider.
Returns BaseProvider this
url
Returns any url otf the provider.
toJSON
List all defined entries from attributes. return {object}
repositoryGroupClass
Returns Class repository group class used by the Provider
hookClass
Returns Class hook class used by the Provider
repositoryClass
Returns Class repository class used by the Provider
branchClass
Returns Class branch class used by the Provider
tagClass
Returns Class branch class used by the Provider
entryClass
Returns Class entry class used by the Provider
pullRequestClass
Returns Class pull request class used by the Provider
instanceIdentifier
Returns string identifier for environment options
optionsFromEnvironment
Extract options suitable for the constructor form the given set of environment variables.
Parameters
env
Object taken from process.envinstanceIdentifier
string (optional, defaultthis.instanceIdentifier
)
Returns Object undefined if no suitable environment variables have been found
areOptionsSufficcient
Check if given options are sufficient to create a provider.
Parameters
options
Object
Returns boolean true if options ar sufficient to construct a provider
initialize
Creates a new provider for a given set of options.
Parameters
options
Object additional options (optional, default{}
)options.instanceIdentifier
string? name of the provider instance
env
Object taken from process.env
Returns BaseProvider newly created provider or undefined if options are not sufficient to construct a provider
priority
In case there are several provider able to support a given source which one sould be used ? this defines the order
name
Name of the provider
messageDestination
to forward info/warn and error messages to
Branch
Extends Ref
Abstract branch.
Parameters
repository
Repositoryname
string (optional, defaultrepository.defaultBranchName
)options
Object
Properties
repository
Repositoryprovider
Providername
string
url
Deliver repository and branch url combined.
Returns string 'repoUrl#branch'
refType
Returns string tags
isDefault
Are we the default branch.
Returns boolean true if name matches the repository default branch
delete
Delete the branch from the Repository.
Returns Promise<any>
commit
Commit entries.
Parameters
message
string commit messageupdates
Array<ContentEntry> content to be commitedoptions
Object
Returns Promise<CommitResult>
commitIntoPullRequest
Add commits into a pull request.
Parameters
options
Objectoptions.pullRequestBranch
(Branch | string) to commit intooptions.dry
boolean do not create a branch and do not commit only create dummy PRoptions.skipWithoutCommits
boolean do not create a PR if no commits are givenoptions.bodyFromCommitMessages
boolean generate body from commit messagesoptions.body
string? body of the PR
Returns Promise<PullRequest>
removeEntries
Remove entries form the branch.
Parameters
entries
AsyncIterator<ContentEntry>
createPullRequest
Create a pull request.
Parameters
Returns Promise<PullRequest>
createBranch
Create a new Branch by cloning a given source branch. Simply calls Repository.createBranch() with the receiver as source branch
Parameters
Returns Promise<Branch> newly created branch (or already present old one with the same name)
CommitResult
Type: Object
Properties
ref
string
Commit
Parameters
repository
Properties
repository
Repositorymessage
stringsha
string
Hook
Extends BaseObject
Repository hook.
Parameters
repository
Repositoryid
stringevents
Set<string> (optional, defaultnew Set(["*"])
)options
Object
Properties
repository
Repositoryurl
URLevents
Set<string>
equals
Check for equality.
Parameters
other
Hook
Returns boolean true if name and repository are equal
toJSON
Provide name, events and all defined attributes.
Issue
Extends NamedObject
Parameters
owner
name
options
Milestone
Extends NamedObject
Parameters
owner
name
options
MultiGroupProvider
Extends BaseProvider
Provider supporting serveral repository groups.
Parameters
options
repository
Lookup a repository in the provider and all of its repository groups.
Parameters
name
string of the repository
Returns Promise<Repository>
branch
Lookup a branch.
Parameters
name
string of the branch
repositoryGroup
Lookup a repository group.
Parameters
name
string of the group
Returns Promise<RepositoryGroup>
repositoryGroups
List groups.
Parameters
Returns AsyncIterator<RepositoryGroup> all matching repositories groups of the provider
createRepositoryGroup
Create a new repository group. If there is already a group for the given name it will be returend instead
Parameters
Returns Promise<RepositoryGroup>
addRepositoryGroup
Add a new repository group (not provider specific actions are executed).
Parameters
Returns RepositoryGroup
NamedObject
Extends BaseObject
Object with a name.
Parameters
Properties
name
string
equals
Check for equality.
Parameters
other
NamedObject
Returns boolean true if names are equal
displayName
Beautified name use for human displaying only.
Returns string human readable name
fullName
Returns string name with owner name
toJSON
Provide name and all defined attributes.
Project
Extends NamedObject
Parameters
owner
name
options
PullRequest
Extends NamedObject
Abstract pull request. Repository#addPullRequest
Parameters
Properties
name
stringsource
Branchdestination
Branchtitle
string?state
string?merged
boolean?locked
boolean?url
string
fullName
Name of the PR together with the repository.
Returns string PR full name
url
URL of the pull request.
Returns string url
repository
Returns Repository destination repository
provider
Returns BaseProvider
equals
Check for equality
Parameters
other
PullRequest
Returns boolean true if number and repository are equal
delete
Delete the pull request from the Repository.
Returns Promise
merge
Merge the pull request.
Parameters
method
string (optional, default"MERGE"
)
decline
Decline the pull request.
reviews
Returns AsyncIterator<Review>
identifier
Short human readable identifier with provider and branch.
Returns string
validStates
All valid states
Returns Set<string> valid states
defaultListStates
States to list pull request by default
Returns Set<string> states to list by default
validMergeMethods
All valid merge methods
Returns Set<string> valid merge methods
list
List all pull request for a given repo result will be filtered by source branch, destination branch and states
Parameters
repository
Repositoryfilter
Object
Returns AsyncIterator<PullRequest>
open
Open a pull request
Parameters
title
The one line description of the pull request.
Returns string
body
The description of the pull request.
Returns string
state
state of the pull request.
- OPEN
- MERGED
- CLOSED
Returns string
locked
Locked state of the pull request.
Returns boolean
merged
Merged state of the pull request.
Returns boolean
draft
Draft state of the pull request.
Returns boolean
ContentEntry
Type: Object
Properties
name
string
Ref
Extends NamedObject
Base for Branch and Tag
Parameters
repository
name
options
equals
Check for equality.
Parameters
other
Ref
Returns boolean true if name and repository are equal
ref
ref name.
Returns string git ref of the Ref
refId
Get sha of a ref.
Parameters
ref
string (optional, defaultthis.ref
)
Returns Promise<string> sha of the ref
entries
List entries of the branch.
Parameters
Returns AsyncIterator<ContentEntry> all matching entries in the branch
asyncIterator
List all entries of the branch.
Returns AsyncIterator<ContentEntry> all entries in the branch
maybeEntry
Get exactly one matching entry by name or undefine if no such entry is found.
Parameters
name
string
Returns Promise<ContentEntry>
entry
Get exactly one matching entry by name (throws if entry is not found).
Parameters
name
string
Returns Promise<ContentEntry>
owner
- See: Repository#owner
Branch owner. By default we provide the repository owner
Returns string
fullName
Repository and branch name combined.
Returns string 'repo#branch'
fullCondensedName
Repository fullName and branch name combined. But skipping the branch name if it is the default branch
Returns string 'user/repo#branch'
identifier
Short human readable identifier with provider and branch.
Returns string
issuesURL
- See: Repository#issuesURL
Url of issue tracking system.
Returns string as provided from the repository
homePageURL
Url of home page.
Returns string as provided from the repository
isLocked
Forwarded from the repository
isArchived
Forwarded from the repository
isDisabled
Forwarded from the repository
isProtected
Returns any false
isWritable
Returns any true if not isArchived and isDisabled and isLocked
attributes
options
isProtected
Can the branch be modified.
Returns string
RepositoryGroup
Extends RepositoryOwner(NamedObject)
Abstract repository collection.
Parameters
provider
BaseProvidername
string of the groupoptions
Object
Properties
provider
BaseProvidername
string
attributeMapping
Map attributes between external and internal representation.
type
Type of the repository group either User or Organization.
Returns string
url
api url
RepositoryOwner
Mixin to define a class able to handle a collection of repositories.
Parameters
base
Class to be extendet
Repository
Extends NamedObject
Abstract repository
Parameters
Properties
owner
Ownername
string without (#branch)description
string? from options.descriptionid
string? from options.idbranches
Map<string, Branch>tags
Map<string, Tag>pullRequests
Map<string, PullRequest>milestones
Map<string, Milestone>
fullName
Full repository name within the provider.
Returns string full repo name
slug
URL name of the repo.
Returns string
provider
The owners provider.
Returns BaseProvider
identifier
Short human readable identifier with provider and branch.
Returns string
equals
Check for equality.
Parameters
other
Repository
Returns boolean true if name and provider are equal
entry
Lookup entries form the head of the default branch. Branch#entry
Parameters
name
Returns Promise<ContentEntry>
entries
List entries of the default branch.
Parameters
Returns AsyncIterator<ContentEntry> all matching entries in the branch
maybeEntry
Get exactly one matching entry by name or undefined if no such entry is found.
Parameters
name
string
Returns Promise<ContentEntry>
urls
Urls to access the repo.
url
Preffered url to access the repo.
Returns string
cloneURL
The url used fro cloning the repo.
Returns string
issuesURL
The url of issue tracking system.
Returns string
homePageURL
The url of home page.
Returns string
condensedName
Name without owner.
Returns string name
isArchived
By default we are not archived.
Returns boolean false
isLocked
By default we are not locked.
Returns boolean false
isDisabled
By default we are not disabled.
Returns boolean false
isTemplate
By default we are not a template.
Returns boolean false
defaultBranch
Lookup the default branch.
Returns Promise<Branch> branch named after defaultBranchName
branch
Lookup branch by name.
Parameters
name
string
branches
Parameters
patterns
Returns AsyncIterator<Branch> of all branches
createBranch
Create a new Branch by cloning a given source branch.
Parameters
Returns Promise<Branch> newly created branch (or already present old one with the same name)
addBranch
Add a new Branch. Internal branch creation does not call repository.initialize()
Parameters
Returns Branch newly created branch
deleteBranch
Delete a Branch.
Parameters
name
string of the branch
Returns Promise<any>
tag
Get a Tag.
Parameters
name
string
tags
Parameters
Returns AsyncIterator<Tag> of all tags
addTag
Add a new Tag. Internal tag creation does not call repository.initialize()
Parameters
Returns Tag newly created tag
delete
Delete the repository from the Provider. Provider#deleteRepository
Returns Promise<any>
createPullRequest
Create a pull request (or deliver an already present for thefiven name).
Parameters
Returns Promise<PullRequest>
addPullRequest
Add a pull request.
Parameters
Returns PullRequest
pullRequests
Deliver all PullRequests.
Returns AsyncIterator<PullRequest> of all pull requests
pullRequest
The @{link PullRequest} for a given name.
Parameters
name
string
Returns Promise<PullRequest>
deletePullRequest
Delete a PullRequest.
Parameters
name
string
Returns Promise<any>
addHook
Add a Hook.
Parameters
hook
Hook
createHook
Add a new Hook.
Parameters
hook
Hook
hooks
List hooks.
Returns AsyncIterator<Hook> all hooks of the repository
hook
Get a Hook.
Parameters
Returns Promise<Hook> for the given id
type
Get type of the repository.
Returns string 'git'
refId
Get sha of a ref.
Parameters
ref
string
Returns Promise<string> sha of the ref
toJSON
Provide name and all defined attributes
attributes
options
defaultBranchName
The name of the default branch
Returns string
urls
URLs of the repository
issuesURL
The url of issue tracking system.
Returns string
Review
Extends BaseObject
SingleGroupProvider
Extends RepositoryOwner(BaseProvider)
Provider holding a single set of repositories (no repository groups).
repository
Lookup a repository in the provider and all of its repository groups.
Parameters
name
string of the repository
Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise