@fgv/ts-extras 5.1.0-0 → 5.1.0-10

package/dist/packlets/conversion/converters.js

@@ -60,8 +60,41 @@ export const isoDate = new Conversion.BaseConverter((from) => {
     else if (from instanceof Date) {
         return succeed(from);
     }
+    else if (from instanceof DateTime) {
+        if (from.isValid) {
+            return succeed(from.toJSDate());
+        }
+        return fail(`Invalid date: ${from.invalidExplanation}`);
+    }
     return fail(`Cannot convert ${JSON.stringify(from)} to Date`);
 });
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `DateTime` object.
+ * @public
+ */
+export const isoDateTime = new Conversion.BaseConverter((from) => {
+    if (typeof from === 'string') {
+        const dt = DateTime.fromISO(from);
+        if (dt.isValid) {
+            return succeed(dt);
+        }
+        return fail(`Invalid date: ${dt.invalidExplanation}`);
+    }
+    else if (typeof from === 'number') {
+        return succeed(DateTime.fromMillis(from));
+    }
+    else if (from instanceof Date) {
+        return succeed(DateTime.fromJSDate(from));
+    }
+    else if (from instanceof DateTime) {
+        if (from.isValid) {
+            return succeed(from);
+        }
+        return fail(`Invalid date: ${from.invalidExplanation}`);
+    }
+    return fail(`Cannot convert ${JSON.stringify(from)} to DateTime`);
+});
 /**
  * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks

package/dist/packlets/zip-file-tree/zipFileTreeAccessors.js

@@ -20,9 +20,11 @@
  * SOFTWARE.
  */
 import { unzipSync, unzip } from 'fflate';
-import { succeed, fail, captureResult, failWithDetail, Success } from '@fgv/ts-utils';
+import { succeed, fail, captureResult } from '@fgv/ts-utils';
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * ZIP files are read-only, so this item does not support mutation.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
  * @public
  */
 export class ZipFileItem {
@@ -58,30 +60,6 @@ export class ZipFileItem {
         this.extension = accessors.getExtension(zipFilePath);
         this.baseName = accessors.getBaseName(zipFilePath, this.extension);
     }
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     */
-    getIsMutable() {
-        return this._accessors.fileIsMutable(this.absolutePath);
-    }
-    /**
-     * Sets the contents of the file as parsed JSON.
-     * @param json - The JSON to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setContents(json) {
-        return captureResult(() => JSON.stringify(json, null, 2)).onSuccess((contents) => this.setRawContents(contents).onSuccess(() => Success.with(json)));
-    }
-    /**
-     * Sets the contents of the file as a string.
-     * @param contents - The string to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setRawContents(contents) {
-        return this.getIsMutable().asResult.onSuccess(() => 
-        /* c8 ignore next - unreachable: ZIP files are always read-only */
-        this._accessors.saveFileContents(this.absolutePath, contents));
-    }
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -142,7 +120,9 @@ export class ZipDirectoryItem {
     }
 }
 /**
- * File tree accessors for ZIP archives.
+ * Read-only file tree accessors for ZIP archives.
+ * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * to check before attempting mutations.
  * @public
  */
 export class ZipFileTreeAccessors {
@@ -262,23 +242,6 @@ export class ZipFileTreeAccessors {
             this._itemCache.set(absolutePath, item);
         });
     }
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     * @param path - The path of the file.
-     * @returns A `DetailedResult` indicating success or failure.
-     */
-    fileIsMutable(__path) {
-        return failWithDetail('ZIP files are read-only', 'not-supported');
-    }
-    /**
-     * Saves the contents of a file.
-     * @param path - The path of the file.
-     * @param contents - The contents of the file.
-     * @returns A `Result` indicating success or failure.
-     */
-    saveFileContents(__path, __contents) {
-        return failWithDetail('ZIP files are read-only', 'not-supported');
-    }
     /**
      * Resolves paths to an absolute path.
      */

package/dist/ts-extras.d.ts

@@ -1,6 +1,6 @@
 import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
-import { DetailedResult } from '@fgv/ts-utils';
+import { DateTime } from 'luxon';
 import { FileTree } from '@fgv/ts-json-base';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
 import { JsonValue } from '@fgv/ts-json-base';
@@ -211,7 +211,8 @@ declare namespace Converters {
         extendedArrayOf,
         rangeTypeOf,
         rangeOf,
-        isoDate
+        isoDate,
+        isoDateTime
     }
 }
 export { Converters }
@@ -1400,6 +1401,13 @@ declare function isKeyStoreFile(json: unknown): boolean;
  */
 declare const isoDate: Converter<Date, unknown>;
 
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `DateTime` object.
+ * @public
+ */
+declare const isoDateTime: Converter<DateTime, unknown>;
+
 /**
  * Represents a variable reference extracted from a Mustache template.
  * @public
@@ -2338,6 +2346,8 @@ declare class ZipDirectoryItem<TCT extends string = string> implements FileTree.
 
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * ZIP files are read-only, so this item does not support mutation.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
  * @public
  */
 declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
@@ -2388,22 +2398,6 @@ declare class ZipFileItem<TCT extends string = string> implements FileTree.IFile
      * @param accessors - The ZIP file tree accessors.
      */
     constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors<TCT>);
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     */
-    getIsMutable(): DetailedResult<boolean, FileTree.SaveDetail>;
-    /**
-     * Sets the contents of the file as parsed JSON.
-     * @param json - The JSON to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setContents(json: JsonValue): Result<JsonValue>;
-    /**
-     * Sets the contents of the file as a string.
-     * @param contents - The string to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setRawContents(contents: string): Result<string>;
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -2434,10 +2428,12 @@ declare namespace ZipFileTree {
 export { ZipFileTree }
 
 /**
- * File tree accessors for ZIP archives.
+ * Read-only file tree accessors for ZIP archives.
+ * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * to check before attempting mutations.
  * @public
  */
-declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IMutableFileTreeAccessors<TCT> {
+declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
     /**
      * The unzipped file data.
      */
@@ -2509,19 +2505,6 @@ declare class ZipFileTreeAccessors<TCT extends string = string> implements FileT
      * Builds the cache of all items in the ZIP archive.
      */
     private _buildItemCache;
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     * @param path - The path of the file.
-     * @returns A `DetailedResult` indicating success or failure.
-     */
-    fileIsMutable(__path: string): DetailedResult<boolean, FileTree.SaveDetail>;
-    /**
-     * Saves the contents of a file.
-     * @param path - The path of the file.
-     * @param contents - The contents of the file.
-     * @returns A `Result` indicating success or failure.
-     */
-    saveFileContents(__path: string, __contents: string): Result<string>;
     /**
      * Resolves paths to an absolute path.
      */

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.57.6"
+      "packageVersion": "7.57.7"
     }
   ]
 }

package/lib/packlets/conversion/converters.d.ts

@@ -1,4 +1,5 @@
 import { Conversion, Converter, Result } from '@fgv/ts-utils';
+import { DateTime } from 'luxon';
 import { ExtendedArray, RangeOf, RangeOfProperties } from '../experimental';
 /**
  * Helper function to create a `StringConverter` which converts
@@ -17,6 +18,12 @@ export declare function templateString(defaultContext?: unknown): Conversion.Str
  * @public
  */
 export declare const isoDate: Converter<Date, unknown>;
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `DateTime` object.
+ * @public
+ */
+export declare const isoDateTime: Converter<DateTime, unknown>;
 /**
  * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks

package/lib/packlets/conversion/converters.js

@@ -24,7 +24,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isoDate = void 0;
+exports.isoDateTime = exports.isoDate = void 0;
 exports.templateString = templateString;
 exports.extendedArrayOf = extendedArrayOf;
 exports.rangeTypeOf = rangeTypeOf;
@@ -70,8 +70,41 @@ exports.isoDate = new ts_utils_1.Conversion.BaseConverter((from) => {
     else if (from instanceof Date) {
         return (0, ts_utils_1.succeed)(from);
     }
+    else if (from instanceof luxon_1.DateTime) {
+        if (from.isValid) {
+            return (0, ts_utils_1.succeed)(from.toJSDate());
+        }
+        return (0, ts_utils_1.fail)(`Invalid date: ${from.invalidExplanation}`);
+    }
     return (0, ts_utils_1.fail)(`Cannot convert ${JSON.stringify(from)} to Date`);
 });
+/**
+ * A `Converter` which converts an iso formatted string, a number or a `Date` object to
+ * a `DateTime` object.
+ * @public
+ */
+exports.isoDateTime = new ts_utils_1.Conversion.BaseConverter((from) => {
+    if (typeof from === 'string') {
+        const dt = luxon_1.DateTime.fromISO(from);
+        if (dt.isValid) {
+            return (0, ts_utils_1.succeed)(dt);
+        }
+        return (0, ts_utils_1.fail)(`Invalid date: ${dt.invalidExplanation}`);
+    }
+    else if (typeof from === 'number') {
+        return (0, ts_utils_1.succeed)(luxon_1.DateTime.fromMillis(from));
+    }
+    else if (from instanceof Date) {
+        return (0, ts_utils_1.succeed)(luxon_1.DateTime.fromJSDate(from));
+    }
+    else if (from instanceof luxon_1.DateTime) {
+        if (from.isValid) {
+            return (0, ts_utils_1.succeed)(from);
+        }
+        return (0, ts_utils_1.fail)(`Invalid date: ${from.invalidExplanation}`);
+    }
+    return (0, ts_utils_1.fail)(`Cannot convert ${JSON.stringify(from)} to DateTime`);
+});
 /**
  * A helper function to create a `Converter` which converts `unknown` to {@link Experimental.ExtendedArray | ExtendedArray<T>}.
  * @remarks

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.d.ts

@@ -1,7 +1,9 @@
-import { Result, Converter, Validator, DetailedResult } from '@fgv/ts-utils';
+import { Result, Converter, Validator } from '@fgv/ts-utils';
 import { FileTree, JsonValue } from '@fgv/ts-json-base';
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * ZIP files are read-only, so this item does not support mutation.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
  * @public
  */
 export declare class ZipFileItem<TCT extends string = string> implements FileTree.IFileTreeFileItem<TCT> {
@@ -52,22 +54,6 @@ export declare class ZipFileItem<TCT extends string = string> implements FileTre
      * @param accessors - The ZIP file tree accessors.
      */
     constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors<TCT>);
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     */
-    getIsMutable(): DetailedResult<boolean, FileTree.SaveDetail>;
-    /**
-     * Sets the contents of the file as parsed JSON.
-     * @param json - The JSON to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setContents(json: JsonValue): Result<JsonValue>;
-    /**
-     * Sets the contents of the file as a string.
-     * @param contents - The string to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setRawContents(contents: string): Result<string>;
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -116,10 +102,12 @@ export declare class ZipDirectoryItem<TCT extends string = string> implements Fi
     getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem<TCT>>>;
 }
 /**
- * File tree accessors for ZIP archives.
+ * Read-only file tree accessors for ZIP archives.
+ * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * to check before attempting mutations.
  * @public
  */
-export declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IMutableFileTreeAccessors<TCT> {
+export declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
     /**
      * The unzipped file data.
      */
@@ -191,19 +179,6 @@ export declare class ZipFileTreeAccessors<TCT extends string = string> implement
      * Builds the cache of all items in the ZIP archive.
      */
     private _buildItemCache;
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     * @param path - The path of the file.
-     * @returns A `DetailedResult` indicating success or failure.
-     */
-    fileIsMutable(__path: string): DetailedResult<boolean, FileTree.SaveDetail>;
-    /**
-     * Saves the contents of a file.
-     * @param path - The path of the file.
-     * @param contents - The contents of the file.
-     * @returns A `Result` indicating success or failure.
-     */
-    saveFileContents(__path: string, __contents: string): Result<string>;
     /**
      * Resolves paths to an absolute path.
      */

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.js

@@ -26,6 +26,8 @@ const fflate_1 = require("fflate");
 const ts_utils_1 = require("@fgv/ts-utils");
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * ZIP files are read-only, so this item does not support mutation.
+ * Use {@link FileTree.isMutableFileItem | isMutableFileItem} to check before attempting mutations.
  * @public
  */
 class ZipFileItem {
@@ -61,30 +63,6 @@ class ZipFileItem {
         this.extension = accessors.getExtension(zipFilePath);
         this.baseName = accessors.getBaseName(zipFilePath, this.extension);
     }
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     */
-    getIsMutable() {
-        return this._accessors.fileIsMutable(this.absolutePath);
-    }
-    /**
-     * Sets the contents of the file as parsed JSON.
-     * @param json - The JSON to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setContents(json) {
-        return (0, ts_utils_1.captureResult)(() => JSON.stringify(json, null, 2)).onSuccess((contents) => this.setRawContents(contents).onSuccess(() => ts_utils_1.Success.with(json)));
-    }
-    /**
-     * Sets the contents of the file as a string.
-     * @param contents - The string to set as the contents of the file.
-     * @returns A Result indicating success or failure.
-     */
-    setRawContents(contents) {
-        return this.getIsMutable().asResult.onSuccess(() => 
-        /* c8 ignore next - unreachable: ZIP files are always read-only */
-        this._accessors.saveFileContents(this.absolutePath, contents));
-    }
     /**
      * Sets the content type of the file.
      * @param contentType - The content type of the file.
@@ -147,7 +125,9 @@ class ZipDirectoryItem {
 }
 exports.ZipDirectoryItem = ZipDirectoryItem;
 /**
- * File tree accessors for ZIP archives.
+ * Read-only file tree accessors for ZIP archives.
+ * ZIP archives are read-only by design — use {@link FileTree.isMutableAccessors | isMutableAccessors}
+ * to check before attempting mutations.
  * @public
  */
 class ZipFileTreeAccessors {
@@ -267,23 +247,6 @@ class ZipFileTreeAccessors {
             this._itemCache.set(absolutePath, item);
         });
     }
-    /**
-     * Returns a boolean indicating whether this file can be saved.
-     * @param path - The path of the file.
-     * @returns A `DetailedResult` indicating success or failure.
-     */
-    fileIsMutable(__path) {
-        return (0, ts_utils_1.failWithDetail)('ZIP files are read-only', 'not-supported');
-    }
-    /**
-     * Saves the contents of a file.
-     * @param path - The path of the file.
-     * @param contents - The contents of the file.
-     * @returns A `Result` indicating success or failure.
-     */
-    saveFileContents(__path, __contents) {
-        return (0, ts_utils_1.failWithDetail)('ZIP files are read-only', 'not-supported');
-    }
     /**
      * Resolves paths to an absolute path.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-0",
+  "version": "5.1.0-10",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -77,8 +77,8 @@
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
     "jest-snapshot": "~29.7.0",
-    "@rushstack/heft": "1.2.6",
-    "@rushstack/heft-node-rig": "2.11.26",
+    "@rushstack/heft": "1.2.7",
+    "@rushstack/heft-node-rig": "2.11.27",
     "@rushstack/eslint-config": "4.6.4",
     "@types/heft-jest": "1.0.6",
     "@rushstack/heft-jest-plugin": "1.2.6",
@@ -86,9 +86,10 @@
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/ts-utils-jest": "5.1.0-0",
-    "@fgv/heft-dual-rig": "0.1.0",
-    "@fgv/ts-utils": "5.1.0-0"
+    "@fgv/heft-dual-rig": "5.1.0-10",
+    "@fgv/ts-utils-jest": "5.1.0-10",
+    "@fgv/typedoc-compact-theme": "5.1.0-10",
+    "@fgv/ts-utils": "5.1.0-10"
   },
   "dependencies": {
     "luxon": "^3.7.2",
@@ -96,10 +97,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-0"
+    "@fgv/ts-json-base": "5.1.0-10"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-0"
+    "@fgv/ts-utils": "5.1.0-10"
   },
   "repository": {
     "type": "git",