@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. 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. |
Promise.<any>
ghFileImporter.fetchMetadata(owner, repo, path, ref) ⇒ 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. |
Promise.<string>
ghFileImporter.fetchFileContents(owner, repo, path, ref) ⇒ 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. |
Promise.<string>
ghFileImporter.fetchFileContentsFromUrl(url) ⇒ 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. |
Promise.<string>
ghFileImporter.importContents(url) ⇒ 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. |
Promise.<string>
ghFileImporter.importContentsFromUrl(url) ⇒ 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. |
© The OpenINF Authors