docs: add missing jsdocs

src/index.ts

@@ -7,21 +7,48 @@ import type { PackageJson, TSConfig } from "./types";
 export * from "./types";
 export * from "./utils";
 
+/**
+ * Represents the options for resolving paths with additional file finding capabilities.
+ */
 export type ResolveOptions = _ResolveOptions & FindFileOptions;
+
+/**
+ * Options for reading files with optional caching.
+ */
 export type ReadOptions = {
+  /**
+   * Specifies whether the read results should be cached.
+   * Can be a boolean or a map to hold the cached data.
+   */
   cache?: boolean | Map<string, Record<string, any>>;
 };
 
+/**
+ * Defines a PackageJson structure.
+ * @param package_ - The `package.json` content as an object. See {@link PackageJson}.
+ * @returns the same `package.json` object.
+ */
 export function definePackageJSON(package_: PackageJson): PackageJson {
   return package_;
 }
 
+/**
+ * Defines a TSConfig structure.
+ * @param tsconfig - The contents of `tsconfig.json` as an object. See {@link TSConfig}.
+ * @returns the same `tsconfig.json` object.
+ */
 export function defineTSConfig(tsconfig: TSConfig): TSConfig {
   return tsconfig;
 }
 
 const FileCache = new Map<string, Record<string, any>>();
 
+/**
+ * Asynchronously reads a `package.json` file.
+ * @param id - The path identifier for the package.json, defaults to the current working directory.
+ * @param options - The options for resolving and reading the file. See {@link ResolveOptions}.
+ * @returns a promise resolving to the parsed `package.json` object.
+ */
 export async function readPackageJSON(
   id?: string,
   options: ResolveOptions & ReadOptions = {},
@@ -40,13 +67,24 @@ export async function readPackageJSON(
   return parsed;
 }
 
+/**
+ * Asynchronously writes data to a `package.json` file.
+ * @param path - The path to the file where the `package.json` is written.
+ * @param package_ - The `package.json` object to write. See {@link PackageJson}.
+ */
 export async function writePackageJSON(
   path: string,
   package_: PackageJson,
 ): Promise<void> {
   await fsp.writeFile(path, JSON.stringify(package_, undefined, 2));
 }
 
+/**
+ * Asynchronously reads a `tsconfig.json` file.
+ * @param id - The path to the `tsconfig.json` file, defaults to the current working directory.
+ * @param options - The options for resolving and reading the file. See {@link ResolveOptions}.
+ * @returns a promise resolving to the parsed `tsconfig.json` object.
+ */
 export async function readTSConfig(
   id?: string,
   options: ResolveOptions & ReadOptions = {},
@@ -66,13 +104,24 @@ export async function readTSConfig(
   return parsed;
 }
 
+/**
+ * Asynchronously writes data to a `tsconfig.json` file.
+ * @param path - The path to the file where the `tsconfig.json` is written.
+ * @param tsconfig - The `tsconfig.json` object to write. See {@link TSConfig}.
+ */
 export async function writeTSConfig(
   path: string,
   tsconfig: TSConfig,
 ): Promise<void> {
   await fsp.writeFile(path, JSON.stringify(tsconfig, undefined, 2));
 }
 
+/**
+ * Resolves the path to the nearest `package.json` file from a given directory.
+ * @param id - The base path for the search, defaults to the current working directory.
+ * @param options - Options to modify the search behaviour. See {@link ResolveOptions}.
+ * @returns A promise resolving to the path of the nearest `package.json` file.
+ */
 export async function resolvePackageJSON(
   id: string = process.cwd(),
   options: ResolveOptions = {},
@@ -84,6 +133,12 @@ export async function resolvePackageJSON(
   });
 }
 
+/**
+ * Resolves the path to the nearest `tsconfig.json` file from a given directory.
+ * @param id - The base path for the search, defaults to the current working directory.
+ * @param options - Options to modify the search behaviour. See {@link ResolveOptions}.
+ * @returns A promise resolving to the path of the nearest `tsconfig.json` file.
+ */
 export async function resolveTSConfig(
   id: string = process.cwd(),
   options: ResolveOptions = {},
@@ -103,6 +158,12 @@ const lockFiles = [
   "bun.lockb",
 ];
 
+/**
+ * Resolves the path to the nearest `tsconfig.json` file from a given directory.
+ * @param id - The base path for the search, defaults to the current working directory.
+ * @param options - Options to modify the search behaviour. See {@link ResolveOptions}.
+ * @returns A promise resolving to the path of the nearest `tsconfig.json` file.
+ */
 export async function resolveLockfile(
   id: string = process.cwd(),
   options: ResolveOptions = {},
@@ -119,6 +180,13 @@ export async function resolveLockfile(
   throw new Error("No lockfile found from " + id);
 }
 
+/**
+ * Detects the workspace directory based on common project markers (`.git`, lockfiles, `package.json`).
+ * Throws an error if the workspace root cannot be detected.
+ * @param id - The base path to search, defaults to the current working directory.
+ * @param options - Options to modify the search behaviour. See {@link ResolveOptions}.
+ * @returns a promise resolving to the path of the detected workspace directory.
+ */
 export async function findWorkspaceDir(
   id: string = process.cwd(),
   options: ResolveOptions = {},

src/types/packagejson.ts

@@ -118,9 +118,12 @@ export interface PackageJson {
    */
   peerDependencies?: Record<string, string>;
   /**
-   * TypeScript typings, typically ending by .d.ts
+   * TypeScript typings, typically ending by `.d.ts`.
    */
   types?: string;
+  /**
+   * This field is synonymous with `types`.
+   */
   typings?: string;
   /**
    * Non-Standard Node.js alternate entry-point to main.
@@ -154,6 +157,9 @@ export interface PackageJson {
         "import" | "require" | "." | "node" | "browser" | string,
         string | Record<"import" | "require" | string, string>
       >;
+  /**
+   * The optional engines field is used to specify the versions of npm and node that your stuff works on.
+   */
   workspaces?: string[];
   [key: string]: any;
 }

src/utils.ts

@@ -45,6 +45,13 @@ const defaultFindOptions: Required<FindFileOptions> = {
   },
 };
 
+/**
+ * Asynchronously finds a file by name, starting from the specified directory and traversing up (or down if reverse).
+ * @param filename - The name of the file to find.
+ * @param _options - Options to customise the search behaviour.
+ * @returns a promise that resolves to the path of the file found.
+ * @throws Will throw an error if the file cannot be found.
+ */
 export async function findFile(
   filename: string,
   _options: FindFileOptions = {},
@@ -86,13 +93,27 @@ export async function findFile(
   );
 }
 
+/**
+ * Asynchronously finds the next file with the given name, starting in the given directory and moving up.
+ * Alias for findFile without reversing the search.
+ * @param filename - The name of the file to find.
+ * @param _options - Options to customise the search behaviour.
+ * @returns A promise that resolves to the path of the next file found.
+ */
 export function findNearestFile(
   filename: string,
   _options: FindFileOptions = {},
 ): Promise<string> {
   return findFile(filename, _options);
 }
 
+/**
+ * Asynchronously finds the furthest file with the given name, starting from the root directory and moving downwards.
+ * This is essentially the reverse of `findNearestFile'.
+ * @param filename - The name of the file to find.
+ * @param _options - Options to customise the search behaviour, with reverse set to true.
+ * @returns A promise that resolves to the path of the farthest file found.
+ */
 export function findFarthestFile(
   filename: string,
   _options: FindFileOptions = {},