repository-provider 26.0.2 → 26.0.3

package/README.md

@@ -425,8 +425,7 @@ In other words only produce key value pairs if value is defined.
 
 *   `object` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** 
 *   `initial` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**  (optional, default `{}`)
-*   `attributes`   (optional, default `object.constructor.attributes`)
-*   `attibutes` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** to operator on
+*   `attributes` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** to operator on (optional, default `object.constructor.attributes`)
 
 Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** initial + defined values
 
@@ -776,7 +775,7 @@ Creates a new provider for a given set of options.
     *   `options.instanceIdentifier` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?** 
 *   `env` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** taken from process.env
 
-Returns **Provider** newly created provider or undefined if options are not sufficient to construct a provider
+Returns **[BaseProvider](#baseprovider)** newly created provider or undefined if options are not sufficient to construct a provider
 
 ## priority
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repository-provider",
-  "version": "26.0.2",
+  "version": "26.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -25,8 +25,9 @@
     "test:ava": "ava --timeout 2m tests/*.mjs",
     "cover": "c8 -x 'tests/**/*' --temp-directory build/tmp ava --timeout 2m tests/*.mjs && c8 report -r lcov -o build/coverage --temp-directory build/tmp",
     "docs": "documentation readme --section=API ./src/**/*.mjs",
-    "lint": "npm run lint:docs",
-    "lint:docs": "documentation lint ./src/**/*.mjs"
+    "lint": "npm run lint:docs && npm run lint:tsc",
+    "lint:docs": "documentation lint ./src/**/*.mjs",
+    "lint:tsc": "tsc --allowJs --checkJs --noEmit -module nodenext -t es2022 ./src/*.mjs"
   },
   "dependencies": {
     "matching-iterator": "^2.0.0"
@@ -35,8 +36,9 @@
     "ava": "^3.15.0",
     "c8": "^7.10.0",
     "documentation": "^13.2.5",
-    "repository-provider-test-support": "^1.8.11",
-    "semantic-release": "^18.0.1"
+    "repository-provider-test-support": "^1.8.14",
+    "semantic-release": "^18.0.1",
+    "typescript": "^4.6.0-dev.20211228"
   },
   "engines": {
     "node": ">=14.18.1"
@@ -52,7 +54,8 @@
   "template": {
     "inheritFrom": [
       "arlac77/template-arlac77-github",
-      "arlac77/template-esm-only"
+      "arlac77/template-esm-only",
+      "arlac77/template-typescript"
     ]
   }
 }

package/src/attribute.mjs

@@ -146,7 +146,7 @@ export function getAttribute(object, name) {
  * In other words only produce key value pairs if value is defined.
  * @param {Object} object
  * @param {Object} initial
- * @param {Object} attibutes to operator on
+ * @param {Object} attributes to operator on
  * @return {Object} initial + defined values
  */
 export function optionJSON(object, initial = {}, attributes=object.constructor.attributes) {

package/src/base-object.mjs

@@ -38,6 +38,10 @@ export class BaseObject {
        */
       avatarURL: { type: "url" },
 
+      /**
+       * The url of home page.
+       * @return {string}
+       */
       homePageURL: { type: "url", writable: true }
     };
   }

package/src/base-provider.mjs

@@ -4,7 +4,10 @@ import { PullRequest } from "./pull-request.mjs";
 import { RepositoryGroup } from "./repository-group.mjs";
 import { Repository } from "./repository.mjs";
 import { Branch } from "./branch.mjs";
+import { Tag } from "./tag.mjs";
 import { Hook } from "./hook.mjs";
+import { Project } from "./project.mjs";
+import { Milestone } from "./milestone.mjs";
 
 /**
  * @typedef {Object} MessageDestination
@@ -125,7 +128,7 @@ export class BaseProvider {
    * @param {Object} options additional options
    * @param {string?} options.instanceIdentifier
    * @param {Object} env taken from process.env
-   * @return {Provider} newly created provider or undefined if options are not sufficient to construct a provider
+   * @return {BaseProvider} newly created provider or undefined if options are not sufficient to construct a provider
    */
   static initialize(options = {}, env) {
     options = {
@@ -324,7 +327,7 @@ export class BaseProvider {
   /**
    * List projects.
    * @param {string[]|string} patterns
-   * @return {Iterator<Projects>} all matching projects of the provider
+   * @return {AsyncIterator<Project>} all matching projects of the provider
    */
   async *projects(patterns) {
     yield* this.list("projects", patterns);
@@ -333,16 +336,16 @@ export class BaseProvider {
   /**
    * List milestones.
    * @param {string[]|string} patterns
-   * @return {Iterator<Milestone>} all matching milestones of the provider
+   * @return {AsyncIterator<Milestone>} all matching milestones of the provider
    */
-  async *projects(patterns) {
+  async *milestones(patterns) {
     yield* this.list("milestones", patterns);
   }
 
   /**
    * List repositories.
    * @param {string[]|string} patterns
-   * @return {Iterator<Repository>} all matching repos of the provider
+   * @return {AsyncIterator<Repository>} all matching repos of the provider
    */
   async *repositories(patterns) {
     yield* this.list("repositories", patterns);
@@ -351,7 +354,7 @@ export class BaseProvider {
   /**
    * List branches.
    * @param {string[]|string} patterns
-   * @return {Iterator<Branch>} all matching branches of the provider
+   * @return {AsyncIterator<Branch>} all matching branches of the provider
    */
   async *branches(patterns) {
     yield* this.list("branches", patterns);
@@ -360,7 +363,7 @@ export class BaseProvider {
   /**
    * List tags.
    * @param {string[]|string} patterns
-   * @return {Iterator<Tag>} all matching tags of the provider
+   * @return {AsyncIterator<Tag>} all matching tags of the provider
    */
   async *tags(patterns) {
     yield* this.list("tags", patterns);
@@ -369,7 +372,7 @@ export class BaseProvider {
   /**
    * List hooks.
    * @param {string[]|string} patterns
-   * @return {Iterator<Hook>} all matching hooks of the provider
+   * @return {AsyncIterator<Hook>} all matching hooks of the provider
    */
   async *hooks(patterns) {
     yield* this.list("hooks", patterns);
@@ -378,7 +381,7 @@ export class BaseProvider {
   /**
    * List pull requests.
    * @param {string[]|string} patterns
-   * @return {Iterator<PullRequest>} all matching pullRequests of the provider
+   * @return {AsyncIterator<PullRequest>} all matching pullRequests of the provider
    */
   async *pullRequests(patterns) {
     yield* this.list("pullRequests", patterns);
@@ -408,7 +411,7 @@ export class BaseProvider {
 
   /**
    * We are our own provider.
-   * @return {Provider} this
+   * @return {BaseProvider} this
    */
   get provider() {
     return this;

package/src/branch.mjs

@@ -1,5 +1,6 @@
 import { Ref } from "./ref.mjs";
 import { PullRequest } from "./pull-request.mjs";
+import { Repository } from "./repository.mjs";
 
 /**
  * @typedef {Object} Commit
@@ -54,7 +55,7 @@ export class Branch extends Ref {
   /**
    * Delete the branch from the {@link Repository}.
    * @see {@link Repository#deleteBranch}
-   * @return {Promise<undefined>}
+   * @return {Promise<any>}
    */
   async delete() {
     return this.repository.deleteBranch(this.name);
@@ -65,7 +66,7 @@ export class Branch extends Ref {
    * @param {string} message commit message
    * @param {ContentEntry[]} updates content to be commited
    * @param {Object} options
-   * @return {CommitResult}
+   * @return {Promise<CommitResult>}
    */
   async commit(message, updates, options) {}
 
@@ -78,7 +79,7 @@ export class Branch extends Ref {
    * @param {boolean} options.dry do not create a branch and do not commit only create dummy PR
    * @param {boolean} options.skipWithoutCommits do not create a PR if no commits are given
    * @param {boolean} options.bodyFromCommitMessages generate body from commit messages
-   * @return {PullRequest}
+   * @return {Promise<PullRequest>}
    */
   async commitIntoPullRequest(commits, options) {
     const isBranch = options.pullRequestBranch instanceof Branch;
@@ -148,7 +149,7 @@ export class Branch extends Ref {
 
   /**
    * Remove entries form the branch.
-   * @param {Iterator <ContentEntry>} entries
+   * @param {AsyncIterator<ContentEntry>} entries
    */
   async removeEntries(entries) {}
 

package/src/hook.mjs

@@ -1,5 +1,6 @@
 import { optionJSON } from "./attribute.mjs";
 import { BaseObject } from "./base-object.mjs";
+import { Repository } from "./repository.mjs";
 
 /**
  * Repository hook.

package/src/multi-group-provider.mjs

@@ -1,6 +1,8 @@
 import { matcher } from "matching-iterator";
 import { BaseProvider } from "./base-provider.mjs";
 import { stripBaseNames } from "./util.mjs";
+import { Repository } from "./repository.mjs";
+import { RepositoryGroup } from "./repository-group.mjs";
 
 /**
  * Provider supporting serveral repository groups.
@@ -16,7 +18,7 @@ export class MultiGroupProvider extends BaseProvider {
   /**
    * Lookup a repository in the provider and all of its repository groups.
    * @param {string} name of the repository
-   * @return {Repository}
+   * @return {Promise<Repository>}
    */
   async repository(name) {
     const { base, group, repository } = this.parseName(name);
@@ -54,7 +56,7 @@ export class MultiGroupProvider extends BaseProvider {
   /**
    * Lookup a repository group.
    * @param {string} name of the group
-   * @return {RepositoryGroup}
+   * @return {Promise<RepositoryGroup>}
    */
   async repositoryGroup(name) {
     const { base } = this.parseName(name);
@@ -69,7 +71,7 @@ export class MultiGroupProvider extends BaseProvider {
   /**
    * List groups.
    * @param {string[]|string} patterns
-   * @return {Iterator<RepositoryGroup>} all matching repositories groups of the provider
+   * @return {AsyncIterator<RepositoryGroup>} all matching repositories groups of the provider
    */
   async *repositoryGroups(patterns) {
     await this.initializeRepositories();
@@ -89,7 +91,7 @@ export class MultiGroupProvider extends BaseProvider {
    * If there is already a group for the given name it will be returend instead
    * @param {string} name of the group
    * @param {Object} options
-   * @return {RepositoryGroup}
+   * @return {Promise<RepositoryGroup>}
    */
   async createRepositoryGroup(name, options) {
     return this.addRepositoryGroup(name, options);

package/src/named-object.mjs

@@ -35,7 +35,7 @@ export class NamedObject extends BaseObject {
   }
 
   /**
-   * Preserve object attributes in the backing store.
+   * Save object attributes in the backing store.
    */
   async update()
   {

package/src/pull-request.mjs

@@ -1,5 +1,9 @@
 import { optionJSON } from "./attribute.mjs";
 import { NamedObject } from "./named-object.mjs";
+import { Branch } from "./branch.mjs";
+import { Repository } from "./repository.mjs";
+import { Review } from "./review.mjs";
+import { BaseProvider } from "./base-provider.mjs";
 
 /**
  * Abstract pull request.
@@ -55,7 +59,7 @@ export class PullRequest extends NamedObject {
    * @param {Branch?} filter.source
    * @param {Branch?} filter.destination
    * @param {Set<string>?} filter.states
-   * @return {Iterator<PullRequest>}
+   * @return {AsyncIterator<PullRequest>}
    */
   static async *list(repository, filter) {}
 
@@ -206,7 +210,7 @@ export class PullRequest extends NamedObject {
   }
 
   /**
-   * @return {Provider}
+   * @return {BaseProvider}
    */
   get provider() {
     return this.destination === undefined
@@ -260,7 +264,7 @@ export class PullRequest extends NamedObject {
   async decline() {}
 
   /**
-   * @return {Interaor<Review>}
+   * @return {AsyncIterator<Review>}
    */
   async *reviews() {}
 

package/src/ref.mjs

@@ -1,5 +1,11 @@
 import { NamedObject } from "./named-object.mjs";
 
+/**
+ * @typedef {Object} ContentEntry
+ * @property {string} name
+ * 
+ */
+
 /**
  * Base for Branch and Tag
  */
@@ -25,7 +31,7 @@ export class Ref extends NamedObject {
 
   /**
    * Check for equality.
-   * @param {Branch} other
+   * @param {Ref} other
    * @return {boolean} true if name and repository are equal
    */
   equals(other) {
@@ -37,7 +43,7 @@ export class Ref extends NamedObject {
   }
 
   /**
-   * ref name
+   * ref name.
    * @return {string} git ref of the Ref
    */
   get ref() {
@@ -47,7 +53,7 @@ export class Ref extends NamedObject {
   /**
    * Get sha of a ref.
    * @param {string} ref
-   * @return {string} sha of the ref
+   * @return {Promise<string>} sha of the ref
    */
   async refId(ref = this.ref) {
     return this.repository.refId(ref);
@@ -56,13 +62,13 @@ export class Ref extends NamedObject {
   /**
    * List entries of the branch.
    * @param {string[]} matchingPatterns
-   * @return {ContentEntry} all matching entries in the branch
+   * @return {AsyncIterator<ContentEntry>} all matching entries in the branch
    */
   async *entries(matchingPatterns) {}
 
   /**
    * List all entries of the branch.
-   * @return {asyncIterator<ContentEntry>} all entries in the branch
+   * @return {AsyncIterator<ContentEntry>} all entries in the branch
    */
   async *[Symbol.asyncIterator]() {
     return yield* this.entries();
@@ -92,7 +98,7 @@ export class Ref extends NamedObject {
 
   /**
    * The provider we live in.
-   * @return {Provider}
+   * @return {BaseProvider}
    */
   get provider() {
     return this.repository.provider;

package/src/repository-group.mjs

@@ -1,9 +1,10 @@
 import { RepositoryOwner } from "./repository-owner.mjs";
 import { NamedObject } from "./named-object.mjs";
+import { BaseProvider } from "./base-provider.mjs";
 
 /**
  * Abstract repository collection.
- * @param {Provider} provider
+ * @param {BaseProvider} provider
  * @param {string} name of the group
  * @param {Object} options
  * @param {string} [options.description] human readable description
@@ -11,7 +12,7 @@ import { NamedObject } from "./named-object.mjs";
  * @param {string} [options.uuid] internal id
  * @param {string} [options.url] home
  *
- * @property {Provider} provider
+ * @property {BaseProvider} provider
  * @property {string} name
  */
 

package/src/repository-owner.mjs

@@ -1,5 +1,6 @@
 import { matcher } from "matching-iterator";
 import { Branch } from "./branch.mjs";
+import { Repository } from "./repository.mjs";
 import { asArray, stripBaseName, stripBaseNames } from "./util.mjs";
 
 /**
@@ -55,8 +56,8 @@ export function RepositoryOwner(base) {
 
     /**
      * List repositories for the owner.
-     * @param {string[]|string} matchingPatterns
-     * @return {Iterator<Repository>} all matching repositories of the owner
+     * @param {string[]|string} patterns
+     * @return {AsyncIterator<Repository>} all matching repositories of the owner
      */
     async *repositories(patterns) {
       patterns = asArray(patterns);
@@ -160,7 +161,7 @@ export function RepositoryOwner(base) {
     /**
      * Delete a repository.
      * @param {string} name
-     * @return {Promise<undefined>}
+     * @return {Promise<any>}
      */
     async deleteRepository(name) {
       this._repositories.delete(this.normalizeRepositoryName(name, true));
@@ -188,7 +189,7 @@ export function RepositoryOwner(base) {
     /**
      * List branches for the owner.
      * @param {string[]|string} patterns
-     * @return {Iterator<Branch>} all matching branches of the owner
+     * @return {AsyncIterator<Branch>} all matching branches of the owner
      */
     async *branches(patterns) {
       yield* this._list(

package/src/repository.mjs

@@ -1,6 +1,11 @@
 import { matcher } from "matching-iterator";
 import { optionJSON } from "./attribute.mjs";
 import { NamedObject } from "./named-object.mjs";
+import { Hook } from "./hook.mjs";
+import { Tag } from "./tag.mjs";
+import { Branch } from "./branch.mjs";
+import { PullRequest } from "./pull-request.mjs";
+import { BaseProvider } from "./base-provider.mjs";
 
 /**
  * Abstract repository
@@ -41,12 +46,6 @@ export class Repository extends NamedObject {
 
       cloneURL: { type: "url" },
 
-      /**
-       * The url of home page.
-       * @return {string}
-       */
-      homePageURL: { type: "url" },
-
       /**
        * The url of issue tracking system.
        * @return {string}
@@ -94,7 +93,7 @@ export class Repository extends NamedObject {
 
   /**
    * The owners provider.
-   * @return {Provider}
+   * @return {BaseProvider}
    */
   get provider() {
     return this.owner.provider;
@@ -126,7 +125,7 @@ export class Repository extends NamedObject {
   /**
    * Lookup entries form the head of the default branch.
    * {@link Branch#entry}
-   * @return {Entry}
+   * @return {Promise<ContentEntry>}
    */
   async entry(name) {
     return (await this.defaultBranch).entry(name);
@@ -135,7 +134,7 @@ export class Repository extends NamedObject {
   /**
    * List entries of the default branch.
    * @param {string[]} matchingPatterns
-   * @return {Entry} all matching entries in the branch
+   * @return {AsyncIterator<ContentEntry>} all matching entries in the branch
    */
   async *entries(matchingPatterns) {
     yield* (await this.defaultBranch).entries(matchingPatterns);
@@ -144,7 +143,7 @@ export class Repository extends NamedObject {
   /**
    * Get exactly one matching entry by name or undefined if no such entry is found.
    * @param {string} name
-   * @return {Promise<Entry>}
+   * @return {Promise<ContentEntry>}
    */
   async maybeEntry(name) {
     return (await this.defaultBranch).maybeEntry(name);
@@ -249,7 +248,7 @@ export class Repository extends NamedObject {
   }
 
   /**
-   * @return {Iterator<Branch>} of all branches
+   * @return {AsyncIterator<Branch>} of all branches
    */
   async *branches(patterns) {
     await this.initializeBranches();
@@ -293,7 +292,7 @@ export class Repository extends NamedObject {
   /**
    * Delete a {@link Branch}.
    * @param {string} name of the branch
-   * @return {Promise<undefined>}
+   * @return {Promise<any>}
    */
   async deleteBranch(name) {
     this._branches.delete(name);
@@ -305,7 +304,7 @@ export class Repository extends NamedObject {
 
   /**
    * @param {string|string[]} patterns
-   * @return {Iterator<Tag>} of all tags
+   * @return {AsyncIterator<Tag>} of all tags
    */
   async *tags(patterns) {
     await this.initializeTags();
@@ -318,7 +317,7 @@ export class Repository extends NamedObject {
   /**
    * Get a Tag.
    * @param {string} name
-   * @return {Tag}
+   * @return {Promise<Tag>}
    */
   async tag(name) {
     await this.initializeTags();
@@ -328,7 +327,7 @@ export class Repository extends NamedObject {
   /**
    * Delete the repository from the {@link Provider}.
    * {@link Provider#deleteRepository}
-   * @return {Promise<undefined>}
+   * @return {Promise<any>}
    */
   async delete() {
     return this.owner.deleteRepository(this.name);
@@ -339,7 +338,7 @@ export class Repository extends NamedObject {
    * @param {string} name of the pr
    * @param {Branch} source branch
    * @param {Object} options
-   * @return {PullRequest}
+   * @return {Promise<PullRequest>}
    */
   async createPullRequest(name, source, options) {
     await this.initializePullRequests();
@@ -368,7 +367,7 @@ export class Repository extends NamedObject {
 
   /**
    * Deliver all {@link PullRequest}s.
-   * @return {Iterator<PullRequest>} of all pull requests
+   * @return {AsyncIterator<PullRequest>} of all pull requests
    */
   async *pullRequests() {
     await this.initializePullRequests();
@@ -391,7 +390,7 @@ export class Repository extends NamedObject {
   /**
    * Delete a {@link PullRequest}.
    * @param {string} name
-   * @return {Promise}
+   * @return {Promise<any>}
    */
   async deletePullRequest(name) {
     this._pullRequests.delete(name);
@@ -419,7 +418,7 @@ export class Repository extends NamedObject {
 
   /**
    * List hooks.
-   * @return {Hook} all hooks of the repository
+   * @return {AsyncIterator<Hook>} all hooks of the repository
    */
   async *hooks() {
     await this.initializeHooks();
@@ -431,7 +430,7 @@ export class Repository extends NamedObject {
   /**
    * Get a Hook.
    * @param {string|number} id
-   * @return {Hook} for the given id
+   * @return {Promise<Hook>} for the given id
    */
   async hook(id) {
     for await (const hook of this.hooks()) {
@@ -469,7 +468,7 @@ export class Repository extends NamedObject {
   /**
    * Get sha of a ref.
    * @param {string} ref
-   * @return {string} sha of the ref
+   * @return {Promise<string>} sha of the ref
    */
   async refId(ref) {
     return undefined;

package/src/single-group-provider.mjs

@@ -1,6 +1,8 @@
 import { BaseProvider } from "./base-provider.mjs";
 import { RepositoryOwner } from "./repository-owner.mjs";
 import { stripBaseNames } from "./util.mjs";
+import { Repository } from "./repository.mjs";
+import { RepositoryGroup } from "./repository-group.mjs";
 
 /**
  * Provider holding a single set of repositories (no repository groups).
@@ -9,7 +11,7 @@ export class SingleGroupProvider extends RepositoryOwner(BaseProvider) {
   /**
    * Lookup a repository in the provider and all of its repository groups.
    * @param {string} name of the repository
-   * @return {Repository}
+   * @return {Promise<Repository>}
    */
   async repository(name) {
     const { base, repository } = this.parseName(name);
@@ -21,7 +23,7 @@ export class SingleGroupProvider extends RepositoryOwner(BaseProvider) {
   /**
    * Get a single group.
    * @param {string} name
-   * @return {RepositoryGroup} deliver the one and only present group
+   * @return {Promise<RepositoryGroup>} deliver the one and only present group
    */
   async repositoryGroup(name) {
     if (name !== undefined) {
@@ -36,7 +38,7 @@ export class SingleGroupProvider extends RepositoryOwner(BaseProvider) {
   /**
    * List groups.
    * @param {string[]|string} patterns
-   * @return {Iterator<RepositoryGroup>} always deliver the one and only present group
+   * @return {AsyncIterator<RepositoryGroup>} always deliver the one and only present group
    */
   async *repositoryGroups(patterns) {
     let found;

package/src/util.mjs

@@ -1,3 +1,5 @@
+import { Repository } from "./repository.mjs";
+
 /**
  * Convert scalar into an array.
  * The value undefined will be represented as an empty array.
@@ -13,7 +15,7 @@ export function asArray(value) {
  * A URL auth component will be removed to.
  * @param {string} name
  * @param {string[]} repositoryBases all possible bases
- * @param {Function} whenFound to be called with the found base name
+ * @param {Function} [whenFound] to be called with the found base name
  * @return {string} name without base
  */
 export function stripBaseName(name, repositoryBases, whenFound) {
@@ -36,10 +38,10 @@ export function stripBaseName(name, repositoryBases, whenFound) {
 /**
  * Loops over names and executes stripBaseName.
  *
- * @param {string[]} names
+ * @param {string|string[]} names
  * @param {*} repositoryBases
  * @param {string[]} repositoryBases all possible bases
- * @param {Function} whenFound to be called with the found base name
+ * @param {Function} [whenFound] to be called with the found base name
  * @return {string[]} names without base
  */
 export function stripBaseNames(names, repositoryBases, whenFound) {
@@ -56,6 +58,7 @@ export function stripBaseNames(names, repositoryBases, whenFound) {
  * 'something/*' will get to something/1 something/2 ...
  * @param {Repository} repository
  * @param {string} pattern
+ * @return {Promise<string>}
  */
 export async function generateBranchName(repository, pattern) {
   let n = 1;