@fgv/ts-json-base 5.0.2 → 5.1.0-1

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

@@ -1,6 +1,42 @@
-import { Result } from '@fgv/ts-utils';
+import { DetailedResult, Result } from '@fgv/ts-utils';
 import { Converter, Validator } from '@fgv/ts-utils';
 import { JsonValue } from '../json';
+/**
+ * Indicates the persistence capability of a save operation.
+ * - `persistent`: Changes are saved to durable storage (e.g., file system).
+ * - `transient`: Changes are saved in memory only and will be lost on reload.
+ * @public
+ */
+export type SaveCapability = 'persistent' | 'transient';
+/**
+ * Indicates the reason a save operation cannot be performed.
+ * - `not-supported`: The accessors do not support mutation.
+ * - `read-only`: The file or file system is read-only.
+ * - `not-mutable`: Mutability is disabled in configuration.
+ * - `path-excluded`: The path is excluded by the mutability filter.
+ * - `permission-denied`: Insufficient permissions to write.
+ * @public
+ */
+export type SaveFailureReason = 'not-supported' | 'read-only' | 'not-mutable' | 'path-excluded' | 'permission-denied';
+/**
+ * Detail type for getIsMutable results.
+ * @public
+ */
+export type SaveDetail = SaveCapability | SaveFailureReason;
+/**
+ * Filter specification for controlling which paths are mutable.
+ * @public
+ */
+export interface IFilterSpec {
+    /**
+     * Paths or patterns to include. If specified, only matching paths are mutable.
+     */
+    include?: (string | RegExp)[];
+    /**
+     * Paths or patterns to exclude. Matching paths are not mutable.
+     */
+    exclude?: (string | RegExp)[];
+}
 /**
  * Type of item in a file tree.
  * @public
@@ -18,9 +54,27 @@ export type ContentTypeFactory<TCT extends string = string> = (filePath: string,
 export interface IFileTreeInitParams<TCT extends string = string> {
     prefix?: string;
     inferContentType?: ContentTypeFactory<TCT>;
+    /**
+     * Controls mutability of the file tree.
+     * - `undefined` or `false`: No files are mutable.
+     * - `true`: All files are mutable.
+     * - `IFilterSpec`: Only files matching the filter are mutable.
+     */
+    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> {
@@ -70,7 +124,37 @@ export interface IFileTreeFileItem<TCT extends string = string> {
     getRawContents(): Result<string>;
 }
 /**
- * Interface for a directory in a file tree.
+ * 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.
+     */
+    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.
+     */
+    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.
+     */
+    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 read-only directory in a file tree.
  * @public
  */
 export interface IFileTreeDirectoryItem<TCT extends string = string> {
@@ -93,11 +177,71 @@ export interface IFileTreeDirectoryItem<TCT extends string = string> {
      */
     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.
+     */
+    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.
+     */
+    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).
@@ -155,4 +299,94 @@ export interface IFileTreeAccessors<TCT extends string = string> {
      */
     getChildren(path: string): Result<ReadonlyArray<FileTreeItem<TCT>>>;
 }
+/**
+ * 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> {
+    /**
+     * Checks if a file at the given path can be saved.
+     * @param path - The path to check.
+     * @returns `DetailedSuccess` with {@link FileTree.SaveCapability} if the file can be saved,
+     * or `DetailedFailure` with {@link FileTree.SaveFailureReason} if it cannot.
+     */
+    fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
+    /**
+     * Saves the contents to a file at the given path.
+     * @param path - The path of the file to save.
+     * @param contents - The string contents to save.
+     * @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>;
+    /**
+     * 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.
+ * @public
+ */
+export interface IPersistentFileTreeAccessors<TCT extends string = string> extends IMutableFileTreeAccessors<TCT> {
+    /**
+     * Synchronize all dirty files to persistent storage.
+     * @returns Promise resolving to success or failure
+     */
+    syncToDisk(): Promise<Result<void>>;
+    /**
+     * Check if there are unsaved changes.
+     * @returns True if there are dirty files
+     */
+    isDirty(): boolean;
+    /**
+     * Get paths of all files with unsaved changes.
+     * @returns Array of dirty file paths
+     */
+    getDirtyPaths(): string[];
+}
+/**
+ * Type guard to check if accessors support mutation.
+ * @param accessors - The accessors to check.
+ * @returns `true` if the accessors implement {@link FileTree.IMutableFileTreeAccessors}.
+ * @public
+ */
+export declare function isMutableAccessors<TCT extends string = string>(accessors: IFileTreeAccessors<TCT>): accessors is IMutableFileTreeAccessors<TCT>;
+/**
+ * Type guard to check if accessors support persistence.
+ * @param accessors - The accessors to check.
+ * @returns `true` if the accessors implement {@link FileTree.IPersistentFileTreeAccessors}.
+ * @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

@@ -21,4 +21,67 @@
  * SOFTWARE.
  */
 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.
+ * @returns `true` if the accessors implement {@link FileTree.IMutableFileTreeAccessors}.
+ * @public
+ */
+function isMutableAccessors(accessors) {
+    const mutable = accessors;
+    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.
+ * @param accessors - The accessors to check.
+ * @returns `true` if the accessors implement {@link FileTree.IPersistentFileTreeAccessors}.
+ * @public
+ */
+function isPersistentAccessors(accessors) {
+    const persistent = accessors;
+    /* c8 ignore next 6 - no current accessor implements IPersistentFileTreeAccessors */
+    return (isMutableAccessors(accessors) &&
+        typeof persistent.syncToDisk === 'function' &&
+        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/filterSpec.d.ts

@@ -0,0 +1,10 @@
+import { IFilterSpec } from './fileTreeAccessors';
+/**
+ * Checks if a path is allowed by a mutability configuration.
+ * @param path - The path to check.
+ * @param mutable - The mutability configuration.
+ * @returns `true` if the path is mutable according to the configuration.
+ * @public
+ */
+export declare function isPathMutable(path: string, mutable: boolean | IFilterSpec | undefined): boolean;
+//# sourceMappingURL=filterSpec.d.ts.map

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

@@ -0,0 +1,77 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPathMutable = isPathMutable;
+/**
+ * Checks if a path matches a single pattern (string or RegExp).
+ * @param path - The path to check.
+ * @param pattern - The pattern to match against.
+ * @returns `true` if the path matches the pattern.
+ * @internal
+ */
+function matchesPattern(path, pattern) {
+    if (typeof pattern === 'string') {
+        return path === pattern || path.startsWith(pattern + '/') || path.includes(pattern);
+    }
+    return pattern.test(path);
+}
+/**
+ * Checks if a path matches any pattern in an array.
+ * @param path - The path to check.
+ * @param patterns - The patterns to match against.
+ * @returns `true` if the path matches any pattern.
+ * @internal
+ */
+function matchesAny(path, patterns) {
+    if (!patterns || patterns.length === 0) {
+        return false;
+    }
+    return patterns.some((pattern) => matchesPattern(path, pattern));
+}
+/**
+ * Checks if a path is allowed by a mutability configuration.
+ * @param path - The path to check.
+ * @param mutable - The mutability configuration.
+ * @returns `true` if the path is mutable according to the configuration.
+ * @public
+ */
+function isPathMutable(path, mutable) {
+    if (mutable === undefined || mutable === false) {
+        return false;
+    }
+    if (mutable === true) {
+        return true;
+    }
+    const { include, exclude } = mutable;
+    // If exclude patterns are specified and path matches, it's not mutable
+    if (matchesAny(path, exclude)) {
+        return false;
+    }
+    // If include patterns are specified, path must match at least one
+    if (include && include.length > 0) {
+        return matchesAny(path, include);
+    }
+    // No include patterns means all paths (not excluded) are mutable
+    return true;
+}
+//# sourceMappingURL=filterSpec.js.map

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

@@ -1,11 +1,11 @@
-import { FileTreeItem, IFileTreeAccessors, IFileTreeInitParams } from './fileTreeAccessors';
-import { Result } from '@fgv/ts-utils';
+import { FileTreeItem, IFileTreeInitParams, IMutableFileTreeAccessors, SaveDetail } from './fileTreeAccessors';
+import { DetailedResult, Result } from '@fgv/ts-utils';
 /**
- * Implementation of {@link FileTree.IFileTreeAccessors} that uses the
- * file system to access files and directories.
+ * Implementation of {@link FileTree.IMutableFileTreeAccessors} that uses the
+ * file system to access and modify files and directories.
  * @public
  */
-export declare class FsFileTreeAccessors<TCT extends string = string> implements IFileTreeAccessors<TCT> {
+export declare class FsFileTreeAccessors<TCT extends string = string> implements IMutableFileTreeAccessors<TCT> {
     /**
      * Optional path prefix to prepend to all paths.
      */
@@ -15,6 +15,10 @@ export declare class FsFileTreeAccessors<TCT extends string = string> implements
      * @public
      */
     protected readonly _inferContentType: (filePath: string) => Result<TCT | undefined>;
+    /**
+     * The mutability configuration.
+     */
+    private readonly _mutable;
     /**
      * Construct a new instance of the {@link FileTree.FsFileTreeAccessors | FsFileTreeAccessors} class.
      * @param params - Optional {@link FileTree.IFileTreeInitParams | initialization parameters}.
@@ -22,36 +26,56 @@ export declare class FsFileTreeAccessors<TCT extends string = string> implements
      */
     constructor(params?: IFileTreeInitParams<TCT>);
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
      */
     resolveAbsolutePath(...paths: string[]): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getExtension}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
      */
     getExtension(itemPath: string): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getBaseName}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
      */
     getBaseName(itemPath: string, suffix?: string): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.joinPaths}
+     * {@inheritDoc FileTree.IFileTreeAccessors.joinPaths}
      */
     joinPaths(...paths: string[]): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getItem}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getItem}
      */
     getItem(itemPath: string): Result<FileTreeItem<TCT>>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContents}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContents}
      */
     getFileContents(filePath: string): Result<string>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContentType}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
      */
     getFileContentType(filePath: string, provided?: string): Result<TCT | undefined>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getChildren}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
      */
     getChildren(dirPath: string): Result<ReadonlyArray<FileTreeItem<TCT>>>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
+     */
+    fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
+    /**
+     * {@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