diff --git a/download.ts b/download.ts index 4bb1338..642e733 100644 --- a/download.ts +++ b/download.ts @@ -1,3 +1,9 @@ +/** + * This module contains the common types used in plug. + * + * @module + */ + import { dirname, ensureDir, @@ -23,11 +29,25 @@ import { urlToFilename, } from "./util.ts"; -export const ALL_ARCHS = ["x86_64", "aarch64"]; +/** + * A list of all possible system architectures. + * + * This should match the {@link Deno.build.arch} type. + */ +export const ALL_ARCHS: (typeof Deno.build.arch)[] = [ + "x86_64", + "aarch64", +]; -export const ALL_OSS = [ +/** + * A list of all possible system operating systems. + * + * This should match the {@link Deno.build.os} type. + */ +export const ALL_OSS: (typeof Deno.build.os)[] = [ "darwin", "linux", + "android", "windows", "freebsd", "netbsd", @@ -36,6 +56,10 @@ export const ALL_OSS = [ "illumos", ]; +/** + * The default file extensions for dynamic libraries in the different operating + * systems. + */ export const defaultExtensions: OsRecord = { darwin: "dylib", linux: "so", @@ -48,6 +72,10 @@ export const defaultExtensions: OsRecord = { android: "so", }; +/** + * The default file prefixes for dynamic libraries in the different operating + * systems. + */ export const defaultPrefixes: OsRecord = { darwin: "lib", linux: "lib", diff --git a/types.ts b/types.ts index 95c517d..c64945f 100644 --- a/types.ts +++ b/types.ts @@ -1,3 +1,9 @@ +/** + * This module contains the common types used in plug. + * + * @module + */ + /** * A record keyed by possible operating system identifiers */ diff --git a/util.ts b/util.ts index 32b5e58..4f7123c 100644 --- a/util.ts +++ b/util.ts @@ -1,3 +1,9 @@ +/** + * This file contains useful utility functions used by plug. + * + * @module + */ + import { hex, isAbsolute, @@ -35,6 +41,11 @@ function baseUrlToFilename(url: URL): string { return join(...out); } +/** + * Transforms a string into a URL. + * + * @private + */ export function stringToURL(url: string): URL { // deno-fmt-ignore return url.startsWith("file://") @@ -44,6 +55,11 @@ export function stringToURL(url: string): URL { : toFileUrl(resolve(url)); } +/** + * SHA-256 hashes a string. Used internally to hash URLs for cache filenames. + * + * @private + */ export async function hash(value: string): Promise { return hex( new Uint8Array( @@ -52,12 +68,22 @@ export async function hash(value: string): Promise { ); } +/** + * Transforms a URL into a filename for the cache. + * + * @private + */ export async function urlToFilename(url: URL): Promise { const cacheFilename = baseUrlToFilename(url); const hashedFilename = await hash(url.pathname + url.search); return join(cacheFilename, hashedFilename); } +/** + * Checks if a file exists. + * + * @private + */ export async function isFile(filePath: string): Promise { try { const stats = await Deno.lstat(filePath); @@ -73,6 +99,9 @@ export async function isFile(filePath: string): Promise { // The rest of is based on code from denoland/deno_cache by the Deno authors // Copyright 2018-2022 the Deno authors. All rights reserved. MIT license. +/** + * @returns The home directory of the user. + */ export function homeDir(): string | undefined { switch (Deno.build.os) { case "windows": @@ -90,6 +119,9 @@ export function homeDir(): string | undefined { } } +/** + * @returns The cache directory of the user. + */ export function cacheDir(): string | undefined { if (Deno.build.os === "darwin") { const home = homeDir(); @@ -111,6 +143,9 @@ export function cacheDir(): string | undefined { } } +/** + * @returns The cache directory for Deno. + */ export function denoCacheDir(): string | undefined { const dd = Deno.env.get("DENO_DIR"); let root;