@executablemd/runtime 0.9.1 → 0.10.0

package/esm/apis.js

@@ -355,6 +355,18 @@ export const API = {
                 throw err;
             }
         },
+        *readDirectory(path) {
+            const entries = [];
+            for (const entry of yield* FsApi.operations.readdirDirents(path)) {
+                entries.push({
+                    name: entry.name,
+                    isFile: entry.isFile(),
+                    isDirectory: entry.isDirectory(),
+                    isSymbolicLink: entry.isSymbolicLink(),
+                });
+            }
+            return entries;
+        },
         *glob(options) {
             const { patterns, root, exclude = [] } = options;
             const matched = [];
@@ -477,6 +489,7 @@ export function exec(options) {
 export const readTextFile = API.Fs.operations.readTextFile;
 export const stat = API.Fs.operations.stat;
 export const lstat = API.Fs.operations.lstat;
+export const readDirectory = API.Fs.operations.readDirectory;
 export const glob = API.Fs.operations.glob;
 export const writeTextFile = API.Fs.operations.writeTextFile;
 export const ensureDir = API.Fs.operations.ensureDir;

package/esm/mod.js

@@ -8,7 +8,8 @@
  * Seven domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
  * - `API.Fs` — the low-level host filesystem (`readTextFile`, `writeTextFile`,
- *   `stat`, `lstat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
+ *   `stat`, `lstat`, `readDirectory`, `glob`, `realpath`, `ensureDir`, `rename`,
+ *   `remove`)
  * - `API.Files` — document filesystem access as whole semantic operations,
  *   with no host default. `useHostFiles()` installs the host provider.
  * - `API.Fetch` — HTTP requests (`fetch`)
@@ -25,7 +26,7 @@
  */
 import "./_dnt.polyfills.js";
 export { API } from "./apis.js";
-export { exec, readTextFile, writeTextFile, stat, lstat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
+export { exec, readTextFile, writeTextFile, stat, lstat, readDirectory, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
 export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
 export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";
 export { asDuration, durationError, parseDuration } from "./duration.js";

package/esm/test/stubs.js

@@ -45,7 +45,10 @@ export function* useStubService(endpoint) {
  * - `stat` returns `{ exists: true, isFile: true }` for keys in the map.
  * - `lstat` answers the same, with `isSymbolicLink: false`: an in-memory map
  *   holds file content, so nothing in it is a link to somewhere else.
- * - `glob` throws (not stubbed). Install `API.Fs.around()` directly if needed.
+ * - `readDirectory` and `glob` throw (not stubbed). An in-memory map of file
+ *   paths holds no directory structure, so answering either from it would
+ *   invent one; install `API.Fs.around()` directly when a test needs to
+ *   enumerate.
  * - the writing half — `writeTextFile`, `ensureDir`, `rename`, `remove`, and
  *   `realpath` — is not stubbed and reaches the real filesystem. A test that
  *   exercises a document writing files wants a real temporary directory.
@@ -71,6 +74,9 @@ export function* useStubFs(files) {
             const exists = path in files;
             return { exists, isFile: exists, isDirectory: false, isSymbolicLink: false };
         },
+        *readDirectory(_args, _next) {
+            throw new Error("readDirectory not stubbed");
+        },
         *glob(_args, _next) {
             throw new Error("glob not stubbed");
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/runtime",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Runtime host APIs for executable.md documents.",
   "homepage": "https://executable.md",
   "repository": {

package/types/apis.d.ts

@@ -104,6 +104,21 @@ export interface LinkStatResult {
     isDirectory: boolean;
     isSymbolicLink: boolean;
 }
+/**
+ * One entry of a directory, as the entry itself rather than as what it leads
+ * to.
+ *
+ * Plain data: a caller reads members, never host methods, so the same values
+ * cross a substituted provider and the default adapter. A symbolic link reports
+ * `isSymbolicLink: true` with `isFile` and `isDirectory` both false, whatever
+ * it points at — the same shape `lstat` answers with.
+ */
+export interface DirectoryEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
 /**
  * Minimal response headers interface.
  *
@@ -193,6 +208,17 @@ interface FsHandler {
      * link is not removing that file. Missing is an answer here too.
      */
     lstat(path: string): Operation<LinkStatResult>;
+    /**
+     * The entries one directory holds directly, in whatever order the host
+     * reports them.
+     *
+     * One level, and nothing more: it does not recurse, does not follow a
+     * symbolic link, does not sort, and does not soften a directory that cannot
+     * be read into an empty answer. A caller that walks a tree decides for itself
+     * which directories are worth reading, which is what lets it skip a subtree
+     * entirely rather than filter one it has already walked.
+     */
+    readDirectory(path: string): Operation<DirectoryEntry[]>;
     /**
      * Files and symbolic links beneath `root` whose path relative to it matches
      * `patterns` and matches none of `exclude`. Paths come back relative and
@@ -288,6 +314,7 @@ export declare function exec(options: ProcessExecOptions & {
 export declare const readTextFile: typeof API.Fs.operations.readTextFile;
 export declare const stat: typeof API.Fs.operations.stat;
 export declare const lstat: typeof API.Fs.operations.lstat;
+export declare const readDirectory: typeof API.Fs.operations.readDirectory;
 export declare const glob: typeof API.Fs.operations.glob;
 export declare const writeTextFile: typeof API.Fs.operations.writeTextFile;
 export declare const ensureDir: typeof API.Fs.operations.ensureDir;

package/types/mod.d.ts

@@ -8,7 +8,8 @@
  * Seven domain APIs:
  * - `API.Process` — subprocess execution (`exec`)
  * - `API.Fs` — the low-level host filesystem (`readTextFile`, `writeTextFile`,
- *   `stat`, `lstat`, `glob`, `realpath`, `ensureDir`, `rename`, `remove`)
+ *   `stat`, `lstat`, `readDirectory`, `glob`, `realpath`, `ensureDir`, `rename`,
+ *   `remove`)
  * - `API.Files` — document filesystem access as whole semantic operations,
  *   with no host default. `useHostFiles()` installs the host provider.
  * - `API.Fetch` — HTTP requests (`fetch`)
@@ -25,8 +26,8 @@
  */
 import "./_dnt.polyfills.js";
 export { API } from "./apis.js";
-export { exec, readTextFile, writeTextFile, stat, lstat, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
-export type { EvalBlock, FetchInit, FetchOperation, LinkStatResult, ResponseHeaders, RuntimeFetchResponse, StatResult, } from "./apis.js";
+export { exec, readTextFile, writeTextFile, stat, lstat, readDirectory, glob, realpath, ensureDir, rename, remove, fetch, cwd, env, platform, command, compile, useQuietProcessOutput, } from "./apis.js";
+export type { DirectoryEntry, EvalBlock, FetchInit, FetchOperation, LinkStatResult, ResponseHeaders, RuntimeFetchResponse, StatResult, } from "./apis.js";
 export { Service, SERVICE_HOSTNAME, SERVICE_READY_PREFIX, ServiceProcessExitBeforeReadyError, ServiceProtocolDuplicateError, ServiceProtocolHostnameMismatchError, ServiceProtocolIncompatibleError, ServiceProtocolMalformedError, ServiceProtocolTokenMismatchError, ServiceProviderError, ServiceStartupTimeoutError, ServiceTeardownError, ServiceUnexpectedExitError, parseServiceReadyRecord, startService, } from "./service.js";
 export type { ServiceEndpoint, ServiceHandler, ServiceAttachment, ServiceStartOptions, } from "./service.js";
 export { Config, timeout, timeoutExec, timeoutFetch } from "./config.js";

package/types/test/stubs.d.ts

@@ -30,7 +30,10 @@ export declare function useStubService(endpoint: ServiceEndpoint): Operation<voi
  * - `stat` returns `{ exists: true, isFile: true }` for keys in the map.
  * - `lstat` answers the same, with `isSymbolicLink: false`: an in-memory map
  *   holds file content, so nothing in it is a link to somewhere else.
- * - `glob` throws (not stubbed). Install `API.Fs.around()` directly if needed.
+ * - `readDirectory` and `glob` throw (not stubbed). An in-memory map of file
+ *   paths holds no directory structure, so answering either from it would
+ *   invent one; install `API.Fs.around()` directly when a test needs to
+ *   enumerate.
  * - the writing half — `writeTextFile`, `ensureDir`, `rename`, `remove`, and
  *   `realpath` — is not stubbed and reaches the real filesystem. A test that
  *   exercises a document writing files wants a real temporary directory.