@fgv/ts-json-base 5.1.0-0 → 5.1.0-10

package/lib/packlets/file-tree/fileTreeAccessors.d.ts

@@ -63,7 +63,18 @@ export interface IFileTreeInitParams<TCT extends string = string> {
     mutable?: boolean | IFilterSpec;
 }
 /**
- * Interface for a file in a file tree.
+ * Options for deleting a child item from a directory.
+ * @public
+ */
+export interface IDeleteChildOptions {
+    /**
+     * If true, recursively delete directory children and their contents.
+     * Default: false (fail if directory is non-empty).
+     */
+    recursive?: boolean;
+}
+/**
+ * Interface for a read-only file in a file tree.
  * @public
  */
 export interface IFileTreeFileItem<TCT extends string = string> {
@@ -111,30 +122,39 @@ export interface IFileTreeFileItem<TCT extends string = string> {
      * `Failure` with an error message otherwise.
      */
     getRawContents(): Result<string>;
+}
+/**
+ * Extended file item interface that supports mutation operations.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} type guard to narrow.
+ * @public
+ */
+export interface IMutableFileTreeFileItem<TCT extends string = string> extends IFileTreeFileItem<TCT> {
     /**
      * Indicates whether this file can be saved.
      * @returns `DetailedSuccess` with {@link FileTree.SaveCapability} if the file can be saved,
      * or `DetailedFailure` with {@link FileTree.SaveFailureReason} if it cannot.
-     * @remarks This property is optional. If not present, the file is not mutable.
      */
     getIsMutable(): DetailedResult<boolean, SaveDetail>;
     /**
      * Sets the contents of the file from a JSON value.
      * @param json - The JSON value to serialize and save.
      * @returns `Success` if the file was saved, or `Failure` with an error message.
-     * @remarks This method is optional. If not present, the file is not mutable.
      */
     setContents(json: JsonValue): Result<JsonValue>;
     /**
      * Sets the raw contents of the file.
      * @param contents - The string contents to save.
      * @returns `Success` if the file was saved, or `Failure` with an error message.
-     * @remarks This method is optional. If not present, the file is not mutable.
      */
     setRawContents(contents: string): Result<string>;
+    /**
+     * Deletes this file from its backing store.
+     * @returns `Success` with `true` if the file was deleted, or `Failure` with an error message.
+     */
+    delete(): Result<boolean>;
 }
 /**
- * Interface for a directory in a file tree.
+ * Interface for a read-only directory in a file tree.
  * @public
  */
 export interface IFileTreeDirectoryItem<TCT extends string = string> {
@@ -156,27 +176,72 @@ export interface IFileTreeDirectoryItem<TCT extends string = string> {
      * or `Failure` with an error message otherwise.
      */
     getChildren(): Result<ReadonlyArray<FileTreeItem<TCT>>>;
+}
+/**
+ * Extended directory item interface that supports mutation operations.
+ * Use {@link FileTree.isMutableDirectoryItem | isMutableDirectoryItem} type guard to narrow.
+ * @public
+ */
+export interface IMutableFileTreeDirectoryItem<TCT extends string = string> extends IFileTreeDirectoryItem<TCT> {
     /**
      * Creates a new file as a child of this directory.
      * @param name - The file name to create.
      * @param contents - The string contents to write.
      * @returns `Success` with the new file item, or `Failure` with an error message.
-     * @remarks This method is optional. Only available on mutable directory items.
      */
-    createChildFile?(name: string, contents: string): Result<IFileTreeFileItem<TCT>>;
+    createChildFile(name: string, contents: string): Result<IMutableFileTreeFileItem<TCT>>;
     /**
      * Creates a new subdirectory as a child of this directory.
      * @param name - The directory name to create.
      * @returns `Success` with the new directory item, or `Failure` with an error message.
-     * @remarks This method is optional. Only available on mutable directory items.
      */
-    createChildDirectory?(name: string): Result<IFileTreeDirectoryItem<TCT>>;
+    createChildDirectory(name: string): Result<IMutableFileTreeDirectoryItem<TCT>>;
+    /**
+     * Deletes a child item from this directory.
+     * @param name - The name of the child to delete.
+     * @param options - Optional {@link FileTree.IDeleteChildOptions | options} controlling deletion behavior.
+     * @returns `Success` with `true` if the child was deleted, or `Failure` with an error message.
+     */
+    deleteChild(name: string, options?: IDeleteChildOptions): Result<boolean>;
+    /**
+     * Deletes this directory from its backing store.
+     * The directory must be empty or the operation will fail.
+     * @returns `Success` with `true` if the directory was deleted, or `Failure` with an error message.
+     */
+    delete(): Result<boolean>;
 }
 /**
  * Type for an item in a file tree.
  * @public
  */
 export type FileTreeItem<TCT extends string = string> = IFileTreeFileItem<TCT> | IFileTreeDirectoryItem<TCT>;
+/**
+ * Type for a mutable item in a file tree.
+ * @public
+ */
+export type MutableFileTreeItem<TCT extends string = string> = IMutableFileTreeFileItem<TCT> | IMutableFileTreeDirectoryItem<TCT>;
+/**
+ * A file item that may or may not be mutable at runtime.
+ *
+ * Use this type for parameters or fields where the code checks for mutability
+ * and handles the read-only case gracefully. Use {@link FileTree.IMutableFileTreeFileItem}
+ * when mutation is required.
+ *
+ * Narrow with {@link FileTree.isMutableFileItem} to access mutation methods.
+ * @public
+ */
+export type AnyFileTreeFileItem<TCT extends string = string> = IFileTreeFileItem<TCT> | IMutableFileTreeFileItem<TCT>;
+/**
+ * A directory item that may or may not be mutable at runtime.
+ *
+ * Use this type for parameters or fields where the code checks for mutability
+ * and handles the read-only case gracefully. Use {@link FileTree.IMutableFileTreeDirectoryItem}
+ * when mutation is required.
+ *
+ * Narrow with {@link FileTree.isMutableDirectoryItem} to access mutation methods.
+ * @public
+ */
+export type AnyFileTreeDirectoryItem<TCT extends string = string> = IFileTreeDirectoryItem<TCT> | IMutableFileTreeDirectoryItem<TCT>;
 /**
  * Common abstraction layer interface for a tree of files
  * (e.g. a file system or a zip file).
@@ -236,6 +301,8 @@ export interface IFileTreeAccessors<TCT extends string = string> {
 }
 /**
  * Extended accessors interface that supports mutation operations.
+ * All mutation methods are required — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * type guard to check if an accessor supports mutation.
  * @public
  */
 export interface IMutableFileTreeAccessors<TCT extends string = string> extends IFileTreeAccessors<TCT> {
@@ -253,12 +320,25 @@ export interface IMutableFileTreeAccessors<TCT extends string = string> extends
      * @returns `Success` if the file was saved, or `Failure` with an error message.
      */
     saveFileContents(path: string, contents: string): Result<string>;
+    /**
+     * Deletes a file at the given path.
+     * @param path - The path of the file to delete.
+     * @returns `Success` with `true` if the file was deleted, or `Failure` with an error message.
+     */
+    deleteFile(path: string): Result<boolean>;
     /**
      * Creates a directory at the given path, including any missing parent directories.
      * @param path - The path of the directory to create.
      * @returns `Success` with the absolute path if created, or `Failure` with an error message.
      */
-    createDirectory?(path: string): Result<string>;
+    createDirectory(path: string): Result<string>;
+    /**
+     * Deletes a directory at the given path.
+     * The directory must be empty or the operation will fail.
+     * @param path - The path of the directory to delete.
+     * @returns `Success` with `true` if the directory was deleted, or `Failure` with an error message.
+     */
+    deleteDirectory(path: string): Result<boolean>;
 }
 /**
  * Extended accessors interface that supports persistence operations.
@@ -295,4 +375,18 @@ export declare function isMutableAccessors<TCT extends string = string>(accessor
  * @public
  */
 export declare function isPersistentAccessors<TCT extends string = string>(accessors: IFileTreeAccessors<TCT>): accessors is IPersistentFileTreeAccessors<TCT>;
+/**
+ * Type guard to check if a file item supports mutation.
+ * @param item - The file item to check.
+ * @returns `true` if the item implements {@link FileTree.IMutableFileTreeFileItem}.
+ * @public
+ */
+export declare function isMutableFileItem<TCT extends string = string>(item: AnyFileTreeFileItem<TCT> | FileTreeItem<TCT>): item is IMutableFileTreeFileItem<TCT>;
+/**
+ * Type guard to check if a directory item supports mutation.
+ * @param item - The directory item to check.
+ * @returns `true` if the item implements {@link FileTree.IMutableFileTreeDirectoryItem}.
+ * @public
+ */
+export declare function isMutableDirectoryItem<TCT extends string = string>(item: AnyFileTreeDirectoryItem<TCT> | FileTreeItem<TCT>): item is IMutableFileTreeDirectoryItem<TCT>;
 //# sourceMappingURL=fileTreeAccessors.d.ts.map

package/lib/packlets/file-tree/fileTreeAccessors.js

@@ -23,6 +23,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMutableAccessors = isMutableAccessors;
 exports.isPersistentAccessors = isPersistentAccessors;
+exports.isMutableFileItem = isMutableFileItem;
+exports.isMutableDirectoryItem = isMutableDirectoryItem;
+// ============================================================================
+// Type Guards
+// ============================================================================
 /**
  * Type guard to check if accessors support mutation.
  * @param accessors - The accessors to check.
@@ -31,7 +36,11 @@ exports.isPersistentAccessors = isPersistentAccessors;
  */
 function isMutableAccessors(accessors) {
     const mutable = accessors;
-    return typeof mutable.fileIsMutable === 'function' && typeof mutable.saveFileContents === 'function';
+    return (typeof mutable.fileIsMutable === 'function' &&
+        typeof mutable.saveFileContents === 'function' &&
+        typeof mutable.deleteFile === 'function' &&
+        typeof mutable.createDirectory === 'function' &&
+        typeof mutable.deleteDirectory === 'function');
 }
 /**
  * Type guard to check if accessors support persistence.
@@ -47,4 +56,32 @@ function isPersistentAccessors(accessors) {
         typeof persistent.isDirty === 'function' &&
         typeof persistent.getDirtyPaths === 'function');
 }
+/**
+ * Type guard to check if a file item supports mutation.
+ * @param item - The file item to check.
+ * @returns `true` if the item implements {@link FileTree.IMutableFileTreeFileItem}.
+ * @public
+ */
+function isMutableFileItem(item) {
+    const mutable = item;
+    return (mutable.type === 'file' &&
+        typeof mutable.getIsMutable === 'function' &&
+        typeof mutable.setContents === 'function' &&
+        typeof mutable.setRawContents === 'function' &&
+        typeof mutable.delete === 'function');
+}
+/**
+ * Type guard to check if a directory item supports mutation.
+ * @param item - The directory item to check.
+ * @returns `true` if the item implements {@link FileTree.IMutableFileTreeDirectoryItem}.
+ * @public
+ */
+function isMutableDirectoryItem(item) {
+    const mutable = item;
+    return (mutable.type === 'directory' &&
+        typeof mutable.createChildFile === 'function' &&
+        typeof mutable.createChildDirectory === 'function' &&
+        typeof mutable.deleteChild === 'function' &&
+        typeof mutable.delete === 'function');
+}
 //# sourceMappingURL=fileTreeAccessors.js.map

package/lib/packlets/file-tree/fsTree.d.ts

@@ -65,9 +65,17 @@ export declare class FsFileTreeAccessors<TCT extends string = string> implements
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
      */
     saveFileContents(path: string, contents: string): Result<string>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     */
+    deleteFile(path: string): Result<boolean>;
     /**
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
      */
     createDirectory(dirPath: string): Result<string>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     */
+    deleteDirectory(dirPath: string): Result<boolean>;
 }
 //# sourceMappingURL=fsTree.d.ts.map

package/lib/packlets/file-tree/fsTree.js

@@ -154,6 +154,7 @@ class FsFileTreeAccessors {
                 }
             }
             return (0, ts_utils_1.succeedWithDetail)(true, 'persistent');
+            /* c8 ignore next 3 - unreachable when running as root (CI), tested in mutableFsTree.test.ts */
         }
         catch (_a) {
             return (0, ts_utils_1.failWithDetail)(`${absolutePath}: permission denied`, 'permission-denied');
@@ -171,6 +172,22 @@ class FsFileTreeAccessors {
             });
         });
     }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     */
+    deleteFile(path) {
+        return this.fileIsMutable(path).asResult.onSuccess(() => {
+            const absolutePath = this.resolveAbsolutePath(path);
+            return (0, ts_utils_1.captureResult)(() => {
+                const stat = fs_1.default.statSync(absolutePath);
+                if (!stat.isFile()) {
+                    throw new Error(`${absolutePath}: not a file`);
+                }
+                fs_1.default.unlinkSync(absolutePath);
+                return true;
+            });
+        });
+    }
     /**
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
      */
@@ -185,6 +202,23 @@ class FsFileTreeAccessors {
             return absolutePath;
         });
     }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     */
+    deleteDirectory(dirPath) {
+        return this.fileIsMutable(dirPath).asResult.onSuccess(() => {
+            const absolutePath = this.resolveAbsolutePath(dirPath);
+            return (0, ts_utils_1.captureResult)(() => {
+                const stat = fs_1.default.statSync(absolutePath);
+                if (!stat.isDirectory()) {
+                    throw new Error(`${absolutePath}: not a directory`);
+                }
+                // fs.rmdirSync fails if directory is non-empty (desired behavior)
+                fs_1.default.rmdirSync(absolutePath);
+                return true;
+            });
+        });
+    }
 }
 exports.FsFileTreeAccessors = FsFileTreeAccessors;
 //# sourceMappingURL=fsTree.js.map

package/lib/packlets/file-tree/in-memory/inMemoryTree.d.ts

@@ -91,6 +91,14 @@ export declare class InMemoryTreeAccessors<TCT extends string = string> implemen
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
      */
     fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     */
+    deleteFile(path: string): Result<boolean>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     */
+    deleteDirectory(path: string): Result<boolean>;
     /**
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
      */

package/lib/packlets/file-tree/in-memory/inMemoryTree.js

@@ -95,6 +95,9 @@ class MutableInMemoryDirectory {
         }
         return this.addFile(name, contents, contentType);
     }
+    removeChild(name) {
+        return this._children.delete(name);
+    }
 }
 /**
  * Implementation of {@link FileTree.IMutableFileTreeAccessors} that uses an in-memory
@@ -323,6 +326,78 @@ class InMemoryTreeAccessors {
         }
         return (0, ts_utils_1.succeedWithDetail)(true, 'transient');
     }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteFile}
+     */
+    deleteFile(path) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        if (parts.length === 0) {
+            return (0, ts_utils_1.fail)(`${absolutePath}: invalid file path`);
+        }
+        const fileName = parts.pop();
+        // Navigate to parent directory
+        let dir = this._mutableRoot;
+        for (const part of parts) {
+            const child = dir.children.get(part);
+            if (!child || !(child instanceof MutableInMemoryDirectory)) {
+                return (0, ts_utils_1.fail)(`${absolutePath}: parent directory not found`);
+            }
+            dir = child;
+        }
+        if (!dir.removeChild(fileName)) {
+            return (0, ts_utils_1.fail)(`${absolutePath}: file not found`);
+        }
+        // Also remove from the read layer's directory children and path index
+        const parentPath = parts.length === 0 ? '/' : '/' + parts.join('/');
+        const readParent = this._tree.byAbsolutePath.get(parentPath);
+        if (readParent instanceof treeBuilder_1.InMemoryDirectory) {
+            readParent.removeChild(fileName);
+        }
+        this._tree.byAbsolutePath.delete(absolutePath);
+        this._mutableByPath.delete(absolutePath);
+        return (0, ts_utils_1.succeed)(true);
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.deleteDirectory}
+     */
+    deleteDirectory(path) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        if (parts.length === 0) {
+            return (0, ts_utils_1.fail)(`${absolutePath}: invalid directory path`);
+        }
+        const dirName = parts.pop();
+        // Navigate to parent directory
+        let parentDir = this._mutableRoot;
+        for (const part of parts) {
+            const child = parentDir.children.get(part);
+            if (!child || !(child instanceof MutableInMemoryDirectory)) {
+                return (0, ts_utils_1.fail)(`${absolutePath}: parent directory not found`);
+            }
+            parentDir = child;
+        }
+        // Verify target is a directory
+        const target = parentDir.children.get(dirName);
+        if (!target || !(target instanceof MutableInMemoryDirectory)) {
+            return (0, ts_utils_1.fail)(`${absolutePath}: not a directory`);
+        }
+        // Check non-empty
+        if (target.children.size > 0) {
+            return (0, ts_utils_1.fail)(`${absolutePath}: directory is not empty`);
+        }
+        parentDir.removeChild(dirName);
+        // Also remove from the read layer
+        /* c8 ignore next 1 - defensive: branch for top-level directory deletion */
+        const readParentPath = parts.length === 0 ? '/' : '/' + parts.join('/');
+        const readParent = this._tree.byAbsolutePath.get(readParentPath);
+        if (readParent instanceof treeBuilder_1.InMemoryDirectory) {
+            readParent.removeChild(dirName);
+        }
+        this._tree.byAbsolutePath.delete(absolutePath);
+        this._mutableByPath.delete(absolutePath);
+        return (0, ts_utils_1.succeed)(true);
+    }
     /**
      * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
      */

package/lib/packlets/file-tree/in-memory/treeBuilder.d.ts

@@ -59,6 +59,12 @@ export declare class InMemoryDirectory<TCT extends string = string> {
      * `Failure` with an error message otherwise.
      */
     addFile(name: string, contents: unknown, contentType?: TCT): Result<InMemoryFile<TCT>>;
+    /**
+     * Removes a child from the directory.
+     * @param name - The name of the child to remove.
+     * @returns `true` if the child was found and removed, `false` otherwise.
+     */
+    removeChild(name: string): boolean;
     /**
      * Gets the absolute path for a child of this directory with the supplied
      * name.

package/lib/packlets/file-tree/in-memory/treeBuilder.js

@@ -94,6 +94,14 @@ class InMemoryDirectory {
         this._children.set(name, child);
         return (0, ts_utils_1.succeed)(child);
     }
+    /**
+     * Removes a child from the directory.
+     * @param name - The name of the child to remove.
+     * @returns `true` if the child was found and removed, `false` otherwise.
+     */
+    removeChild(name) {
+        return this._children.delete(name);
+    }
     /**
      * Gets the absolute path for a child of this directory with the supplied
      * name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-json-base",
-  "version": "5.1.0-0",
+  "version": "5.1.0-10",
   "description": "Typescript types and basic functions for working with json",
   "main": "lib/index.js",
   "types": "dist/ts-json-base.d.ts",
@@ -44,7 +44,7 @@
     "ts-node": "^10.9.2",
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
-    "@rushstack/heft": "1.2.6",
+    "@rushstack/heft": "1.2.7",
     "@rushstack/heft-jest-plugin": "1.2.6",
     "@types/heft-jest": "1.0.6",
     "@microsoft/api-documenter": "^7.28.2",
@@ -52,14 +52,16 @@
     "@rushstack/eslint-config": "4.6.4",
     "eslint-plugin-tsdoc": "~0.5.2",
     "@types/luxon": "^3.7.1",
-    "@rushstack/heft-node-rig": "2.11.26",
+    "@rushstack/heft-node-rig": "2.11.27",
     "@microsoft/api-extractor": "^7.55.2",
-    "@fgv/ts-utils": "5.1.0-0",
-    "@fgv/ts-utils-jest": "5.1.0-0",
-    "@fgv/heft-dual-rig": "0.1.0"
+    "typedoc": "~0.28.16",
+    "@fgv/ts-utils": "5.1.0-10",
+    "@fgv/ts-utils-jest": "5.1.0-10",
+    "@fgv/heft-dual-rig": "5.1.0-10",
+    "@fgv/typedoc-compact-theme": "5.1.0-10"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-0"
+    "@fgv/ts-utils": "5.1.0-10"
   },
   "dependencies": {
     "luxon": "^3.7.2"
@@ -76,7 +78,6 @@
     "build-all": "rushx build; rushx build-docs",
     "test-handles": "jest --runInBand --detectOpenHandles",
     "clean-jest": "jest --clear-cache",
-    "coverage": "jest --coverage --no-cache",
     "lint": "eslint src --ext .ts",
     "fixlint": "eslint src --ext .ts --fix"
   }