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({ /* access options as hosts and credentials */ });
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.string);
Derived Providers
list by repository-provider keyword
API
Table of Contents
Application
Extends OwnedObject
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());
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, default object.constructor.attributes||[]
)
defaultValues
Get default values.
Parameters
Returns Object filled with default values
optionJSON
Create json based on present options.
In other words only produce key value pairs if value is defined.
Parameters
object
Object initial
Object (optional, default {}
)attributes
Object to operator on (optional, default object.constructor.attributes
)
Returns Object initial + defined values
mapAttributes
Rename attributes.
Filters out null, undefined and empty strings.
mapAttributes({a:1},{a:"a'"})
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
AttributeDefinition
Type: Object
Properties
type
string writable
boolean private
boolean? should the value be showndepends
string? name of an attribute we depend onadditionalAttributes
Array<string> extra attributes that are present in case our attribute is setdescription
string default
any? the default valueset
Function? set the valueget
Function? get the value can be used to calculate default valuesenv
(Array<string> | string)? environment variable use to provide the value
tokens
Split property path into tokens
Parameters
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
getAttributeAndOperator
Deliver attribute value and operator.
The name may be a property path like 'a.b.c <='.
Parameters
object
Object expression
string getters
(optional, default {}
)
Returns [any, string] value associated with the given property name
default_attribute
common attributes
description_attribute
The description of the object content.
id_attribute
Unique id within the provider.
body_attribute
The description of the pull request.
title_attribute
The one line description of the pull request.
priority_attribute
In case there are several providers able to support a given source which one sould be used ?
this defines the order
BaseObject
Creates an instance of BaseObject.
Parameters
updateAttributes
Takes values from options.
Parameters
update
Save object attributes in the backing store.
toString
Returns string fullName
displayName
Beautified name use for human displaying only.
Returns string human readable name
fullName
Complete name in the hierachy.
Returns string
fullCondensedName
Complete name in the hierachy.
Returns string
isWritable
By default cannot be written to.
Returns boolean false
equals
Check for equality
Parameters
Returns boolean true if other is present
type
Returns string type we represent
collectionName
Tag -> tags
Repository -> repositories
Returns string name of the collection holding us in the owner
attributes
Attributes definitions
Returns Object
writableAttributes
User modifyable attributes.
Returns Object writable attributes
attributeMapping
Map attributes between external and internal representation.
Returns Object
MessageDestination
Type: Object
Properties
BaseProvider
Extends BaseObject
Properties
equals
Parameters
Returns boolean true if other provider is the same as the receiver
repositoryBases
All supported base urls.
For github something like:
Returns Array<string> common base urls of all repositories
supportsBase
Does the provider support the base name.
Parameters
Returns boolean true if base is supported or base is undefined
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
parseName
Parses repository name and tries to split it into
base, group, repository and branch.
Parameters
name
string? focus
string where lies the focus if only one path component is given (optional, default "repository"
)
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
(Array<string> | string | undefined) 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
provider
We are our own provider.
Returns BaseProvider this
toJSON
List all defined entries from attributes.
return {object}
repositoryGroupClass
hookClass
repositoryClass
branchClass
tagClass
entryClass
pullRequestClass
instanceIdentifier
Prefix used to form environment variables.
'GITHUB_' -> 'GITHUB_TOKEN'
Returns string identifier for environment options
optionsFromEnvironment
Extract options suitable for the constructor.
Form the given set of environment variables.
Object with the detected key value pairs is delivered.
Parameters
env
Object? as from process.envinstanceIdentifier
string part of variable name. (optional, default this.instanceIdentifier
)
Returns (Object | undefined) undefined if no suitable environment variables have been found
areOptionsSufficcient
Check if given options are sufficient to create a provider.
Parameters
Returns boolean true if options ar sufficient to construct a provider
initialize
Creates a new provider for a given set of options.
Parameters
Returns (BaseProvider | undefined) newly created provider or undefined if options are not sufficient to construct a provider
name
Name of the provider.
messageDestination
To forward info/warn and error messages to
Branch
Type: Object
Parameters
Properties
url
Deliver repository and branch url combined.
Returns string 'repoUrl#branch'
refType
Returns string heades
isWritable
Returns any true if not isArchived and isDisabled and isLocked and isProtected
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
Returns Promise<CommitResult>
commitIntoPullRequest
Add commits into a pull request.
Parameters
Returns Promise<PullRequest>
removeEntries
Remove entries form the branch.
Parameters
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
Commit
Parameters
Properties
Hook
Extends OwnedObject
Repository hook.
Issue
Extends OwnedObject
Milestone
Extends OwnedObject
MultiGroupProvider
Extends BaseProvider
Provider supporting serveral repository groups.
repository
Lookup a repository in the provider and all of its repository groups.
Parameters
Returns Promise<(Repository | undefined)>
branch
Lookup a branch.
Parameters
Returns Promise<(Branch | undefined)>
repositoryGroup
Lookup a repository group.
Parameters
Returns Promise<(RepositoryGroup | undefined)>
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
equals
Check for equality.
Parameters
Returns boolean true if names are equal and have the same provider
toJSON
Provided name and all defined attributes.
OwnedObject
Extends NamedObject
Named Object registering itself in the owner.
Parameters
owner
name
options
additionalProperties
delete
Removes the receiver from the owner.
equals
Check for equality.
Parameters
Returns boolean true if receiver and owner are equal
homePageURL
Url of home page.
Returns string as provided from the owner
issuesURL
Url of issue tracking system.
Returns string as provided from the repository
isLocked
Forwarded from the owner.
Returns boolean
isArchived
Forwarded from the owner.
Returns boolean
isDisabled
Forwarded from the owner.
Returns boolean
api
API as given by the owner.
Returns string url
slug
API as given by the owner.
Returns string url
url
URL as given by the owner.
Returns string url
provider
The provider we live in.
Returns BaseProvider
identifier
Short human readable identifier with provider and branch.
Returns string
fullName
Returns string name with owner name
trace
Forwarded to the owner.
Parameters
info
Forwarded to the owner.
Parameters
warn
Forwarded to the owner.
Parameters
error
Forwarded to the owner.
Parameters
debug
Forwarded to the owner.
Parameters
repositoryClass
By default we use the owners implementation.
Returns Function as defined in the owner
pullRequestClass
By default we use the owners implementation.
branchClass
By default we use the owners implementation.
tagClass
By default we use the owners implementation.
entryClass
By default we use the owners implementation.
hookClass
By default we use the owners implementation.
addMethodName
Method name to be called to register one instance in the owner.
sample: Application => _addApplication
Returns string
deleteMethodName
Method name to be called to unregister one instance in the owner.
sample: Application => _deleteApplication
Returns string
Project
Extends OwnedObject
PullRequest
Extends OwnedObject
Abstract pull request.
Repository#addPullRequest
Parameters
Properties
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
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
defaultListStates
States to list pull request by default
Returns Set<string> states to list by default
states
possible states
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
Returns AsyncIterator<PullRequest>
open
Open a pull request
Parameters
state
state of the pull request.
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
Ref
Extends OwnedObject
Base for Branch and Tag
ref
Full ref path.
Returns string git ref of the Ref
refId
Get sha of our 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
Returns Promise<(ContentEntry | undefined)>
entry
Get exactly one matching entry by name (throws if entry is not found).
Parameters
Returns Promise<ContentEntry>
repository
Ref owner.
By default we provide the repository owner
Returns Repository
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'
isProtected
Returns any false
isDefault
Are we the default ref.
Returns boolean false
attributes
options
isProtected
Can the ref be modified.
Returns boolean
RepositoryGroup
Extends RepositoryOwner(OwnedObject)
Abstract repository collection.
Parameters
Properties
attributeMapping
Map attributes between external and internal representation.
type
Type of the repository group either User or Organization.
homePageURL
The url of home page.
Returns string
RepositoryOwner
Mixin to define a class able to handle a collection of repositories.
Parameters
Repository
Type: Object
Parameters
Properties
slug
Name of the repo as used in the URL.
Returns string
entry
Lookup entries form the head of the default branch.
Branch#entry
Parameters
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
Returns Promise<(ContentEntry | undefined)>
commits
List commits of the default branch.
Parameters
Returns AsyncIterator<Commit> all matching commits in the repository
cloneURL
The url used for cloning the repo.
Returns string
issuesURL
The url of issue tracking system.
Returns string
homePageURL
The url of home page.
Returns string
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
delete
Delete the repository from the Provider.
Provider#deleteRepository
Returns Promise<any>
defaultBranch
Lookup the default branch.
Returns Promise<(Branch | undefined)> branch named after defaultBranchName
branch
Lookup branch by name.
Parameters
Returns Promise<(Branch | undefined)>
hasBranches
Returns boolean true if there is at least one branch
branches
Parameters
Returns AsyncIterator<Branch> of all branches
createBranch
Create a new Branch by cloning a given source branch.
Parameters
name
string of the new branchsource
Branch branch defaults to the defaultBranchoptions
Object?
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
name
string of the new branchoptions
Object? to be passed to the branch
Returns Branch newly created branch
deleteBranch
Delete a Branch.
Parameters
Returns Promise<any>
tag
Get a Tag.
Parameters
Returns Promise<Tag>
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
createPullRequest
Create a pull request (or deliver an already present for the given 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 @see PullRequest for a given name.
Parameters
Returns Promise<(PullRequest | undefined)>
deletePullRequest
Delete a PullRequest.
Parameters
Returns Promise<any>
addHook
Add a new Hook.
Parameters
Returns Hook newly created hook
createHook
Add a new Hook.
Parameters
hooks
List hooks.
Returns AsyncIterator<Hook> all hooks of the repository
hook
Get a Hook.
Parameters
Returns Promise<(Hook | undefined)> for the given id
milestone
Get a Milestone.
Parameters
Returns Promise<(Milestone | undefined)> for the given name
project
Get a Project.
Parameters
Returns Promise<(Project | undefined)> for the given name
application
Get an Application.
Parameters
Returns Promise<(Application | undefined)> for the given name
type
Get type of the repository.
Returns string 'git'
refId
Get sha of a ref.
Parameters
Returns Promise<(string | undefined)> sha of the ref
attributes
options
defaultBranchName
The name of the default branch
Returns string
Review
Extends OwnedObject
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
Returns Promise<(Repository | undefined)>
repositoryGroup
Get a single group.
Parameters
Returns Promise<(RepositoryGroup | undefined)> deliver the one and only present group
repositoryGroups
List groups.
Parameters
Returns AsyncIterator<RepositoryGroup> always deliver the one and only present group
Tag
Extends Ref
Tag refs
refType
Returns string tags
asArray
Convert scalar into an array.
The value undefined will be represented as an empty array.
Parameters
Returns Array value encapsulated in an array
stripBaseName
Strip repository base name away.
A URL auth component will be removed to.
Parameters
Returns (string | undefined) name without base
stripBaseNames
Loops over names and executes stripBaseName.
Parameters
Returns (Array<string> | string | undefined) names without base
generateBranchName
Find a new branch name for a given pattern.
'' will be replaced by a number.
'something/' will get to something/1 something/2 ...
Parameters
Returns Promise<string>
install
With npm do:
npm install repository-provider
license
BSD-2-Clause