@dogsbay/corpus 0.2.0-beta.132 → 0.2.0-beta.134

package/dist/index.d.ts

@@ -11,8 +11,65 @@ export interface Corpus {
     contains?(path: string, dir: string): boolean;
 }
 export type CorpusFiles = Map<string, string | Uint8Array>;
+export interface MapCorpusOptions {
+    /**
+     * Every path of the repo (relative to the same root as `files`), when the host knows more
+     * files than it has fetched — the playground lists a GitHub tree and fetches as it goes.
+     * The corpus lists them all, so the import sees the repo as it is; reading one that `files`
+     * does not hold returns undefined and is recorded (`missing`).
+     */
+    paths?: Iterable<string>;
+}
+export interface MapCorpus extends Corpus {
+    /** Listed paths the import read but `files` did not hold, sorted: fetch them and run it again. */
+    missing(): string[];
+}
 /**
  * A corpus over a map of files; bytes are read as UTF-8. A key that is not a plain path
  * (`../x`, `/etc/x`, `a/./b`, a backslash) is left out: the keys come from someone else's repo.
  */
-export declare function corpusFromMap(files: CorpusFiles): Corpus;
+export declare function corpusFromMap(files: CorpusFiles, opts?: MapCorpusOptions): MapCorpus;
+/**
+ * What a browser conversion still needs, when the host listed more paths than it fetched:
+ * `read` the import read (fetch them and convert again: the result changes), `copy` the
+ * output copies as they are (fetch them for the finished files; nothing is converted again).
+ * Both empty: the result is complete. Each round can find one more level of an include or
+ * `require` chain, so a host caps the rounds; a result with `read` not empty is not a
+ * conversion (its `files` may be empty: the import could not go on without them).
+ */
+export interface Unfetched {
+    read: string[];
+    copy: string[];
+    /**
+     * `copy` with where each file goes in `files` (its output path), in the same order: the host
+     * adds the fetched bytes itself, without converting again.
+     */
+    copyTo: {
+        from: string;
+        to: string;
+    }[];
+}
+/** `copyTo`'s pairs sorted by source path, and `copy` (the sources) in the same order. */
+export declare function pendingCopies(pairs: {
+    from: string;
+    to: string;
+}[]): Pick<Unfetched, "copy" | "copyTo">;
+/**
+ * The ledger message for a conversion that still needs files (undefined when none), with the
+ * error the import stopped on, when it stopped.
+ */
+export declare function unfetchedMessage(read: string[], stoppedOn?: unknown): string | undefined;
+/**
+ * Each written page's source file → its path in the project, from the pages in the order they
+ * were written: a later page at the same path replaces an earlier one, whose file then has no
+ * page (its notes would otherwise open another file's page).
+ */
+export declare function pageSources(written: Iterable<{
+    file: string;
+    path: string;
+}>): Map<string, string>;
+/** The ledger, each entry about a written page's source file given its `page`. */
+export declare function withPages<E extends {
+    file?: string;
+    page?: string;
+}>(ledger: E[], pageOf: ReadonlyMap<string, string>): E[];

package/dist/index.js

@@ -12,17 +12,60 @@ import { isPlainPath } from "@dogsbay/detect";
  * A corpus over a map of files; bytes are read as UTF-8. A key that is not a plain path
  * (`../x`, `/etc/x`, `a/./b`, a backslash) is left out: the keys come from someone else's repo.
  */
-export function corpusFromMap(files) {
+export function corpusFromMap(files, opts = {}) {
     const decoder = new TextDecoder();
-    const paths = [...files.keys()].filter(isPlainPath).sort();
+    const paths = [...new Set([...files.keys(), ...(opts.paths ?? [])])].filter(isPlainPath).sort();
     const listed = new Set(paths);
+    const missing = new Set();
     return {
         paths,
         text(path) {
             if (!listed.has(path))
                 return undefined;
             const v = files.get(path);
-            return v === undefined ? undefined : typeof v === "string" ? v : decoder.decode(v);
+            if (v === undefined) {
+                missing.add(path);
+                return undefined;
+            }
+            return typeof v === "string" ? v : decoder.decode(v);
         },
+        missing: () => [...missing].sort(),
     };
 }
+/** `copyTo`'s pairs sorted by source path, and `copy` (the sources) in the same order. */
+export function pendingCopies(pairs) {
+    const copyTo = [...pairs].sort((a, b) => (a.from < b.from ? -1 : a.from > b.from ? 1 : 0));
+    return { copy: copyTo.map((p) => p.from), copyTo };
+}
+/**
+ * The ledger message for a conversion that still needs files (undefined when none), with the
+ * error the import stopped on, when it stopped.
+ */
+export function unfetchedMessage(read, stoppedOn) {
+    if (!read.length)
+        return undefined;
+    const names = `${read.slice(0, 3).join(", ")}${read.length > 3 ? ", …" : ""}`;
+    const stopped = stoppedOn instanceof Error ? ` It stopped on: ${stoppedOn.message}` : "";
+    return `${read.length} file${read.length === 1 ? "" : "s"} the conversion reads ${read.length === 1 ? "was" : "were"} not given (${names}): fetch them and convert again.${stopped}`;
+}
+/**
+ * Each written page's source file → its path in the project, from the pages in the order they
+ * were written: a later page at the same path replaces an earlier one, whose file then has no
+ * page (its notes would otherwise open another file's page).
+ */
+export function pageSources(written) {
+    const fileAt = new Map();
+    for (const { file, path } of written)
+        fileAt.set(path, file);
+    const pageOf = new Map();
+    for (const [path, file] of fileAt)
+        pageOf.set(file, path);
+    return pageOf;
+}
+/** The ledger, each entry about a written page's source file given its `page`. */
+export function withPages(ledger, pageOf) {
+    return ledger.map((e) => {
+        const page = e.file === undefined ? undefined : pageOf.get(e.file);
+        return page === undefined ? e : { ...e, page };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/corpus",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.134",
   "description": "A documentation repository as its importers read it, in the browser or in Node: plain paths plus text on demand, from a map of files or from a folder whose symlinks are kept inside it",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@dogsbay/detect": "0.2.0-beta.132"
+    "@dogsbay/detect": "0.2.0-beta.134"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",