The high-level goal of @openinf/gh-file-importer is to serve as a Node.js package containing a utility for importing arbitrary files from remote GitHub repos allowing users to make use of them locally. As is the case with any software project in continuous development, omissions and errors may exist, for which contributions are welcome.

Installation

@openinf/gh-file-importer runs on Node.js and is available via npm.

npm install @openinf/gh-file-importer

Usage

Import the GhFileImporter constructor based on your platform.

Node.js

Install with npm install @openinf/gh-file-importer

import { GhFileImporter } from '@openinf/gh-file-importer';

Options

Now instantiate your your API. All options are optional except for destDir, which is the location where your files will be stored.

import { GhFileImporter } from '@openinf/gh-file-importer';

const DIR_TEMP = './tmp';

const ghFileImporter = new GhFileImporter({ destDir: DIR_TEMP });

await ghFileImporter.importContents('tc39', 'proposals', 'README.md');

Note: if needing to circumvent exceeding the GitHub API rate limit, be sure to have an environment variable called GITHUB_TOKEN containing a GitHub person access token.

Logging

For custom logging, pass an object with debug, info, warn, and error methods as the log option.

const ghFileImporter = new GhFileImporter({
  destDir: DIR_TEMP,
  log: {
    debug: () => {},
    info: () => {},
    warn: console.warn,
    error: console.error
  }
};

Debug

The simplest way to receive debug information is to set the log client option to console.

const ghFileImporter = new GhFileImporter({
  destDir: DIR_TEMP,
  log: console,
});

If you like to support a configurable log level, we recommend using the console-log-level module.

const ghFileImporter = new GhFileImporter({
  destDir: DIR_TEMP,
  log: require("console-log-level")({ level: "info" }),
});

GhFileImporter

Kind: global class

• GhFileImporter
  • new GhFileImporter(options)
  • .fetchMetadata(owner, repo, path, ref) ⇒ Promise.<any>
  • .fetchFileContents(owner, repo, path, ref) ⇒ Promise.<string>
  • .fetchFileContentsFromUrl(url) ⇒ Promise.<string>
  • .importContents(url) ⇒ Promise.<string>
  • .importContentsFromUrl(url) ⇒ Promise.<string>

new GhFileImporter(options)

Creates an instance of GhFileImporter.

Throws:

• InvalidArgTypeError
• InvalidArgValueError
• InvalidPropertyValueError
• MissingArgsError
• MissingOptionError

| Param | Type | Description | | --- | --- | --- | | options | GhFileImporterOptions | undefined | The options object. |

ghFileImporter.fetchMetadata(owner, repo, path, ref) ⇒ Promise.<any>

Retrieves a repo or path's metadata.

Kind: instance method of GhFileImporter
Returns: Promise.<any> - An object containing the metadata repo or path's metadata.
Throws:

• InvalidArgTypeError
• InvalidArgValueError
• InvalidArgsNumberError

See: https://docs.github.com/en/rest/reference/repos#get-repository-content

| Param | Type | Description | | --- | --- | --- | | owner | string | The username associated with the repository. | | repo | string | The repository name. | | path | string | undefined | The path to the file or folder. | | ref | string | undefined | The name of the commit/branch/tag. |

ghFileImporter.fetchFileContents(owner, repo, path, ref) ⇒ Promise.<string>

Retrieves a path's contents.

Kind: instance method of GhFileImporter
Returns: Promise.<string> - The file contents.
Throws:

• InvalidArgTypeError
• InvalidArgValueError
• InvalidArgsNumberError

| Param | Type | Description | | --- | --- | --- | | owner | string | The username associated with the repository. | | repo | string | The repository name. | | path | string | The path to the file or folder. | | ref | string | undefined | The name of the commit/branch/tag. |

ghFileImporter.fetchFileContentsFromUrl(url) ⇒ Promise.<string>

Retrieves the file contents from the URL provided.

Kind: instance method of GhFileImporter
Returns: Promise.<string> - The file contents.
Throws:

• InvalidArgTypeError
• InvalidArgValueError

| Param | Type | Description | | --- | --- | --- | | url | string | The string representation of a remote file URL. |

ghFileImporter.importContents(url) ⇒ Promise.<string>

Imports a file into the directory provided for the destDir option.

Kind: instance method of GhFileImporter
Returns: Promise.<string> - The file contents.
Throws:

• InvalidArgTypeError
• InvalidArgValueError

| Param | Type | Description | | --- | --- | --- | | url | string | The string representation of a remote file URL. |

ghFileImporter.importContentsFromUrl(url) ⇒ Promise.<string>

Imports a file located at the supplied URL into the directory provided for the destDir option.

Kind: instance method of GhFileImporter
Returns: Promise.<string> - The file contents.
Throws:

• InvalidArgTypeError
• InvalidArgValueError

| Param | Type | Description | | --- | --- | --- | | url | string | The string representation of a remote file URL. |