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

package/dist/ts-json-base.d.ts

@@ -1,6 +1,7 @@
 import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { Converters as Converters_3 } from '@fgv/ts-utils';
+import { DetailedResult } from '@fgv/ts-utils';
 import { ObjectConverter as ObjectConverter_2 } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
 import { StringConverter } from '@fgv/ts-utils';
@@ -40,16 +41,16 @@ declare function arrayOf_2<T, TC = unknown>(validateElement: JsonCompatible_2.Va
 declare type ArrayValidator<T, TC = unknown> = Validation.Classes.ArrayValidator<JsonCompatibleType<T>, TC>;
 
 /**
- * A {@link Converter | Converter} which converts `unknown` to a `boolean`.
- * Accepts {@link Converters.IJsonConverterContext | IJsonConverterContext} but ignores it.
+ * A `Converter` which converts `unknown` to a `boolean`.
+ * Accepts `IJsonConverterContext` but ignores it.
  * Mirrors the behavior of `@fgv/ts-utils`.
  * @public
  */
 declare const boolean: Converter<boolean, IJsonConverterContext>;
 
 /**
- * A {@link Validation.Classes.BooleanValidator | BooleanValidator} which validates a boolean in place.
- * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * A `BooleanValidator` which validates a boolean in place.
+ * Accepts `IJsonValidatorContext` but ignores it.
  * @public
  */
 declare const boolean_2: Validator<boolean, IJsonValidatorContext>;
@@ -80,6 +81,7 @@ declare namespace Converters {
     export {
         literal,
         enumeratedValue,
+        jsonConverter,
         IJsonConverterContext,
         jsonPrimitive,
         jsonObject,
@@ -158,15 +160,15 @@ declare const DefaultJsonTreeHelper: JsonTreeHelper;
  */
 declare class DirectoryItem<TCT extends string = string> implements IFileTreeDirectoryItem<TCT> {
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem."type"}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem."type"}
      */
     readonly type: 'directory';
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem.absolutePath}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.absolutePath}
      */
     readonly absolutePath: string;
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem.name}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.name}
      */
     get name(): string;
     /**
@@ -192,9 +194,17 @@ declare class DirectoryItem<TCT extends string = string> implements IFileTreeDir
      */
     static create<TCT extends string = string>(path: string, hal: IFileTreeAccessors<TCT>): Result<DirectoryItem<TCT>>;
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem.getChildren}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.getChildren}
      */
     getChildren(): Result<ReadonlyArray<FileTreeItem<TCT>>>;
+    /**
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.createChildFile}
+     */
+    createChildFile(name: string, contents: string): Result<IFileTreeFileItem<TCT>>;
+    /**
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.createChildDirectory}
+     */
+    createChildDirectory(name: string): Result<IFileTreeDirectoryItem<TCT>>;
 }
 
 /**
@@ -209,33 +219,33 @@ declare class DirectoryItem<TCT extends string = string> implements IFileTreeDir
 declare function discriminatedObject<T, TD extends string = string, TC = unknown>(discriminatorProp: string, converters: Converters_3.DiscriminatedObjectConverters<JsonCompatibleType<T>, TD, TC>): JsonCompatible_2.Converter<T, TC>;
 
 /**
- * Helper function to create a {@link Converter | Converter} which converts `unknown` to one of a set of
+ * Helper function to create a `Converter` which converts `unknown` to one of a set of
  * supplied enumerated values. Anything else fails.
  *
  * @remarks
- * This JSON variant accepts an {@link Converters.IJsonConverterContext | IJsonConverterContext} OR
+ * This JSON variant accepts an `IJsonConverterContext` OR
  * a `ReadonlyArray<T>` as its conversion context. If the context is an array, it is used to override the
  * allowed values for that conversion; otherwise, the original `values` supplied at creation time are used.
  *
  * @param values - Array of allowed values.
  * @param message - Optional custom failure message.
- * @returns A new {@link Converter | Converter} returning `<T>`.
+ * @returns A new `Converter` returning `<T>`.
  * @public
  */
 declare function enumeratedValue<T>(values: ReadonlyArray<T>, message?: string): Converter<T, IJsonConverterContext | ReadonlyArray<T>>;
 
 /**
- * Helper function to create a {@link Validator | Validator} which validates `unknown` to one of a set of
+ * Helper function to create a `Validator` which validates `unknown` to one of a set of
  * supplied enumerated values. Anything else fails.
  *
  * @remarks
- * This JSON variant accepts an {@link Validators.IJsonValidatorContext | IJsonValidatorContext} OR
+ * This JSON variant accepts an `IJsonValidatorContext` OR
  * a `ReadonlyArray<T>` as its validation context. If the context is an array, it is used to override the
  * allowed values for that validation; otherwise, the original `values` supplied at creation time are used.
  *
  * @param values - Array of allowed values.
  * @param message - Optional custom failure message.
- * @returns A new {@link Validator | Validator} returning `<T>`.
+ * @returns A new `Validator` returning `<T>`.
  * @public
  */
 declare function enumeratedValue_2<T>(values: ReadonlyArray<T>, message?: string): Validator<T, IJsonValidatorContext | ReadonlyArray<T>>;
@@ -246,27 +256,27 @@ declare function enumeratedValue_2<T>(values: ReadonlyArray<T>, message?: string
  */
 declare class FileItem<TCT extends string = string> implements IFileTreeFileItem<TCT> {
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem."type"}
+     * {@inheritDoc FileTree.IFileTreeFileItem."type"}
      */
     readonly type: 'file';
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.absolutePath}
+     * {@inheritDoc FileTree.IFileTreeFileItem.absolutePath}
      */
     readonly absolutePath: string;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.name}
+     * {@inheritDoc FileTree.IFileTreeFileItem.name}
      */
     get name(): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.baseName}
+     * {@inheritDoc FileTree.IFileTreeFileItem.baseName}
      */
     get baseName(): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.extension}
+     * {@inheritDoc FileTree.IFileTreeFileItem.extension}
      */
     get extension(): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.contentType}
+     * {@inheritDoc FileTree.IFileTreeFileItem.contentType}
      */
     get contentType(): TCT | undefined;
     /**
@@ -296,15 +306,19 @@ declare class FileItem<TCT extends string = string> implements IFileTreeFileItem
      */
     static create<TCT extends string = string>(path: string, hal: IFileTreeAccessors<TCT>): Result<FileItem<TCT>>;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.(getContents:1)}
+     * {@inheritDoc FileTree.IFileTreeFileItem.getIsMutable}
+     */
+    getIsMutable(): DetailedResult<boolean, SaveDetail>;
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.getContents}
      */
     getContents(): Result<JsonValue>;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.(getContents:2)}
+     * {@inheritDoc FileTree.IFileTreeFileItem.getContents}
      */
     getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.getRawContents}
+     * {@inheritDoc FileTree.IFileTreeFileItem.getRawContents}
      */
     getRawContents(): Result<string>;
     /**
@@ -312,15 +326,24 @@ declare class FileItem<TCT extends string = string> implements IFileTreeFileItem
      * @param contentType - The content type of the file.
      */
     setContentType(contentType: TCT | undefined): void;
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.setContents}
+     */
+    setContents(json: JsonValue): Result<JsonValue>;
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.setRawContents}
+     */
+    setRawContents(contents: string): Result<string>;
     /**
      * Default function to infer the content type of a file.
      * @param filePath - The path of the file.
+     * @param provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.
      * @public
      */
-    static defaultInferContentType<TCT extends string = string>(__filePath: string, __provided?: string): Result<TCT | undefined>;
+    static defaultInferContentType<TCT extends string = string>(filePath: string, provided?: string): Result<TCT | undefined>;
     /**
      * Default function to accept the content type of a file.
      * @param filePath - The path of the file.
@@ -330,12 +353,18 @@ declare class FileItem<TCT extends string = string> implements IFileTreeFileItem
      * @remarks This default implementation always returns `Success` with `undefined`.
      * @public
      */
-    static defaultAcceptContentType<TCT extends string = string>(__filePath: string, provided?: TCT): Result<TCT | undefined>;
+    static defaultAcceptContentType<TCT extends string = string>(filePath: string, provided?: TCT): Result<TCT | undefined>;
 }
 
 declare namespace FileTree {
     export {
         inMemory,
+        isMutableAccessors,
+        isPersistentAccessors,
+        SaveCapability,
+        SaveFailureReason,
+        SaveDetail,
+        IFilterSpec,
         FileTreeItemType,
         ContentTypeFactory,
         IFileTreeInitParams,
@@ -343,9 +372,12 @@ declare namespace FileTree {
         IFileTreeDirectoryItem,
         FileTreeItem,
         IFileTreeAccessors,
+        IMutableFileTreeAccessors,
+        IPersistentFileTreeAccessors,
         FileTree_2 as FileTree,
         DirectoryItem,
         FileItem,
+        isPathMutable,
         forFilesystem,
         IInMemoryFile,
         InMemoryTreeAccessors,
@@ -434,11 +466,11 @@ declare function forFilesystem<TCT extends string = string>(prefix?: string): Re
 declare function forFilesystem<TCT extends string = string>(params?: IFileTreeInitParams<TCT>): Result<FileTree_2<TCT>>;
 
 /**
- * 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
  */
-declare class FsFileTreeAccessors<TCT extends string = string> implements IFileTreeAccessors<TCT> {
+declare class FsFileTreeAccessors<TCT extends string = string> implements IMutableFileTreeAccessors<TCT> {
     /**
      * Optional path prefix to prepend to all paths.
      */
@@ -448,6 +480,10 @@ declare class FsFileTreeAccessors<TCT extends string = string> implements IFileT
      * @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}.
@@ -455,37 +491,49 @@ declare class FsFileTreeAccessors<TCT extends string = string> implements IFileT
      */
     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.createDirectory}
+     */
+    createDirectory(dirPath: string): Result<string>;
 }
 
 /**
@@ -569,6 +617,21 @@ declare interface IFileTreeDirectoryItem<TCT extends string = string> {
      * or `Failure` with an error message otherwise.
      */
     getChildren(): Result<ReadonlyArray<FileTreeItem<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>>;
+    /**
+     * 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>>;
 }
 
 /**
@@ -620,6 +683,27 @@ declare interface IFileTreeFileItem<TCT extends string = string> {
      * `Failure` with an error message otherwise.
      */
     getRawContents(): Result<string>;
+    /**
+     * 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>;
 }
 
 /**
@@ -629,6 +713,28 @@ declare interface IFileTreeFileItem<TCT extends string = string> {
 declare 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;
+}
+
+/**
+ * Filter specification for controlling which paths are mutable.
+ * @public
+ */
+declare 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)[];
 }
 
 /**
@@ -708,6 +814,33 @@ declare interface IJsonValidatorContext {
     ignoreUndefinedProperties?: boolean;
 }
 
+/**
+ * Extended accessors interface that supports mutation operations.
+ * @public
+ */
+declare 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>;
+    /**
+     * 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>;
+}
+
 /**
  * Helper function to create a new {@link FileTree.FileTree | FileTree} instance
  * with accessors for an in-memory file tree.
@@ -731,13 +864,16 @@ declare function inMemory<TCT extends string = string>(files: IInMemoryFile<TCT>
 declare function inMemory<TCT extends string = string>(files: IInMemoryFile<TCT>[], params?: IFileTreeInitParams<TCT>): Result<FileTree_2<TCT>>;
 
 /**
- * Implementation of {@link FileTree.IFileTreeAccessors} that uses an in-memory
- * tree to access files and directories.
+ * Implementation of {@link FileTree.IMutableFileTreeAccessors} that uses an in-memory
+ * tree to access and modify files and directories.
  * @public
  */
-declare class InMemoryTreeAccessors<TCT extends string = string> implements IFileTreeAccessors<TCT> {
+declare class InMemoryTreeAccessors<TCT extends string = string> implements IMutableFileTreeAccessors<TCT> {
     private readonly _tree;
     private readonly _inferContentType;
+    private readonly _mutable;
+    private readonly _mutableByPath;
+    private readonly _mutableRoot;
     /**
      * Protected constructor for derived classes.
      * @param files - An array of {@link FileTree.IInMemoryFile | in-memory files} to include in the tree.
@@ -760,37 +896,72 @@ declare class InMemoryTreeAccessors<TCT extends string = string> implements IFil
      */
     static create<TCT extends string = string>(files: IInMemoryFile<TCT>[], params?: IFileTreeInitParams<TCT>): Result<InMemoryTreeAccessors<TCT>>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
      */
     resolveAbsolutePath(...paths: string[]): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getExtension}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
      */
     getExtension(path: string): string;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getBaseName}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
      */
     getBaseName(path: 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(path: string): Result<string>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContentType}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
      */
     getFileContentType(path: string, provided?: string): Result<TCT | undefined>;
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getChildren}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
      */
     getChildren(path: string): Result<ReadonlyArray<FileTreeItem<TCT>>>;
+    private _addMutableFile;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
+     */
+    createDirectory(dirPath: string): Result<string>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
+     */
+    fileIsMutable(path: string): DetailedResult<boolean, SaveDetail>;
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
+     */
+    saveFileContents(path: string, contents: string): Result<string>;
+}
+
+/**
+ * Extended accessors interface that supports persistence operations.
+ * @public
+ */
+declare 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[];
 }
 
 /**
@@ -835,6 +1006,31 @@ export declare function isJsonObject(from: unknown): from is JsonObject;
  */
 export declare function isJsonPrimitive(from: unknown): from is JsonPrimitive;
 
+/**
+ * Type guard to check if accessors support mutation.
+ * @param accessors - The accessors to check.
+ * @returns `true` if the accessors implement {@link FileTree.IMutableFileTreeAccessors}.
+ * @public
+ */
+declare function isMutableAccessors<TCT extends string = string>(accessors: IFileTreeAccessors<TCT>): accessors is IMutableFileTreeAccessors<TCT>;
+
+/**
+ * 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
+ */
+declare function isPathMutable(path: string, mutable: boolean | IFilterSpec | undefined): boolean;
+
+/**
+ * Type guard to check if accessors support persistence.
+ * @param accessors - The accessors to check.
+ * @returns `true` if the accessors implement {@link FileTree.IPersistentFileTreeAccessors}.
+ * @public
+ */
+declare function isPersistentAccessors<TCT extends string = string>(accessors: IFileTreeAccessors<TCT>): accessors is IPersistentFileTreeAccessors<TCT>;
+
 /**
  * Helper type to detect if T is exactly unknown.
  */
@@ -858,7 +1054,7 @@ export declare interface JsonArray extends Array<JsonValue> {
  * An copying converter which converts a supplied `unknown` value to
  * a valid {@link JsonArray | JsonArray}. Fails by default if any properties or array elements
  * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
+ * `IJsonConverterContext` at runtime.
  *
  * Guaranteed to return a new array.
  * @public
@@ -954,6 +1150,14 @@ export declare type JsonCompatibleType<T> = IsUnknown<T> extends true ? JsonValu
     [K in keyof T]: JsonCompatibleType<T[K]>;
 } : ['Error: Non-JSON type'];
 
+/**
+ * Creates a converter that parses JSON string content and then applies the supplied converter.
+ * @param converter - Converter to apply to the parsed JSON
+ * @returns Converter that parses JSON then validates
+ * @public
+ */
+declare function jsonConverter<T>(converter: Converter<T>): Converter<T>;
+
 declare namespace JsonFile {
     export {
         readJsonFileSync,
@@ -994,7 +1198,7 @@ declare class JsonFsHelper {
     readonly config: IJsonFsHelperConfig;
     /**
      * Construct a new {@link JsonFile.JsonFsHelper | JsonFsHelper}.
-     * @param json - Optional {@link JsonFile.IJsonLike | IJsonLike} used to process strings
+     * @param init - Optional {@link JsonFile.JsonFsHelperInitOptions | init options} to construct
      * and JSON values.
      */
     constructor(init?: JsonFsHelperInitOptions);
@@ -1057,7 +1261,7 @@ export declare interface JsonObject {
  * An copying converter which converts a supplied `unknown` value into
  * a valid {@link JsonObject | JsonObject}. Fails by default if any properties or array elements
  * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
+ * `IJsonConverterContext` at runtime.
  *
  * Guaranteed to return a new object.
  * @public
@@ -1179,7 +1383,7 @@ export declare type JsonValue = JsonPrimitive | JsonObject | JsonArray;
  * An copying converter which converts a supplied `unknown` value to a
  * valid {@link JsonValue | JsonValue}. Fails by default if any properties or array elements
  * are `undefined` - this default behavior can be overridden by supplying an appropriate
- * {@link Converters.IJsonConverterContext | context} at runtime.
+ * `IJsonConverterContext` at runtime.
  * @public
  */
 declare const jsonValue: Converter<JsonValue, IJsonConverterContext>;
@@ -1201,7 +1405,7 @@ export declare type JsonValueType = 'primitive' | 'object' | 'array';
 
 /**
  * Helper to create a converter for a literal value.
- * Accepts {@link Converters.IJsonConverterContext | IJsonConverterContext} but ignores it.
+ * Accepts `IJsonConverterContext` but ignores it.
  * Mirrors the behavior of `@fgv/ts-utils`.
  * @public
  */
@@ -1209,26 +1413,26 @@ declare function literal<T>(value: T): Converter<T, IJsonConverterContext>;
 
 /**
  * Helper to create a validator for a literal value.
- * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
+ * Accepts `IJsonValidatorContext` but ignores it.
  * Mirrors the behavior of `@fgv/ts-utils`.
  * @public
  */
 declare function literal_2<T>(value: T): Validator<T, IJsonValidatorContext>;
 
 /**
- * A {@link Converter | Converter} which converts `unknown` to a `number`.
- * Accepts {@link Converters.IJsonConverterContext | IJsonConverterContext} but ignores it.
+ * A `Converter` which converts `unknown` to a `number`.
+ * Accepts `IJsonConverterContext` but ignores it.
  * Mirrors the behavior of `@fgv/ts-utils`.
  * @public
  */
 declare const number: Converter<number, IJsonConverterContext>;
 
 /**
- * A {@link Validation.Classes.NumberValidator | NumberValidator} which validates a number in place.
+ * A `NumberValidator` which validates a number in place.
  * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
  * @public
  */
-declare const number_2: Validator<number, IJsonValidatorContext>;
+declare const number_2: Validation.Classes.NumberValidator<number, IJsonValidatorContext>;
 
 /**
  * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which converts a
@@ -1285,7 +1489,7 @@ export declare function pickJsonObject(src: JsonObject, path: string): Result<Js
 export declare function pickJsonValue(src: JsonObject, path: string): Result<JsonValue>;
 
 /**
- * {@inheritdoc JsonFile.JsonFsHelper.readJsonFileSync}
+ * {@inheritDoc JsonFile.JsonFsHelper.readJsonFileSync}
  * @public
  */
 declare function readJsonFileSync(srcPath: string): Result<JsonValue>;
@@ -1351,6 +1555,31 @@ export declare function sanitizeJson(from: unknown): Result<JsonValue>;
  */
 export declare function sanitizeJsonObject<T>(from: T): Result<T>;
 
+/**
+ * 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
+ */
+declare type SaveCapability = 'persistent' | 'transient';
+
+/**
+ * Detail type for getIsMutable results.
+ * @public
+ */
+declare type SaveDetail = SaveCapability | SaveFailureReason;
+
+/**
+ * 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
+ */
+declare type SaveFailureReason = 'not-supported' | 'read-only' | 'not-mutable' | 'path-excluded' | 'permission-denied';
+
 /**
  * A helper function to create a {@link JsonCompatible.ObjectConverter | JSON-compatible ObjectConverter<T, TC>} which converts a
  * supplied `unknown` value to a valid {@link JsonCompatibleType | JsonCompatibleType<T>} value.
@@ -1363,14 +1592,14 @@ export declare function sanitizeJsonObject<T>(from: T): Result<T>;
 declare function strictObject<T, TC = unknown>(properties: Conversion.FieldConverters<JsonCompatibleType<T>, TC>, options?: Converters_3.StrictObjectConverterOptions<JsonCompatibleType<T>>): JsonCompatible_2.ObjectConverter<T, TC>;
 
 /**
- * A {@link Converter | Converter} which converts `unknown` to a `string`.
- * Accepts {@link Converters.IJsonConverterContext | IJsonConverterContext} but ignores it.
+ * A `StringConverter` which converts `unknown` to a `string`.
+ * Accepts `IJsonConverterContext` but ignores it.
  * @public
  */
 declare const string: StringConverter<string, IJsonConverterContext>;
 
 /**
- * A {@link Validation.Classes.StringValidator | StringValidator} which validates a string in place.
+ * A `StringValidator` which validates a string in place.
  * Accepts {@link Validators.IJsonValidatorContext | IJsonValidatorContext} but ignores it.
  * @public
  */