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

package/dist/index.d.ts

@@ -11,8 +11,38 @@ 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[];
+}
+/**
+ * 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;

package/dist/index.js

@@ -12,17 +12,34 @@ 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(),
     };
 }
+/**
+ * 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}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/corpus",
-  "version": "0.2.0-beta.132",
+  "version": "0.2.0-beta.133",
   "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.133"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",