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

package/CHANGELOG.json

@@ -1,6 +1,27 @@
 {
   "name": "@fgv/ts-json-base",
   "entries": [
+    {
+      "version": "5.0.2",
+      "tag": "@fgv/ts-json-base_v5.0.2",
+      "date": "Wed, 17 Dec 2025 18:08:09 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "dual-publish"
+          },
+          {
+            "comment": "add converters that take json context"
+          },
+          {
+            "comment": "minor cleanup"
+          },
+          {
+            "comment": "export JsonCompatible for web consumers as well"
+          }
+        ]
+      }
+    },
     {
       "version": "5.0.1",
       "tag": "@fgv/ts-json-base_v5.0.1",

package/dist/packlets/converters/converters.js

@@ -19,7 +19,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { Conversion, Converters as BaseConverters, StringConverter, fail, succeed } from '@fgv/ts-utils';
+import { Conversion, Converters as BaseConverters, StringConverter, captureResult, fail, succeed } from '@fgv/ts-utils';
 import { isJsonArray, isJsonObject } from '../json';
 /**
  * An converter which converts a supplied `unknown` value to a valid {@link JsonPrimitive | JsonPrimitive}.
@@ -45,7 +45,7 @@ export const jsonPrimitive = new Conversion.BaseConverter((from, __self, ctx) =>
  * 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
@@ -81,7 +81,7 @@ export const jsonObject = new Conversion.BaseConverter((from, __self, ctx) => {
  * 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
@@ -119,7 +119,7 @@ export const jsonArray = new Conversion.BaseConverter((from, __self, ctx) => {
  * 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
  */
 export const jsonValue = new Conversion.BaseConverter((from, __self, ctx) => {
@@ -132,28 +132,28 @@ export const jsonValue = new Conversion.BaseConverter((from, __self, ctx) => {
     return jsonPrimitive.convert(from, ctx);
 });
 /**
- * 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
  */
 export const string = new StringConverter();
 /**
- * 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
  */
 export const number = new Conversion.BaseConverter((from) => BaseConverters.number.convert(from));
 /**
- * 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
  */
 export const boolean = new Conversion.BaseConverter((from) => BaseConverters.boolean.convert(from));
 /**
  * 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
  */
@@ -161,17 +161,17 @@ export function literal(value) {
     return BaseConverters.literal(value);
 }
 /**
- * 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
  */
 export function enumeratedValue(values, message) {
@@ -184,4 +184,26 @@ export function enumeratedValue(values, message) {
         return fail(message !== null && message !== void 0 ? message : `Invalid enumerated value ${JSON.stringify(from)}`);
     });
 }
+/**
+ * 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
+ */
+export function jsonConverter(converter) {
+    return new Conversion.BaseConverter((from) => {
+        if (typeof from !== 'string') {
+            return fail('Input must be a string');
+        }
+        const parseResult = captureResult(() => JSON.parse(from));
+        if (parseResult.isFailure()) {
+            return fail(`Failed to parse JSON: ${parseResult.message}`);
+        }
+        const parsed = parseResult.value;
+        if (typeof parsed !== 'object' || parsed === null) {
+            return fail('Failed to parse JSON: JSON content must be an object');
+        }
+        return converter.convert(parsed);
+    });
+}
 //# sourceMappingURL=converters.js.map

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

@@ -19,14 +19,15 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { captureResult } from '@fgv/ts-utils';
+import { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { isMutableAccessors } from './fileTreeAccessors';
 /**
  * Class representing a directory in a file tree.
  * @public
  */
 export class DirectoryItem {
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem.name}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.name}
      */
     get name() {
         return this._hal.getBaseName(this.absolutePath);
@@ -40,7 +41,7 @@ export class DirectoryItem {
      */
     constructor(path, hal) {
         /**
-         * {@inheritdoc FileTree.IFileTreeDirectoryItem."type"}
+         * {@inheritDoc FileTree.IFileTreeDirectoryItem."type"}
          */
         this.type = 'directory';
         this._hal = hal;
@@ -58,10 +59,40 @@ export class DirectoryItem {
         return captureResult(() => new DirectoryItem(path, hal));
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeDirectoryItem.getChildren}
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.getChildren}
      */
     getChildren() {
         return this._hal.getChildren(this.absolutePath);
     }
+    /**
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.createChildFile}
+     */
+    createChildFile(name, contents) {
+        if (!isMutableAccessors(this._hal)) {
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        const filePath = this._hal.joinPaths(this.absolutePath, name);
+        return this._hal.saveFileContents(filePath, contents).onSuccess(() => this._hal.getItem(filePath).onSuccess((item) => {
+            /* c8 ignore next 3 - defensive: verifies accessor returned correct item type after save */
+            if (item.type !== 'file') {
+                return fail(`${filePath}: expected file but got ${item.type}`);
+            }
+            return succeed(item);
+        }));
+    }
+    /**
+     * {@inheritDoc FileTree.IFileTreeDirectoryItem.createChildDirectory}
+     */
+    createChildDirectory(name) {
+        if (!isMutableAccessors(this._hal)) {
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        /* c8 ignore next 3 - defensive: createDirectory should always exist if isMutableAccessors is true */
+        if (this._hal.createDirectory === undefined) {
+            return fail(`${this.absolutePath}: directory creation not supported`);
+        }
+        const dirPath = this._hal.joinPaths(this.absolutePath, name);
+        return this._hal.createDirectory(dirPath).onSuccess(() => DirectoryItem.create(dirPath, this._hal));
+    }
 }
 //# sourceMappingURL=directoryItem.js.map

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

@@ -19,32 +19,33 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { captureResult, succeed } from '@fgv/ts-utils';
+import { captureResult, fail, failWithDetail, succeed, Success } from '@fgv/ts-utils';
+import { isMutableAccessors } from './fileTreeAccessors';
 /**
  * Class representing a file in a file tree.
  * @public
  */
 export class FileItem {
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.name}
+     * {@inheritDoc FileTree.IFileTreeFileItem.name}
      */
     get name() {
         return this._hal.getBaseName(this.absolutePath);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.baseName}
+     * {@inheritDoc FileTree.IFileTreeFileItem.baseName}
      */
     get baseName() {
         return this._hal.getBaseName(this.absolutePath, this.extension);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.extension}
+     * {@inheritDoc FileTree.IFileTreeFileItem.extension}
      */
     get extension() {
         return this._hal.getExtension(this.absolutePath);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.contentType}
+     * {@inheritDoc FileTree.IFileTreeFileItem.contentType}
      */
     get contentType() {
         return this._contentType;
@@ -58,7 +59,7 @@ export class FileItem {
      */
     constructor(path, hal) {
         /**
-         * {@inheritdoc FileTree.IFileTreeFileItem."type"}
+         * {@inheritDoc FileTree.IFileTreeFileItem."type"}
          */
         this.type = 'file';
         this._hal = hal;
@@ -75,6 +76,16 @@ export class FileItem {
     static create(path, hal) {
         return captureResult(() => new FileItem(path, hal));
     }
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.getIsMutable}
+     */
+    getIsMutable() {
+        if (isMutableAccessors(this._hal)) {
+            return this._hal.fileIsMutable(this.absolutePath);
+        }
+        /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+        return failWithDetail(`${this.absolutePath}: mutation not supported`, 'not-supported');
+    }
     getContents(converter) {
         return this._hal
             .getFileContents(this.absolutePath)
@@ -87,7 +98,7 @@ export class FileItem {
         });
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeFileItem.getRawContents}
+     * {@inheritDoc FileTree.IFileTreeFileItem.getRawContents}
      */
     getRawContents() {
         return this._hal.getFileContents(this.absolutePath);
@@ -99,15 +110,32 @@ export class FileItem {
     setContentType(contentType) {
         this._contentType = contentType;
     }
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.setContents}
+     */
+    setContents(json) {
+        return captureResult(() => JSON.stringify(json, null, 2)).onSuccess((contents) => this.setRawContents(contents).onSuccess(() => Success.with(json)));
+    }
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.setRawContents}
+     */
+    setRawContents(contents) {
+        if (isMutableAccessors(this._hal)) {
+            return this._hal.saveFileContents(this.absolutePath, contents);
+        }
+        /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+        return fail(`${this.absolutePath}: mutation not supported`);
+    }
     /**
      * 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(__filePath, __provided) {
+    static defaultInferContentType(filePath, provided) {
         return succeed(undefined);
     }
     /**
@@ -119,7 +147,7 @@ export class FileItem {
      * @remarks This default implementation always returns `Success` with `undefined`.
      * @public
      */
-    static defaultAcceptContentType(__filePath, provided) {
+    static defaultAcceptContentType(filePath, provided) {
         return succeed(provided);
     }
 }

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

@@ -19,5 +19,28 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-export {};
+/**
+ * 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 function isMutableAccessors(accessors) {
+    const mutable = accessors;
+    return typeof mutable.fileIsMutable === 'function' && typeof mutable.saveFileContents === '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
+ */
+export 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');
+}
 //# sourceMappingURL=fileTreeAccessors.js.map

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

@@ -0,0 +1,74 @@
+/*
+ * 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.
+ */
+/**
+ * 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
+ */
+export 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/dist/packlets/file-tree/fsTree.js

@@ -21,12 +21,13 @@
  */
 import path from 'path';
 import fs from 'fs';
-import { captureResult, succeed } from '@fgv/ts-utils';
+import { captureResult, fail, failWithDetail, succeed, succeedWithDetail } from '@fgv/ts-utils';
 import { DirectoryItem } from './directoryItem';
 import { FileItem } from './fileItem';
+import { isPathMutable } from './filterSpec';
 /**
- * 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 class FsFileTreeAccessors {
@@ -36,12 +37,14 @@ export class FsFileTreeAccessors {
      * @public
      */
     constructor(params) {
-        var _a;
+        var _a, _b;
         this.prefix = params === null || params === void 0 ? void 0 : params.prefix;
         this._inferContentType = (_a = params === null || params === void 0 ? void 0 : params.inferContentType) !== null && _a !== void 0 ? _a : FileItem.defaultInferContentType;
+        /* c8 ignore next 1 - defensive default when params is undefined */
+        this._mutable = (_b = params === null || params === void 0 ? void 0 : params.mutable) !== null && _b !== void 0 ? _b : false;
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
+     * {@inheritDoc FileTree.IFileTreeAccessors.resolveAbsolutePath}
      */
     resolveAbsolutePath(...paths) {
         if (this.prefix && !path.isAbsolute(paths[0])) {
@@ -50,25 +53,25 @@ export class FsFileTreeAccessors {
         return path.resolve(...paths);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getExtension}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getExtension}
      */
     getExtension(itemPath) {
         return path.extname(itemPath);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getBaseName}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getBaseName}
      */
     getBaseName(itemPath, suffix) {
         return path.basename(itemPath, suffix);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.joinPaths}
+     * {@inheritDoc FileTree.IFileTreeAccessors.joinPaths}
      */
     joinPaths(...paths) {
         return path.join(...paths);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getItem}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getItem}
      */
     getItem(itemPath) {
         return captureResult(() => {
@@ -84,13 +87,13 @@ export class FsFileTreeAccessors {
         });
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContents}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContents}
      */
     getFileContents(filePath) {
         return captureResult(() => fs.readFileSync(this.resolveAbsolutePath(filePath), 'utf8'));
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getFileContentType}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getFileContentType}
      */
     getFileContentType(filePath, provided) {
         if (provided !== undefined) {
@@ -100,7 +103,7 @@ export class FsFileTreeAccessors {
         return this._inferContentType(filePath);
     }
     /**
-     * {@inheritdoc FileTree.IFileTreeAccessors.getChildren}
+     * {@inheritDoc FileTree.IFileTreeAccessors.getChildren}
      */
     getChildren(dirPath) {
         return captureResult(() => {
@@ -118,5 +121,63 @@ export class FsFileTreeAccessors {
             return children;
         });
     }
+    /**
+     * {@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');
+        }
+        // Check file system permissions
+        try {
+            // Check if file exists
+            if (fs.existsSync(absolutePath)) {
+                fs.accessSync(absolutePath, fs.constants.W_OK);
+            }
+            else {
+                // Check if parent directory is writable
+                const parentDir = absolutePath.substring(0, absolutePath.lastIndexOf('/'));
+                if (parentDir && fs.existsSync(parentDir)) {
+                    fs.accessSync(parentDir, fs.constants.W_OK);
+                }
+            }
+            return succeedWithDetail(true, 'persistent');
+        }
+        catch (_a) {
+            return failWithDetail(`${absolutePath}: permission denied`, 'permission-denied');
+        }
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeAccessors.saveFileContents}
+     */
+    saveFileContents(path, contents) {
+        return this.fileIsMutable(path).asResult.onSuccess(() => {
+            const absolutePath = this.resolveAbsolutePath(path);
+            return captureResult(() => {
+                fs.writeFileSync(absolutePath, contents, 'utf8');
+                return contents;
+            });
+        });
+    }
+    /**
+     * {@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`);
+        }
+        return captureResult(() => {
+            fs.mkdirSync(absolutePath, { recursive: true });
+            return absolutePath;
+        });
+    }
 }
 //# sourceMappingURL=fsTree.js.map