Work with several forges

createForges() takes a list of factories, or of providers you already created. It builds the providers and returns an object that routes calls:

import { createForges, github, gitlab } from 'forges'

const forges = createForges([
  github({ auth: { type: 'token', token: process.env.GITHUB_TOKEN! } }),
  gitlab({ auth: { type: 'token', token: process.env.GITLAB_TOKEN! } }),
])

Route by ref

Every ref carries forge and instance. Calls such as forges.threads.get(ref) and forges.repos.get(ref) go to the provider that matches. A ref for an unregistered forge throws UnknownForgeError.

To get the provider itself, use forges.for(ref), forges.get('github'), or forges.all('gitlab'):

const provider = forges.for(thread.ref)
if (provider?.can('threads.close', thread.ref.kind)) {
  await provider.threads.close(thread.ref)
}

Read a pasted URL

forges.parseUrl() turns a web URL on any registered instance into refs. It returns undefined for a URL that no provider serves:

const parsed = forges.parseUrl('https://github.com/nuxt/nuxt/issues/1')

if (parsed?.thread) {
  const thread = await parsed.provider.threads.get(parsed.thread)
}

The reverse is provider.urlFor(), which builds a web URL from a ref without a request.

Fan out reads

Some calls run on every provider that supports them:

• forges.notifications.list() lists notifications provider by provider.
• forges.search.threads() and forges.search.repos() read one page from each provider that supports search, and merge the results, newest first. A provider that fails adds a warning and no items.
• forges.threads.getMany() groups refs by provider and keeps the input order.

Run two instances of one forge

A provider takes its instance from the host of baseUrl, so github.com and a GitHub Enterprise Server can be registered together:

const forges = createForges([
  github({ auth: personal }),
  github({ baseUrl: 'https://ghe.example.com/api/v3', auth: work }),
])

createForges() throws when two providers share a forge and an instance. To register two providers for the same host, pass a different instance to one of them.