diff --git a/README.md b/README.md index 2c6938c..4b5418a 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,18 @@ $ yarn add @nodesecure/gitlab import * as gitlab from "@nodesecure/gitlab"; // Note: repository can be either namespace path or repository ID -const is = await gitlab.download("NodeSecure.utils"); -console.log(is.location); +const result = await gitlab.download( + "NodeSecure.utils" +); +console.log(result); ``` ## API +Both `download` and `downloadAndExtract` functions use the same set of options. + ```ts -export interface DownloadOptions { +interface DownloadOptions { /** * The destination (location) to extract the tar.gz * @@ -61,8 +65,13 @@ export interface DownloadOptions { */ gitlab?: string; } +``` -export interface DownloadResult { +### download(repository: string, options?: DownloadOptions): Promise< DownloadResult > +Download the tar.gz archive of the GIT repository. + +```ts +interface DownloadResult { /** Archive or repository location on disk */ location: string; /** Gitlab repository name */ @@ -72,13 +81,13 @@ export interface DownloadResult { /** Gitlab branch name */ branch: string; } +``` -export function download( - repo: string, - options?: DownloadOptions -): Promise; +### downloadAndExtract(repository: string, options?: DownloadExtractOptions): Promise< DownloadResult > +Use download but extract the tar.gz archive. -export interface DownloadExtractOptions extends DownloadOptions { +```ts +interface DownloadExtractOptions extends DownloadOptions { /** * Remove the tar.gz archive after a succesfull extraction * @@ -86,21 +95,6 @@ export interface DownloadExtractOptions extends DownloadOptions { */ removeArchive?: boolean; } - -export function downloadAndExtract( - repo: string, - options?: DownloadExtractOptions -): Promise; -``` - -### Custom gitlab URL - -To work with a custom gitlab instance you can either setup a `GITLAB_URL` system variable or use `setUrl` method: - -```js -import * as gitlab from "@nodesecure/gitlab"; - -gitlab.setUrl("..."); ``` ## Contributors ✨ diff --git a/test/functions/download.spec.ts b/test/functions/download.spec.ts new file mode 100644 index 0000000..fac9944 --- /dev/null +++ b/test/functions/download.spec.ts @@ -0,0 +1,49 @@ +// Import Node.js Dependencies +import path from "node:path"; +import fs from "node:fs"; +import assert from "node:assert"; +import { describe, test } from "node:test"; + +// Import Third-party Dependencies +import is from "@slimio/is"; + +// Import Internal Dependency +import * as gitlab from "../../src/index.js"; + +describe("download", () => { + test("should be an asyncFunction", () => { + assert.ok(is.func(gitlab.download)); + assert.ok(is.asyncFunction(gitlab.download)); + }); + + test("must throw: repository must be a string!", async() => { + await assert.rejects( + async() => await gitlab.download(10 as any), + { + name: "TypeError", + message: "repository must be a string!" + } + ); + }); + + test("extract tar.gz at in the current working dir", async() => { + try { + const { location, ...resultRest } = await gitlab.download("polychromatic.plombier-chauffagiste"); + + fs.accessSync(location); + + assert.strictEqual(path.extname(location), ".gz"); + assert.deepEqual(resultRest, { + branch: "master", + organization: "polychromatic", + repository: "plombier-chauffagiste" + }); + } + finally { + const tarGzLocation = path.join(process.cwd(), "plombier-chauffagiste-master.tar.gz"); + if (fs.existsSync(tarGzLocation)) { + fs.unlinkSync(tarGzLocation); + } + } + }); +}); diff --git a/test/functions/downloadAndExtract.spec.ts b/test/functions/downloadAndExtract.spec.ts new file mode 100644 index 0000000..e720889 --- /dev/null +++ b/test/functions/downloadAndExtract.spec.ts @@ -0,0 +1,60 @@ +// Import Node.js Dependencies +import os from "node:os"; +import path from "node:path"; +import fs from "node:fs"; +import assert from "node:assert"; +import { describe, test, it, beforeEach, afterEach } from "node:test"; + +// Import Third-party Dependencies +import is from "@slimio/is"; + +// Import Internal Dependency +import * as gitlab from "../../src/index.js"; + +describe("downloadAndExtract", () => { + let tempDownloadDir: string; + + beforeEach(() => { + tempDownloadDir = fs.mkdtempSync( + path.join(os.tmpdir(), "nsecure-gitlab-") + ); + }); + + afterEach(() => { + fs.rmSync(tempDownloadDir, { recursive: true, force: true }); + }); + + test("gitlab.downloadAndExtract should be an asyncFunction", () => { + assert.ok(is.func(gitlab.downloadAndExtract)); + assert.ok(is.asyncFunction(gitlab.downloadAndExtract)); + }); + + it("should download and extract the given gitlab repository (and not delete the tar.gz archive)", async() => { + const { location } = await gitlab.downloadAndExtract("polychromatic.plombier-chauffagiste", { + dest: tempDownloadDir, + removeArchive: false + }); + + assert.ok( + fs.existsSync(path.join(tempDownloadDir, "plombier-chauffagiste-master.tar.gz")) + ); + assert.doesNotThrow( + () => fs.accessSync(location) + ); + }); + + it("should download and extract the given gitlab repository (and delete the tar.gz archive)", async() => { + const { location } = await gitlab.downloadAndExtract("polychromatic.plombier-chauffagiste", { + dest: tempDownloadDir, + removeArchive: true + }); + + assert.strictEqual( + fs.existsSync(path.join(tempDownloadDir, "plombier-chauffagiste-master.tar.gz")), + false + ); + assert.doesNotThrow( + () => fs.accessSync(location) + ); + }); +}); diff --git a/test/test.spec.ts b/test/test.spec.ts deleted file mode 100644 index bad6287..0000000 --- a/test/test.spec.ts +++ /dev/null @@ -1,72 +0,0 @@ -// Import Node.js Dependencies -import { fileURLToPath } from "node:url"; -import path from "node:path"; -import fs from "node:fs/promises"; -import { describe, test } from "node:test"; -import assert from "node:assert"; -import * as timers from "node:timers/promises"; - -// Import Third-party Dependencies -import is from "@slimio/is"; - -// Import Internal Dependency -import * as gitlab from "../src/index.js"; - -// CONSTANTS -const __dirname = path.dirname(fileURLToPath(import.meta.url)); -const kDownloadDir = path.join(__dirname, "downloads"); - -await fs.mkdir(kDownloadDir); - -describe("download", () => { - test("should be an asyncFunction", () => { - assert.equal(is.func(gitlab.download), true); - assert.equal(is.asyncFunction(gitlab.download), true); - }); - - test("must throw: repository must be a string!", async() => { - await assert.rejects( - async() => await gitlab.download(10 as any), - { - name: "TypeError", - message: "repository must be a string!" - } - ); - }); - - test("extract tar.gz at in the current working dir", async() => { - const { location } = await gitlab.download("polychromatic.plombier-chauffagiste"); - - await fs.access(location); - assert.strictEqual(path.extname(location), ".gz"); - }); -}); - -describe("downloadAndExtract", () => { - test("gitlab.downloadAndExtract should be an asyncFunction", () => { - assert.equal(is.func(gitlab.downloadAndExtract), true); - assert.equal(is.asyncFunction(gitlab.downloadAndExtract), true); - }); - - test("download and extract a public gitlab repository", async() => { - const { location } = await gitlab.downloadAndExtract("polychromatic.plombier-chauffagiste", { - dest: kDownloadDir - }); - - await assert.doesNotReject( - async() => await fs.access(location) - ); - }); -}); - -test("teardown", async() => { - await timers.setImmediate(); - - await assert.doesNotReject( - async() => await fs.rm(kDownloadDir, { recursive: true, force: true }) - ); - - await assert.doesNotReject( - async() => await fs.unlink(path.join(process.cwd(), "plombier-chauffagiste-master.tar.gz")) - ); -}); diff --git a/test/utils.spec.ts b/test/utils.spec.ts index b5bc83e..a7c740e 100644 --- a/test/utils.spec.ts +++ b/test/utils.spec.ts @@ -1,14 +1,16 @@ // Import Node.js Dependencies -import { test } from "node:test"; +import { describe, test } from "node:test"; import assert from "node:assert"; // Import Internal Dependency import { getRepositoryPath } from "../src/utils.js"; -test("getRepositoryPath must return id", () => { - assert.equal(getRepositoryPath("10"), "10"); -}); +describe("getRepositoryPath", () => { + test("must return id", () => { + assert.strictEqual(getRepositoryPath("10"), "10"); + }); -test("getRepositoryPath must return gitlab path", () => { - assert.equal(getRepositoryPath("nodesecure.boo"), "nodesecure%2Fboo"); + test("must return GitLab path (encoded for URL)", () => { + assert.strictEqual(getRepositoryPath("nodesecure.boo"), "nodesecure%2Fboo"); + }); });