Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/openinf/openinf-gh-file-importer

Utility that imports arbitrary files from remote GitHub repositories
https://github.com/openinf/openinf-gh-file-importer

commonjs commonjs-module commonjs-package download file github nodejs nodejs-module nodejs-modules npm npm-package repository typescript typescript-package utility

Last synced: about 1 month ago
JSON representation

Utility that imports arbitrary files from remote GitHub repositories

Awesome Lists containing this project

README 

        


  OpenINF logo







## `@openinf/gh-file-importer`



> Utility that imports arbitrary files from remote GitHub repositories







[!['View on npm'][npm-badge--shields]][npm-badge-url]

[!['License: MIT/Apache-2.0'][license-badge--shields]][license-badge-url]










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](#contributing) if

you notice any omissions or errors.



Thanks!







	

		

			Platform: Node.js LTS

		

	

	





		

			Supported Node.js Environments

		




- [ ] v4：Argon (Ar)

- [ ] v6：Boron (B)

- [ ] v8：Carbon (C)

- [ ] v10：Dubnium (Db)

- [ ] v12：Erbium (Er)

- [x] v14：Fermium (Fm)

- [x] v16：Gallium (Ga)

- [x] v18：Hydrogen (H)













[![Code Style: Prettier][prettier-badge]][prettier-url]

[![Commit Style: Conventional Commits][conventional-commits-badge]][conventional-commits-url]

[![Chat on Matrix][matrix-badge--shields]][matrix-url]











---







### Table of Contents



- [Installation](#installation)

- [Usage](#usage)

- [API](#api)

- [Contributing](#contributing)

- [License](#license)








---







	

	
Installation Corepack logo








`@openinf/gh-file-importer` runs on

[supported versions of Node.js](#platform--node-js-lts) and is available via

**`npm`**, **`pnpm`**, or **`yarn`**.



**Using the npm CLI**



See the

[official documentation for this command](https://docs.npmjs.com/cli/commands/npm-install)

for more information.



```shell

npm i @openinf/gh-file-importer

```



**Using the pnpm CLI**



See the [official documentation for this command](https://pnpm.io/cli/add)

for more information.



```shell

pnpm add @openinf/gh-file-importer

```



**Using the Yarn 1 CLI (Classic)**



See the

[official documentation for this command](https://classic.yarnpkg.com/en/docs/cli/add)

for more information.



```shell

yarn add @openinf/gh-file-importer

```







### Usage



Import the `GhFileImporter` constructor based on your platform.



#### Node.js



```ts

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.



```ts

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](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token).



#### Logging



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



```ts

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`.



```ts

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`](https://github.com/watson/console-log-level) module.



```ts

const ghFileImporter = new GhFileImporter({

  destDir: DIR_TEMP,

  log: require("console-log-level")({ level: "info" }),

});

```








### API






#### GhFileImporter

**Kind**: global class  



* [GhFileImporter](#GhFileImporter)

    * [new GhFileImporter(options)](#new_GhFileImporter_new)

    * [.fetchMetadata(owner, repo, path, ref)](#GhFileImporter+fetchMetadata) ⇒ Promise<any>

    * [.fetchFileContents(owner, repo, path, ref)](#GhFileImporter+fetchFileContents) ⇒ Promise<string>

    * [.fetchFileContentsFromUrl(url)](#GhFileImporter+fetchFileContentsFromUrl) ⇒ Promise<string>

    * [.importContents(url)](#GhFileImporter+importContents) ⇒ Promise<string>

    * [.importContentsFromUrl(url)](#GhFileImporter+importContentsFromUrl) ⇒ 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](#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](#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](#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](#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](#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](https://www.apache.org/licenses/LICENSE-2.0)

- [MIT license](https://opensource.org/licenses/MIT)



at your option.



The [SPDX](https://spdx.dev) 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.










  The OpenINF logo







[conventional-commits-badge]: https://img.shields.io/badge/commit%20style-Conventional-%23fa6673?logoColor=white&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAzMCAzMCI+PHBhdGggc3R5bGU9ImZpbGw6ICNGRkYiIGQ9Ik0xNSwyQTEzLDEzLDAsMSwxLDIsMTUsMTMsMTMsMCwwLDEsMTUsMm0wLTJBMTUsMTUsMCwxLDAsMzAsMTUsMTUsMTUsMCwwLDAsMTUsMFoiLz48L3N2Zz4K 'Commit Style: Conventional Commits'

[conventional-commits-url]: https://www.conventionalcommits.org 'Commit Style: Conventional Commits'

[give it a star ⭐️]: https://github.com/OpenINF/openinf-gh-file-importer/stargazers

[license-badge--shields]: https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg?logo=github 'License: MIT/Apache 2.0'

[license-badge-url]: #license 'License: MIT/Apache 2.0'

[matrix-badge--shields]: https://img.shields.io/badge/matrix-join%20chat-%2346BC99?logo=matrix 'Chat on Matrix'

[matrix-url]: https://matrix.to/#/#openinf-space:matrix.org 'You're invited to talk on Matrix'

[npm-badge--shields]: https://img.shields.io/npm/v/@openinf/gh-file-importer/latest.svg?logo=npm&color=fe7d37 'View on npm'

[npm-badge-url]: https://www.npmjs.com/package/@openinf/gh-file-importer#top 'View on npm'

[open an issue]: https://github.com/OpenINF/openinf-gh-file-importer/issues

[prettier-badge]: https://img.shields.io/badge/code_style-Prettier-ff69b4.svg?logo=prettier 'Code Style: Prettier'

[prettier-url]: https://prettier.io/playground 'Code Style: Prettier'

[project-status-badge]: https://img.shields.io/badge/project%20status-under%20construction-orange 'Project Status: Under construction badge'