docs: enhanced programmatic cache API

docs/content/api.md

@@ -16,6 +16,14 @@ Only the type is exported, to create an instance of `AkteApp`, see [`defineAkteA
 
 An Akte app, ready to be interacted with.
 
+#### `files`
+
+Readonly array of Akte files registered within the app.
+
+```typescript
+AkteFiles[];
+```
+
 #### `lookup`
 
 Looks up the Akte file responsible for rendering the path.
@@ -74,6 +82,22 @@ Akte caches all `globalData`, `bulkData`, `data` calls for performance. The `cle
 (alsoClearFileCache?: boolean) => void;
 ```
 
+#### `globalDataCache`
+
+Readonly cache of the app's definition `globalData` method.
+
+```typescript
+Awaitable<TGlobalData> | undefined;
+```
+
+#### `getGlobalData`
+
+Retrieves data from the app's definition `globalData` method.
+
+```typescript
+() => Awaitable<TGlobalData>;
+```
+
 ### `AkteFiles`
 
 :::callout{icon=🈂 title="Type export only"}

src/AkteApp.ts

@@ -72,7 +72,11 @@ const debugCache = createDebugger("akte:app:cache");
 export class AkteApp<TGlobalData = unknown> {
 	protected config: Config<TGlobalData>;
 
-	// TODO: TSDocs
+	/**
+	 * Readonly array of {@link AkteFiles} registered within the app.
+	 *
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	get files(): AkteFiles<TGlobalData>[] {
 		return this.config.files;
 	}
@@ -312,14 +316,25 @@ export class AkteApp<TGlobalData = unknown> {
 		debugCache("cleared");
 	}
 
-	// TODO: TSDocs
+	/**
+	 * Readonly cache of the app's definition `globalData` method.
+	 *
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	get globalDataCache(): Awaitable<TGlobalData> | undefined {
 		return this._globalDataCache;
 	}
 
 	private _globalDataCache: Awaitable<TGlobalData> | undefined;
 
-	// TODO: TSDocs
+	/**
+	 * Retrieves data from the app's definition `globalData` method.
+	 *
+	 * @param context - Context to get global data with.
+	 * @returns Retrieved global data.
+	 * @remark Returned global data may come from cache.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	getGlobalData(): Awaitable<TGlobalData> {
 		if (!this._globalDataCache) {
 			debugCache("retrieving global data...");

src/AkteFiles.ts

@@ -3,6 +3,7 @@ import { type Awaitable } from "./types";
 
 import { createDebugger } from "./lib/createDebugger";
 import { pathToFilePath } from "./lib/pathToFilePath";
+import { toReadonlyMap } from "./lib/toReadonlyMap";
 
 /* eslint-disable @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports */
 
@@ -186,14 +187,25 @@ export class AkteFiles<
 		this._bulkDataCache = undefined;
 	}
 
-	// TODO: TSDocs + freeze map(?)
-	get dataMapCache(): Map<string, Awaitable<TData>> {
-		return this._dataMapCache;
+	/**
+	 * Readonly cache of files' definition `data` method.
+	 *
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
+	get dataMapCache(): ReadonlyMap<string, Awaitable<TData>> {
+		return toReadonlyMap(this._dataMapCache);
 	}
 
 	private _dataMapCache: Map<string, Awaitable<TData>> = new Map();
 
-	// TODO: TSDocs
+	/**
+	 * Retrieves data from files' definition `data` method with given context.
+	 *
+	 * @param context - Context to get data with.
+	 * @returns Retrieved data.
+	 * @remark Returned data may come from cache.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	getData: FilesDataFn<TGlobalData, TParams, TData> = (context) => {
 		const maybePromise = this._dataMapCache.get(context.path);
 		if (maybePromise) {
@@ -242,14 +254,25 @@ export class AkteFiles<
 		return promise;
 	};
 
-	// TODO: TSDocs
+	/**
+	 * Readonly cache of files' definition `bulkData` method.
+	 *
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	get bulkDataCache(): Awaitable<Record<string, TData>> | undefined {
 		return this._bulkDataCache;
 	}
 
 	private _bulkDataCache: Awaitable<Record<string, TData>> | undefined;
 
-	// TODO: TSDocs
+	/**
+	 * Retrieves data from files' definition `bulkData` method with given context.
+	 *
+	 * @param context - Context to get bulk data with.
+	 * @returns Retrieved bulk data.
+	 * @remark Returned bulk data may come from cache.
+	 * @experimental Programmatic API might still change not following SemVer.
+	 */
 	getBulkData: FilesBulkDataFn<TGlobalData, TData> = (context) => {
 		if (!this._bulkDataCache) {
 			debugCache("retrieving bulk data... %o", this.path);

src/lib/toReadonlyMap.ts

@@ -0,0 +1,12 @@
+export const toReadonlyMap = <K, V>(map: Map<K, V>): ReadonlyMap<K, V> => {
+	return {
+		has: map.has.bind(map),
+		get: map.get.bind(map),
+		keys: map.keys.bind(map),
+		values: map.values.bind(map),
+		entries: map.entries.bind(map),
+		forEach: map.forEach.bind(map),
+		size: map.size,
+		[Symbol.iterator]: map[Symbol.iterator].bind(map),
+	};
+};