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

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

@@ -19,13 +19,83 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { captureResult, fail, failWithDetail, succeed, succeedWithDetail } from '@fgv/ts-utils';
 import { DirectoryItem } from '../directoryItem';
 import { FileItem } from '../fileItem';
 import { InMemoryDirectory, InMemoryFile, TreeBuilder } from './treeBuilder';
+import { isPathMutable } from '../filterSpec';
 /**
- * Implementation of {@link FileTree.IFileTreeAccessors} that uses an in-memory
- * tree to access files and directories.
+ * A mutable in-memory file that allows updating contents.
+ * @internal
+ */
+class MutableInMemoryFile {
+    constructor(absolutePath, contents, contentType) {
+        this.absolutePath = absolutePath;
+        this._contents = contents;
+        this.contentType = contentType;
+    }
+    get contents() {
+        return this._contents;
+    }
+    setContents(contents) {
+        this._contents = contents;
+    }
+}
+/**
+ * A mutable in-memory directory that creates mutable files.
+ * @internal
+ */
+class MutableInMemoryDirectory {
+    /* c8 ignore next 3 - internal getter used by tree traversal */
+    get children() {
+        return this._children;
+    }
+    constructor(absolutePath) {
+        this.absolutePath = absolutePath;
+        this._children = new Map();
+    }
+    getChildPath(name) {
+        if (this.absolutePath === '/') {
+            return `/${name}`;
+        }
+        return [this.absolutePath, name].join('/');
+    }
+    addFile(name, contents, contentType) {
+        /* c8 ignore next 3 - defensive: duplicate detection during construction */
+        if (this._children.has(name)) {
+            return fail(`${name}: already exists`);
+        }
+        const child = new MutableInMemoryFile(this.getChildPath(name), contents, contentType);
+        this._children.set(name, child);
+        return succeed(child);
+    }
+    getOrAddDirectory(name) {
+        const existing = this._children.get(name);
+        if (existing) {
+            if (existing instanceof MutableInMemoryDirectory) {
+                return succeed(existing);
+            }
+            return fail(`${name}: not a directory`);
+        }
+        const child = new MutableInMemoryDirectory(this.getChildPath(name));
+        this._children.set(name, child);
+        return succeed(child);
+    }
+    updateOrAddFile(name, contents, contentType) {
+        const existing = this._children.get(name);
+        if (existing) {
+            if (existing instanceof MutableInMemoryFile) {
+                existing.setContents(contents);
+                return succeed(existing);
+            }
+            return fail(`${name}: not a file`);
+        }
+        return this.addFile(name, contents, contentType);
+    }
+}
+/**
+ * Implementation of {@link FileTree.IMutableFileTreeAccessors} that uses an in-memory
+ * tree to access and modify files and directories.
  * @public
  */
 export class InMemoryTreeAccessors {
@@ -36,12 +106,18 @@ export class InMemoryTreeAccessors {
      * @public
      */
     constructor(files, params) {
-        var _a, _b;
+        var _a, _b, _c, _d;
         this._tree = TreeBuilder.create(params === null || params === void 0 ? void 0 : params.prefix).orThrow();
         this._inferContentType = (_a = params === null || params === void 0 ? void 0 : params.inferContentType) !== null && _a !== void 0 ? _a : FileItem.defaultInferContentType;
+        this._mutable = (_b = params === null || params === void 0 ? void 0 : params.mutable) !== null && _b !== void 0 ? _b : false;
+        this._mutableByPath = new Map();
+        const prefix = (_c = params === null || params === void 0 ? void 0 : params.prefix) !== null && _c !== void 0 ? _c : '/';
+        this._mutableRoot = new MutableInMemoryDirectory(prefix.endsWith('/') ? prefix.slice(0, -1) || '/' : prefix);
+        this._mutableByPath.set(this._mutableRoot.absolutePath, this._mutableRoot);
         for (const file of files) {
-            const contentType = (_b = file.contentType) !== null && _b !== void 0 ? _b : this._inferContentType(file.path).orDefault();
+            const contentType = (_d = file.contentType) !== null && _d !== void 0 ? _d : this._inferContentType(file.path).orDefault();
             this._tree.addFile(file.path, file.contents, contentType).orThrow();
+            this._addMutableFile(file.path, file.contents, contentType);
         }
     }
     /**
@@ -56,7 +132,7 @@ export class InMemoryTreeAccessors {
         return captureResult(() => new InMemoryTreeAccessors(files, params));
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
      */
     resolveAbsolutePath(...paths) {
         const parts = paths[0].startsWith('/') ? paths : [this._tree.prefix, ...paths];
@@ -64,7 +140,7 @@ export class InMemoryTreeAccessors {
         return `/${joined}`;
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getExtension}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
      */
     getExtension(path) {
         const parts = path.split('.');
@@ -74,7 +150,7 @@ export class InMemoryTreeAccessors {
         return `.${parts.pop()}`;
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getBaseName}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
      */
     getBaseName(path, suffix) {
         var _a;
@@ -86,13 +162,15 @@ export class InMemoryTreeAccessors {
         return base;
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.joinPaths}
+     * {@inheritDoc FileTree.IFileTreeAccessors.joinPaths}
      */
     joinPaths(...paths) {
-        return paths.join('/');
+        var _a;
+        const joined = paths.flatMap((p) => p.split('/').filter((s) => s.length > 0)).join('/');
+        return ((_a = paths[0]) === null || _a === void 0 ? void 0 : _a.startsWith('/')) ? `/${joined}` : joined;
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getItem}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getItem}
      */
     getItem(itemPath) {
         const existing = this._tree.byAbsolutePath.get(itemPath);
@@ -107,26 +185,24 @@ export class InMemoryTreeAccessors {
         return fail(`${itemPath}: not found`);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContents}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContents}
      */
     getFileContents(path) {
-        const item = this._tree.byAbsolutePath.get(path);
+        const absolutePath = this.resolveAbsolutePath(path);
+        const item = this._mutableByPath.get(absolutePath);
         if (item === undefined) {
-            return fail(`${path}: not found`);
+            return fail(`${absolutePath}: not found`);
         }
-        /* c8 ignore next 3 - local coverage is 100% but build coverage has intermittent issues */
-        if (!(item instanceof InMemoryFile)) {
-            return fail(`${path}: not a file`);
+        if (!(item instanceof MutableInMemoryFile)) {
+            return fail(`${absolutePath}: not a file`);
         }
-        // if the body is a string we don't want to add quotes
         if (typeof item.contents === 'string') {
             return succeed(item.contents);
         }
-        /* c8 ignore next 2 - local coverage is 100% but build coverage has intermittent issues */
         return captureResult(() => JSON.stringify(item.contents));
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContentType}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
      */
     getFileContentType(path, provided) {
         // If provided contentType is given, use it directly (highest priority)
@@ -149,7 +225,7 @@ export class InMemoryTreeAccessors {
         return this._inferContentType(path);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getChildren}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
      */
     getChildren(path) {
         const item = this._tree.byAbsolutePath.get(path);
@@ -173,5 +249,112 @@ export class InMemoryTreeAccessors {
             return children;
         });
     }
+    _addMutableFile(path, contents, contentType) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        /* c8 ignore next 3 - defensive: invalid path detection */
+        if (parts.length === 0) {
+            return fail(`${absolutePath}: invalid file path`);
+        }
+        let dir = this._mutableRoot;
+        while (parts.length > 1) {
+            const part = parts.shift();
+            const result = dir.getOrAddDirectory(part);
+            /* c8 ignore next 3 - defensive: directory conflict during construction */
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+            dir = result.value;
+            if (!this._mutableByPath.has(dir.absolutePath)) {
+                this._mutableByPath.set(dir.absolutePath, dir);
+            }
+        }
+        return dir.addFile(parts[0], contents, contentType).onSuccess((file) => {
+            this._mutableByPath.set(file.absolutePath, file);
+            return succeed(file);
+        });
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.createDirectory}
+     */
+    createDirectory(dirPath) {
+        const absolutePath = this.resolveAbsolutePath(dirPath);
+        // Check if mutability is disabled
+        if (this._mutable === false) {
+            return fail(`${absolutePath}: mutability is disabled`);
+        }
+        // Add to the TreeBuilder (read layer)
+        const treeResult = this._tree.addDirectory(absolutePath);
+        /* c8 ignore next 3 - defensive: read layer failure would indicate internal inconsistency */
+        if (treeResult.isFailure()) {
+            return fail(treeResult.message);
+        }
+        // Add to the mutable layer
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        let dir = this._mutableRoot;
+        for (const part of parts) {
+            const result = dir.getOrAddDirectory(part);
+            /* c8 ignore next 3 - defensive: mutable layer should match read layer state */
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+            dir = result.value;
+            if (!this._mutableByPath.has(dir.absolutePath)) {
+                this._mutableByPath.set(dir.absolutePath, dir);
+            }
+        }
+        return succeed(absolutePath);
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.fileIsMutable}
+     */
+    fileIsMutable(path) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        // Check if mutability is disabled
+        if (this._mutable === false) {
+            return failWithDetail(`${absolutePath}: mutability is disabled`, 'not-mutable');
+        }
+        // Check if path is excluded by filter
+        if (!isPathMutable(absolutePath, this._mutable)) {
+            return failWithDetail(`${absolutePath}: path is excluded by filter`, 'path-excluded');
+        }
+        return succeedWithDetail(true, 'transient');
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
+     */
+    saveFileContents(path, contents) {
+        const isMutable = this.fileIsMutable(path);
+        if (isMutable.isFailure()) {
+            return fail(isMutable.message);
+        }
+        const absolutePath = this.resolveAbsolutePath(path);
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        if (parts.length === 0) {
+            return fail(`${absolutePath}: invalid file path`);
+        }
+        // Navigate to parent directory, creating directories as needed
+        let dir = this._mutableRoot;
+        while (parts.length > 1) {
+            const part = parts.shift();
+            const result = dir.getOrAddDirectory(part);
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+            dir = result.value;
+            if (!this._mutableByPath.has(dir.absolutePath)) {
+                this._mutableByPath.set(dir.absolutePath, dir);
+            }
+        }
+        // Update or add the file in the mutable layer
+        return dir.updateOrAddFile(parts[0], contents).onSuccess((file) => {
+            this._mutableByPath.set(file.absolutePath, file);
+            // Also register in the read layer so getItem/getChildren can find it
+            if (!this._tree.byAbsolutePath.has(file.absolutePath)) {
+                this._tree.addFile(file.absolutePath, contents);
+            }
+            return succeed(contents);
+        });
+    }
 }
 //# sourceMappingURL=inMemoryTree.js.map

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

@@ -169,5 +169,28 @@ export class TreeBuilder {
             return succeed(file);
         });
     }
+    /**
+     * Ensures a directory exists at the given absolute path, creating
+     * intermediate directories as needed.
+     * @param absolutePath - The absolute path of the directory.
+     * @returns `Success` with the directory if successful, or
+     * `Failure` with an error message otherwise.
+     * @public
+     */
+    addDirectory(absolutePath) {
+        const parts = absolutePath.split('/').filter((p) => p.length > 0);
+        let dir = this.root;
+        for (const part of parts) {
+            const result = dir.getOrAddDirectory(part);
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+            dir = result.value;
+            if (!this.byAbsolutePath.has(dir.absolutePath)) {
+                this.byAbsolutePath.set(dir.absolutePath, dir);
+            }
+        }
+        return succeed(dir);
+    }
 }
 //# sourceMappingURL=treeBuilder.js.map

package/dist/packlets/file-tree/index.browser.js

@@ -25,6 +25,7 @@ export * from './fileTreeAccessors';
 export * from './fileTree';
 export * from './directoryItem';
 export * from './fileItem';
+export * from './filterSpec';
 // Export in-memory implementations for web compatibility
 export * from './in-memory';
 export { inMemory } from './fileTreeHelpers.inMemory';

package/dist/packlets/file-tree/index.js

@@ -24,6 +24,7 @@ export * from './fileTreeAccessors';
 export * from './fileTree';
 export * from './directoryItem';
 export * from './fileItem';
+export * from './filterSpec';
 // Export tree-shakeable helpers (filesystem ones will be shaken out if not used)
 export * from './fileTreeHelpers';
 export { inMemory } from './fileTreeHelpers.inMemory';

package/dist/packlets/json-file/file.js

@@ -22,7 +22,7 @@
 import { DefaultJsonFsHelper, JsonFsHelper } from './jsonFsHelper';
 import { DefaultJsonLike } from './jsonLike';
 /**
- * {@inheritdoc JsonFile.JsonFsHelper.readJsonFileSync}
+ * {@inheritDoc JsonFile.JsonFsHelper.readJsonFileSync}
  * @public
  */
 export function readJsonFileSync(srcPath) {

package/dist/packlets/json-file/jsonFsHelper.js

@@ -48,7 +48,7 @@ export const DefaultJsonFsHelperConfig = {
 export class JsonFsHelper {
     /**
      * 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) {

package/dist/packlets/validators/validators.js

@@ -120,26 +120,26 @@ export const jsonValue = new Validation.Base.GenericValidator({
     }
 });
 /**
- * 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
  */
 export const string = new Validation.Classes.StringValidator();
 /**
- * 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
  */
 export const number = new Validation.Classes.NumberValidator();
 /**
- * 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
  */
 export const boolean = new Validation.Classes.BooleanValidator();
 /**
  * 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
  */
@@ -151,17 +151,17 @@ export function literal(value) {
     });
 }
 /**
- * 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
  */
 export function enumeratedValue(values, message) {