diff --git a/src/libs/content.ts b/src/libs/content.ts index 41a21d0..5494d85 100644 --- a/src/libs/content.ts +++ b/src/libs/content.ts @@ -3,6 +3,33 @@ import type { StatusCode } from "@std/http"; import { getRepository, githubToken } from "./env.ts"; +/** + * Get the content of the repository. + * @internal + * + * @param ref The name of the branch, tag or commit hash + * @returns The content of the repository and the status code + * + * @example Use the default branch + * ```ts + * const [content, status] = await getContent(); + * ``` + * @example Use a specific branch + * ```ts + * const branch = "main"; + * const [content, status] = await getContent(branch); + * ``` + * @example Use a specific tag + * ```ts + * const tag = "v1.0.0"; + * const [content, status] = await getContent(tag); + * ``` + * @example Use a specific commit + * ```ts + * const commit = "a1b2c3d4e5f6"; + * const [content, status] = await getContent(commit); + * ``` + */ export async function getContent( ref: string | undefined = undefined, ): Promise<[string, StatusCode]> { diff --git a/src/libs/env.ts b/src/libs/env.ts index 0443502..2016570 100644 --- a/src/libs/env.ts +++ b/src/libs/env.ts @@ -1,5 +1,15 @@ import type { Repository } from "./types.ts"; +/** + * Get the repository details from the environment variables. + * + * @returns {Repository} The repository type + * + * @example + * ```ts + * const repository = getRepository(); + * ``` + */ export function getRepository(): Repository { const repository: Repository = { owner: Deno.env.get("REPOSITORY_OWNER") ?? "", @@ -16,4 +26,12 @@ export function getRepository(): Repository { return repository; } +/** + * The GitHub token from the environment variables. + * + * @example + * ```ts + * const token = githubToken; + * ``` + */ export const githubToken: string | undefined = Deno.env.get("GITHUB_TOKEN"); diff --git a/src/libs/redirect.ts b/src/libs/redirect.ts index c4f6c6b..fb479d4 100644 --- a/src/libs/redirect.ts +++ b/src/libs/redirect.ts @@ -3,6 +3,38 @@ import type { UserAgent } from "@std/http/user-agent"; import { getRepository } from "./env.ts"; import { getGitHubUrl } from "./utils.ts"; +/** + * Check if accessed from a browser and return the GitHub URL. + * @internal + * + * @param userAgent The user agent accessed from + * @param ref="master" The branch, tag, or commit hash + * @returns The GitHub repository URL or null + * + * @example Use the default branch + * ```ts + * const userAgent = new UserAgent("Chrome/1.2.3"); + * const url: URL | null = checkRedirect(userAgent); + * ``` + * @example Use a specific branch + * ```ts + * const userAgent = new UserAgent("Chrome/1.2.3"); + * const branch = "main"; + * const url: URL | null = checkRedirect(userAgent, branch); + * ``` + * @example Use a specific tag + * ```ts + * const userAgent = new UserAgent("Chrome/1.2.3"); + * const tag = "v1.0.0"; + * const url: URL | null = checkRedirect(userAgent, tag); + * ``` + * @example Use a specific commit + * ```ts + * const userAgent = new UserAgent("Chrome/1.2.3"); + * const commit = "a1b2c3d4e5f6"; + * const url: URL | null = checkRedirect(userAgent, commit); + * ``` + */ export function checkRedirect( userAgent: UserAgent, ref: string = "master", diff --git a/src/libs/test_utils.ts b/src/libs/test_utils.ts index 2cfd09d..fe55859 100644 --- a/src/libs/test_utils.ts +++ b/src/libs/test_utils.ts @@ -2,24 +2,79 @@ import { UserAgent } from "@std/http/user-agent"; import type { Repository } from "./types.ts"; +/** + * Sample repository for test. + * + * @example + * ```ts + * const repository = testRepo; + * ``` + */ export const testRepo: Repository = { owner: "denoland", name: "deno", path: "README.md", }; + +/** + * Sample unknown repository for test. + * + * @example + * ```ts + * const repository = unknownRepo; + * ``` + */ export const unknownRepo: Repository = { owner: "unknown-owner", name: "unknown-repo", path: "unknown-path", }; + +/** + * Sample version reference for test. + * + * @example + * ```ts + * const ref = testRef; + * ``` + */ export const testRef = "v1.0.0"; + +/** + * Sample user agent for test. + * + * @example + * ```ts + * const userAgent = testUserAgent; + * ``` + */ export const testUserAgent = new UserAgent("Chrome/1.2.3"); +/** + * Export the repository details to the environment variables. + * + * @param repository The repository type + * + * @example + * ```ts + * const repository = new Repository("5ouma", "reproxy", "src/server.ts"); + * exportRepo(repository); + * ``` + */ export function exportRepo(repository: Repository) { Deno.env.set("REPOSITORY_OWNER", repository.owner); Deno.env.set("REPOSITORY_NAME", repository.name); Deno.env.set("REPOSITORY_PATH", repository.path); } + +/** + * Clear the repository details from the environment variables. + * + * @example + * ```ts + * clearRepo(); + * ``` + */ export function clearRepo() { Deno.env.delete("REPOSITORY_OWNER"); Deno.env.delete("REPOSITORY_NAME"); diff --git a/src/libs/types.ts b/src/libs/types.ts index d2dfbcf..3575123 100644 --- a/src/libs/types.ts +++ b/src/libs/types.ts @@ -1,3 +1,19 @@ +/** + * Repository type. + * + * @property owner The repository owner + * @property name The repository name + * @property path The content path from the root of the repository + * + * @example + * ```ts + * const repository: Repository = { + * owner: "5ouma", + * name: "reproxy", + * path: "src/server.ts", + * }; + * ``` + */ export type Repository = { owner: string; name: string; diff --git a/src/libs/utils.ts b/src/libs/utils.ts index 50137e5..a619489 100644 --- a/src/libs/utils.ts +++ b/src/libs/utils.ts @@ -2,6 +2,23 @@ import { join } from "@std/path"; import type { Repository } from "./types.ts"; +/** + * Get the GitHub URL of the repository. + * + * @param repository The repository type + * @param ref="master" The reference to use + * @returns The GitHub repository URL + * + * @example + * ```ts + * const repository: Repository = { + * owner: "5ouma", + * name: "reproxy", + * path: "src/server.ts", + * }; + * const url: URL = getGitHubUrl(repository); + * ``` + */ export function getGitHubUrl( repository: Repository, ref: string = "master", diff --git a/src/server.ts b/src/server.ts index f780497..4efc307 100644 --- a/src/server.ts +++ b/src/server.ts @@ -4,6 +4,20 @@ import { UserAgent } from "@std/http/user-agent"; import { checkRedirect, getContent } from "./libs/mod.ts"; +/** + * The Hono application for this project. + * + * @example Access without a user agent + * ```ts + * const res: Response = await app.request("/"); + * ``` + * @example Access with a user agent + * ```ts + * const res: Response = await app.request("/", { + * headers: { "User-Agent": new UserAgent("Chrome/1.2.3").toString() }, + * }); + * ``` + */ export const app = new Hono(); app .get("/:ref?", async (ctx: Context) => {