@fgv/ts-json-base 5.0.2 → 5.1.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, isMutableFileItem } 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,104 @@ 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.IMutableFileTreeDirectoryItem.createChildFile}
+     */
+    createChildFile(name, contents) {
+        const hal = this._hal;
+        if (!isMutableAccessors(hal)) {
+            /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        const filePath = hal.joinPaths(this.absolutePath, name);
+        return hal.saveFileContents(filePath, contents).onSuccess(() => hal.getItem(filePath).onSuccess((item) => {
+            /* c8 ignore next 3 - defensive: verifies accessor returned correct item type after save */
+            if (!isMutableFileItem(item)) {
+                return fail(`${filePath}: expected mutable file but got ${item.type}`);
+            }
+            return succeed(item);
+        }));
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeDirectoryItem.createChildDirectory}
+     */
+    createChildDirectory(name) {
+        const hal = this._hal;
+        if (!isMutableAccessors(hal)) {
+            /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        const dirPath = hal.joinPaths(this.absolutePath, name);
+        return hal.createDirectory(dirPath).onSuccess(() => DirectoryItem.create(dirPath, hal));
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeDirectoryItem.deleteChild}
+     */
+    deleteChild(name, options) {
+        const hal = this._hal;
+        if (!isMutableAccessors(hal)) {
+            /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        const childPath = hal.joinPaths(this.absolutePath, name);
+        return hal.getItem(childPath).onSuccess((item) => {
+            if (item.type === 'file') {
+                return hal.deleteFile(childPath);
+            }
+            // Directory child
+            if (options === null || options === void 0 ? void 0 : options.recursive) {
+                return this._deleteRecursive(childPath);
+            }
+            return hal.deleteDirectory(childPath);
+        });
+    }
+    /**
+     * {@inheritDoc FileTree.IMutableFileTreeDirectoryItem.delete}
+     */
+    delete() {
+        const hal = this._hal;
+        if (!isMutableAccessors(hal)) {
+            /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        return hal.deleteDirectory(this.absolutePath);
+    }
+    /**
+     * Recursively deletes all children of a directory and then the directory itself.
+     * @param dirPath - The absolute path of the directory to delete.
+     * @returns `Success` with `true` if the directory was deleted, or `Failure` with an error message.
+     * @internal
+     */
+    _deleteRecursive(dirPath) {
+        const hal = this._hal;
+        /* c8 ignore next 3 - defensive: caller already verified mutable */
+        if (!isMutableAccessors(hal)) {
+            return fail(`${dirPath}: mutation not supported`);
+        }
+        return hal.getChildren(dirPath).onSuccess((children) => {
+            for (const child of children) {
+                if (child.type === 'file') {
+                    const result = hal.deleteFile(child.absolutePath);
+                    /* c8 ignore next 3 - defensive: error propagation during recursive delete */
+                    if (result.isFailure()) {
+                        return result;
+                    }
+                }
+                else {
+                    const result = this._deleteRecursive(child.absolutePath);
+                    /* c8 ignore next 3 - defensive: error propagation during recursive delete */
+                    if (result.isFailure()) {
+                        return result;
+                    }
+                }
+            }
+            return hal.deleteDirectory(dirPath);
+        });
+    }
 }
 //# 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,42 @@ 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`);
+    }
+    /**
+     * {@inheritDoc FileTree.IFileTreeFileItem.delete}
+     */
+    delete() {
+        if (!isMutableAccessors(this._hal)) {
+            /* c8 ignore next 2 - defensive: all current accessor implementations support mutation interface */
+            return fail(`${this.absolutePath}: mutation not supported`);
+        }
+        return this._hal.deleteFile(this.absolutePath);
+    }
     /**
      * 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 +157,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,63 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-export {};
+// ============================================================================
+// 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
+ */
+export 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
+ */
+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');
+}
+/**
+ * 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 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
+ */
+export 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/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