@openinf/gh-file-importer

Utility that imports arbitrary files from remote GitHub repositories

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. We are constantly working to improve this repository, so please feel free to contribute if you notice any omissions or errors.

Thanks!

Supported Node.js Environments

• v4：Argon (Ar)
• v6：Boron (B)
• v8：Carbon (C)
• v10：Dubnium (Db)
• v12：Erbium (Er)
• v14：Fermium (Fm)
• v16：Gallium (Ga)
• v18：Hydrogen (H)

---

Table of Contents

• Installation
• Usage
• API
• Contributing
• License

---

Installation

@openinf/gh-file-importer runs on supported versions of Node.js and is available via npm, pnpm, or yarn.

Using the npm CLI

^{See the official documentation for this command for more information.}

npm i @openinf/gh-file-importer

Using the pnpm CLI

^{See the official documentation for this command for more information.}

pnpm add @openinf/gh-file-importer

Using the Yarn 1 CLI (Classic)

^{See the official documentation for this command for more information.}

yarn add @openinf/gh-file-importer

Usage

Import the GhFileImporter constructor based on your platform.

Node.js

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

Options

Now instantiate 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" }),
});

API

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.

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.

License

This project is licensed under either of

• Apache License, Version 2.0
• MIT license

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.

---

Show Your Support

If you like the project (or want to bookmark it) —
— give it a star ⭐️ — it will greatly encourage us.