docs: add tsdocs

src/AkteApp.ts

@@ -12,18 +12,51 @@ import { createDebugger } from "./lib/createDebugger";
 import { pathToRouterPath } from "./lib/pathToRouterPath";
 import { isCLI } from "./lib/isCLI";
 
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import type { defineAkteFile } from "./defineAkteFile";
+import type { defineAkteFiles } from "./defineAkteFiles";
+
+/* eslint-enable @typescript-eslint/no-unused-vars */
+
+/** Akte app configuration object. */
 export type Config<TGlobalData> = {
+	/**
+	 * Akte files this config is responsible for.
+	 *
+	 * Create them with {@link defineAkteFile} and {@link defineAkteFiles}.
+	 */
 	files: AkteFiles<TGlobalData>[];
+
+	/** Configuration related to Akte build process. */
 	build?: {
+		/**
+		 * Output directory for Akte build command.
+		 *
+		 * @remarks
+		 *   This directory is overriden by the Akte Vite plugin when running Akte
+		 *   through Vite.
+		 * @defaultValue `"dist"` for Akte build command, `".akte"` for Akte Vite plugin.
+		 */
 		outDir?: string;
 	};
 	// Most global data will eventually be objects we use this
 	// assumption to make mandatory or not the `globalData` method
 } & (TGlobalData extends Record<string | number | symbol, unknown>
 	? {
+			/**
+			 * Global data retrieval function.
+			 *
+			 * The return value of this function is then shared with each Akte file.
+			 */
 			globalData: GlobalDataFn<TGlobalData>;
 	  }
 	: {
+			/**
+			 * Global data retrieval function.
+			 *
+			 * The return value of this function is then shared with each Akte file.
+			 */
 			globalData?: GlobalDataFn<TGlobalData>;
 	  });
 
@@ -33,6 +66,7 @@ const debugRender = createDebugger("akte:app:render");
 const debugRouter = createDebugger("akte:app:router");
 const debugCache = createDebugger("akte:app:cache");
 
+/** An Akte app, ready to be interacted with. */
 export class AkteApp<TGlobalData = unknown> {
 	protected config: Config<TGlobalData>;
 
@@ -46,6 +80,16 @@ export class AkteApp<TGlobalData = unknown> {
 		}
 	}
 
+	/**
+	 * Looks up the Akte file responsible for rendering the path.
+	 *
+	 * @param path - Path to lookup, e.g. "/foo"
+	 * @returns A match featuring the path, the path parameters if any, and the
+	 *   Akte file.
+	 * @throws {@link NotFoundError} When no Akte file is found for handling
+	 *   looked up path.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	lookup(path: string): MatchedRoute<{
 		file: AkteFiles<TGlobalData>;
 	}> & { path: string } {
@@ -65,6 +109,15 @@ export class AkteApp<TGlobalData = unknown> {
 		};
 	}
 
+	/**
+	 * Renders a match from {@link lookup}.
+	 *
+	 * @param match - Match to render.
+	 * @returns Rendered file.
+	 * @throws {@link NotFoundError} When the Akte file could not render the match
+	 *   (404), with an optional `cause` attached to it for uncaught errors (500)
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	async render(
 		match: MatchedRoute<{
 			file: AkteFiles<TGlobalData>;
@@ -96,6 +149,12 @@ export class AkteApp<TGlobalData = unknown> {
 		}
 	}
 
+	/**
+	 * Renders all Akte files.
+	 *
+	 * @returns Rendered files map.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	async renderAll(): Promise<Record<string, string>> {
 		debugRender("rendering all files...");
 
@@ -146,6 +205,13 @@ export class AkteApp<TGlobalData = unknown> {
 		return files;
 	}
 
+	/**
+	 * Writes a map of rendered Akte files to the specified `outDir`, or the app
+	 * specified one (defaults to `"dist"`).
+	 *
+	 * @param args - A map of rendered Akte files, and an optional `outDir`
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	async writeAll(args: {
 		outDir?: string;
 		files: Record<string, string>;
@@ -195,13 +261,28 @@ export class AkteApp<TGlobalData = unknown> {
 		);
 	}
 
+	/**
+	 * Build (renders and write) all Akte files to the specified `outDir`, or the
+	 * app specified one (defaults to `"dist"`).
+	 *
+	 * @param args - An optional `outDir`
+	 * @returns Built files array.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	async buildAll(args?: { outDir?: string }): Promise<string[]> {
 		const files = await this.renderAll();
 		await this.writeAll({ ...args, files });
 
 		return Object.keys(files);
 	}
 
+	/**
+	 * Akte caches all `globalData`, `data`, `bulkData` calls for performance.
+	 * This function can be used to clear the cache.
+	 *
+	 * @param alsoClearFileCache - Also clear cache on all registered Akte files.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	clearCache(alsoClearFileCache = false): void {
 		debugCache("clearing...");
 

src/AkteFiles.ts

@@ -4,6 +4,12 @@ import { type Awaitable } from "./types";
 import { createDebugger } from "./lib/createDebugger";
 import { pathToFilePath } from "./lib/pathToFilePath";
 
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import type { AkteApp } from "./AkteApp";
+
+/* eslint-enable @typescript-eslint/no-unused-vars */
+
 type Path<
 	TParams extends string[],
 	TPrefix extends string = string,
@@ -15,27 +21,74 @@ type Path<
 	? Path<Rest, `${TPrefix}:${TParams[0]}${string}`>
 	: string;
 
+/**
+ * A function responsible for fetching the data required to render a given file
+ * at the provided path. Used for optimization like server side rendering or
+ * serverless.
+ */
 export type FilesDataFn<
 	TGlobalData,
 	TParams extends string[],
 	TData,
 > = (context: {
+	/** Path to get data for. */
 	path: string;
+
+	/** Path parameters if any. */
 	params: Record<TParams[number], string>;
+
+	/** Akte app global data. */
 	globalData: TGlobalData;
 }) => Awaitable<TData>;
 
+/** A function responsible for fetching all the data required to render files. */
 export type FilesBulkDataFn<TGlobalData, TData> = (context: {
+	/** Akte app global data. */
 	globalData: TGlobalData;
 }) => Awaitable<Record<string, TData>>;
 
 export type FilesDefinition<TGlobalData, TParams extends string[], TData> = {
+	/**
+	 * Path pattern for the Akte files.
+	 *
+	 * @example
+	 * 	"/";
+	 * 	"/foo";
+	 * 	"/bar.json";
+	 * 	"/posts/:slug";
+	 * 	"/posts/:taxonomy/:slug";
+	 * 	"/pages/**";
+	 * 	"/assets/**.json";
+	 */
 	path: Path<TParams>;
+
+	/**
+	 * A function responsible for fetching the data required to render a given
+	 * file. Used for optimization like server side rendering or serverless.
+	 *
+	 * Throwing a {@link NotFoundError} makes the file at path to be treated as a
+	 * 404, any other error makes it treated as a 500.
+	 */
 	data?: FilesDataFn<TGlobalData, TParams, TData>;
+
+	/** A function responsible for fetching all the data required to render files. */
 	bulkData?: FilesBulkDataFn<TGlobalData, TData>;
+
+	/**
+	 * A function responsible for rendering
+	 *
+	 * @param context - Resolved file path, app global data, and data to render
+	 *   the file.
+	 * @returns Rendered file.
+	 */
 	render: (context: {
+		/** Path to render. */
 		path: string;
+
+		/** Akte app global data. */
 		globalData: TGlobalData;
+
+		/** File data for path. */
 		data: TData;
 	}) => Awaitable<string>;
 };
@@ -52,6 +105,7 @@ export class AkteFiles<
 > {
 	protected definition: FilesDefinition<TGlobalData, TParams, TData>;
 
+	/** Path pattern of this Akte files. */
 	get path(): string {
 		return this.definition.path;
 	}
@@ -62,6 +116,7 @@ export class AkteFiles<
 		debug("created %o", this.path);
 	}
 
+	/** @internal Prefer {@link AkteApp.render} or use at your own risks. */
 	async render(args: {
 		path: string;
 		params: Record<TParams[number], string>;
@@ -76,6 +131,7 @@ export class AkteFiles<
 		});
 	}
 
+	/** @internal Prefer {@link AkteApp.renderAll} or use at your own risks. */
 	async renderAll(args: {
 		globalData: TGlobalData;
 	}): Promise<Record<string, string>> {
@@ -122,6 +178,7 @@ export class AkteFiles<
 		return Object.fromEntries(fileEntries);
 	}
 
+	/** @internal Prefer {@link AkteApp.clearCache} or use at your own risks. */
 	clearCache(): void {
 		this._dataPromiseMap = new Map();
 		this._bulkDataPromise = undefined;

src/defineAkteApp.ts

@@ -1,5 +1,13 @@
 import { AkteApp, type Config } from "./AkteApp";
 
+/**
+ * Creates an Akte app from given configuration.
+ *
+ * @typeParam TGlobalData - Global data type the app should be configured with
+ *   (inferred by default)
+ * @param config - Configuration to create the Akte app with.
+ * @returns The created Akte app.
+ */
 export const defineAkteApp = <TGlobalData>(
 	config: Config<TGlobalData>,
 ): AkteApp<TGlobalData> => {

src/defineAkteFile.ts

@@ -11,7 +11,31 @@ type FileDefinition<TGlobalData, TData> = Omit<
 	"bulkData"
 >;
 
+/**
+ * Creates an Akte files instance for a single file.
+ *
+ * @example
+ * 	const posts = defineAkteFile().from({
+ * 		path: "/about",
+ * 		data() {
+ * 			return {};
+ * 		},
+ * 		render(context) {
+ * 			return "...";
+ * 		},
+ * 	});
+ *
+ * @typeParam TGlobalData - Global data the Akte files expects.
+ * @typeParam TData - Data the Akte files expects (inferred by default)
+ * @returns A factory to create the Akte files from.
+ */
 export const defineAkteFile = <TGlobalData, TData = Empty>(): {
+	/**
+	 * Creates an Akte files instance for a single file from a definition.
+	 *
+	 * @param definition - The definition to create the instance from.
+	 * @returns The created Akte files.
+	 */
 	from: <
 		_TGlobalData extends TGlobalData,
 		_TData extends TData extends Empty

src/defineAkteFiles.ts

@@ -7,11 +7,40 @@ import {
 
 import type { Empty } from "./types";
 
+/**
+ * Creates an Akte files instance.
+ *
+ * @example
+ * 	const posts = defineAkteFiles().from({
+ * 		path: "/posts/:slug",
+ * 		bulkData() {
+ * 			return {
+ * 				"/posts/foo": {},
+ * 				"/posts/bar": {},
+ * 				"/posts/baz": {},
+ * 			};
+ * 		},
+ * 		render(context) {
+ * 			return "...";
+ * 		},
+ * 	});
+ *
+ * @typeParam TGlobalData - Global data the Akte files expects.
+ * @typeParam TParams - Parameters the Akte files expects.
+ * @typeParam TData - Data the Akte files expects (inferred by default)
+ * @returns A factory to create the Akte files from.
+ */
 export const defineAkteFiles = <
 	TGlobalData,
 	TParams extends string[] | Empty = Empty,
 	TData = Empty,
 >(): {
+	/**
+	 * Creates an Akte files instance from a definition.
+	 *
+	 * @param definition - The definition to create the instance from.
+	 * @returns The created Akte files.
+	 */
 	from: <
 		_TGlobalData extends TGlobalData,
 		_TParams extends TParams extends Empty

src/vite/aktePlugin.ts

@@ -23,6 +23,11 @@ const DEFAULT_OPTIONS: Omit<ResolvedOptions<unknown>, "app" | "minifyHTML"> = {
 
 const debug = createDebugger("akte:vite", true);
 
+/**
+ * Akte Vite plugin factory.
+ *
+ * @param rawOptions - Plugin options.
+ */
 export const aktePlugin = <TGlobalData>(
 	rawOptions: Options<TGlobalData>,
 ): PluginOption[] => {