3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-29 17:07:08 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(utils): JSDoc for all APIs (#6980)

Browse source 
* feat(utils): JSDoc for all APIs

* fix tests
This commit is contained in:
Joshua Chen 2022-03-24 21:34:31 +08:00 • committed by GitHub
parent b8d2a4e84d
commit 2eeb0e46a2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
31 changed files with 637 additions and 255 deletions
Download patch file Download diff file Expand all files Collapse all files

29
packages/docusaurus-utils/src/emitUtils.ts
View file

@ -13,6 +13,16 @@ import {findAsyncSequential} from './jsUtils';
const fileHash = new Map<string, string>();
/**
* Outputs a file to the generated files directory. Only writes files if content
* differs from cache (for hot reload performance).
*
* @param generatedFilesDir Absolute path.
* @param file Path relative to `generatedFilesDir`.
* @param content String content to write.
* @param skipCache If `true` (defaults as `true` for production), file is
* force-rewritten, skipping cache.
*/
export async function generate(
generatedFilesDir: string,
file: string,
@ -23,14 +33,21 @@ export async function generate(
if (skipCache) {
await fs.outputFile(filepath, content);
// Cache still needs to be reset, otherwise, writing "A", "B", and "A" where
// "B" skips cache will cause the last "A" not be able to overwrite as the
// first "A" remains in cache. But if the file never existed in cache, no
// need to register it.
if (fileHash.get(filepath)) {
fileHash.set(filepath, createHash('md5').update(content).digest('hex'));
}
return;
}
let lastHash = fileHash.get(filepath);
// If file already exists but its not in runtime cache yet,
// we try to calculate the content hash and then compare
// This is to avoid unnecessary overwriting and we can reuse old file.
// If file already exists but it's not in runtime cache yet, we try to
// calculate the content hash and then compare. This is to avoid unnecessary
// overwriting and we can reuse old file.
if (!lastHash && (await fs.pathExists(filepath))) {
const lastContent = await fs.readFile(filepath, 'utf8');
lastHash = createHash('md5').update(lastContent).digest('hex');
@ -45,7 +62,7 @@ export async function generate(
}
}
const chunkNameCache = new Map();
const chunkNameCache = new Map<string, string>();
/**
* Generate unique chunk name given a module path.
@ -56,7 +73,7 @@ export function genChunkName(
preferredName?: string,
shortId: boolean = process.env.NODE_ENV === 'production',
): string {
let chunkName: string | undefined = chunkNameCache.get(modulePath);
let chunkName = chunkNameCache.get(modulePath);
if (!chunkName) {
if (shortId) {
chunkName = simpleHash(modulePath, 8);
@ -82,6 +99,8 @@ export function genChunkName(
* @returns This returns a buffer, which you have to decode string yourself if
* needed. (Not always necessary since the output isn't for human consumption
* anyways, and most HTML manipulation libs accept buffers)
* @throws Throws when the HTML file is not found at any of the potential paths.
* This should never happen as it would lead to a 404.
*/
export async function readOutputHTMLFile(
permalink: string,