@fgv/ts-extras 5.0.0-0 → 5.0.0-3

package/README.md

@@ -1,17 +1,23 @@
 <div align="center">
-  <h1>ts-utils</h1>
-  Assorted Typescript Utilities
+  <h1>ts-extras</h1>
+  Assorted TypeScript Utilities
 </div>
 
 <hr/>
 
 ## Summary
 
-Assorted less-developed or more specialized odds-and-ends borrowed from one project or another - much less polished and more likely change or disappear:
-* ExtendedArray\<T\> - adds a few useful operations to the built-in Array
-* Formattable\<T\> - simple helpers to create mustache wrappers for objects and make them easily printable
-* Logger - A very basic logger suitable for hobby projects
-* RangeOf\<T\> - Generic open or closed ranges of orderable items (numbers, dates, etc)
+Assorted less-developed or more specialized utilities borrowed from various projects - much less polished and more likely to change or disappear:
+
+* **ExtendedArray\<T\>** - adds useful operations to the built-in Array
+* **Formattable\<T\>** - simple helpers to create mustache wrappers for objects and make them easily printable  
+* **Logger** - A very basic logger suitable for hobby projects
+* **RangeOf\<T\>** - Generic open or closed ranges of orderable items (numbers, dates, etc)
+* **ZIP FileTree** - FileTree implementation for reading from ZIP archives (Node.js)
+* **Converters** - Type-safe data conversion utilities
+* **CSV Helpers** - Utilities for CSV processing
+* **Hash Utilities** - MD5 normalization and hashing utilities
+* **RecordJar Helpers** - Utilities for record collection management
 
 ---
 
@@ -24,6 +30,9 @@ Assorted less-developed or more specialized odds-and-ends borrowed from one proj
   - [Formattable\<T\>](#formattablet)
   - [Logger](#logger)
   - [RangeOf\<T\>](#rangeoft)
+  - [ZIP FileTree](#zip-filetree)
+  - [Converters](#converters)
+  - [Other Utilities](#other-utilities)
 
 ## Installation
 
@@ -37,12 +46,65 @@ Extracted API documentation is [here](./docs/ts-extras.md).
 
 ## Overview
 
+This package provides various utility functions and classes that are commonly needed across TypeScript projects, particularly those working with data processing, file handling, and type-safe operations.
+
 ## API
 
 ### ExtendedArray\<T\>
 
+Extended array functionality with additional operations beyond the built-in Array methods.
+
 ### Formattable\<T\>
 
+Simple helpers for creating mustache-style wrappers around objects to make them easily printable and templatable.
+
 ### Logger
 
+A basic logging utility suitable for development and hobby projects.
+
 ### RangeOf\<T\>
+
+Generic implementation for representing open or closed ranges of orderable items like numbers, dates, or other comparable values.
+
+### ZIP FileTree
+
+**Node.js-compatible** FileTree implementation for reading from ZIP archives using AdmZip:
+
+```typescript
+import { ZipFileTree } from '@fgv/ts-extras';
+import { FileTree } from '@fgv/ts-utils';
+
+// Create ZIP FileTree from buffer
+const zipAccessors = ZipFileTree.ZipFileTreeAccessors.fromBuffer(zipBuffer);
+const fileTree = FileTree.FileTree.create(zipAccessors.value);
+
+// Access files and directories
+const file = fileTree.value.getFile('/path/to/file.json');
+const contents = file.value.getContents(); // Parsed JSON
+const rawContents = file.value.getRawContents(); // Raw string
+```
+
+**Note**: This implementation uses Node.js-specific dependencies (AdmZip, Buffer). For browser environments, see the browser-specific implementations in individual projects.
+
+### Converters  
+
+Type-safe data conversion utilities for transforming between different data formats while maintaining type safety.
+
+### Other Utilities
+
+- **CSV Helpers**: Utilities for processing CSV data
+- **Hash Utilities**: MD5 normalization and hashing functions
+- **RecordJar Helpers**: Utilities for managing record collections and data structures
+
+## Dependencies
+
+This package depends on:
+- `@fgv/ts-utils` - Core utilities and Result pattern
+- `adm-zip` - ZIP file processing (Node.js only)
+- Various other utility packages for specific functionality
+
+## Platform Notes
+
+- **ZIP FileTree**: Node.js only (uses AdmZip and Buffer)  
+- **Other utilities**: Cross-platform compatible
+- **Browser usage**: Most utilities work in browsers, but ZIP functionality requires browser-specific implementations

package/dist/ts-extras.d.ts

@@ -1,7 +1,9 @@
 import { Conversion } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-utils';
 import { Hash as Hash_2 } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
+import { Validator } from '@fgv/ts-utils';
 
 declare namespace Converters {
     export {
@@ -422,4 +424,172 @@ export { RecordJar }
  */
 declare function templateString(defaultContext?: unknown): Conversion.StringConverter<string, unknown>;
 
+/**
+ * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
+ * @public
+ */
+declare class ZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a directory.
+     */
+    readonly type: 'directory';
+    /**
+     * The absolute path of the directory within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the directory
+     */
+    readonly name: string;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipDirectoryItem.
+     * @param directoryPath - The path of the directory within the ZIP.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(directoryPath: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the children of the directory.
+     */
+    getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+}
+
+/**
+ * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * @public
+ */
+declare class ZipFileItem implements FileTree.IFileTreeFileItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a file.
+     */
+    readonly type: 'file';
+    /**
+     * The absolute path of the file within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the file
+     */
+    readonly name: string;
+    /**
+     * The base name of the file (without extension)
+     */
+    readonly baseName: string;
+    /**
+     * The extension of the file
+     */
+    readonly extension: string;
+    /**
+     * The pre-loaded contents of the file.
+     */
+    private readonly _contents;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipFileItem.
+     * @param zipFilePath - The path of the file within the ZIP.
+     * @param contents - The pre-loaded contents of the file.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the contents of the file as parsed JSON.
+     */
+    getContents(): Result<unknown>;
+    getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
+    /**
+     * Gets the raw contents of the file as a string.
+     */
+    getRawContents(): Result<string>;
+}
+
+declare namespace ZipFileTree {
+    export {
+        ZipFileTreeAccessors,
+        ZipFileItem,
+        ZipDirectoryItem
+    }
+}
+export { ZipFileTree }
+
+/**
+ * File tree accessors for ZIP archives.
+ * @public
+ */
+declare class ZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
+    /**
+     * The AdmZip instance containing the archive.
+     */
+    private readonly _zip;
+    /**
+     * Optional prefix to prepend to paths.
+     */
+    private readonly _prefix;
+    /**
+     * Cache of all items in the ZIP for efficient lookups.
+     */
+    private readonly _itemCache;
+    /**
+     * Constructor for ZipFileTreeAccessors.
+     * @param zip - The AdmZip instance.
+     * @param prefix - Optional prefix to prepend to paths.
+     */
+    private constructor();
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer.
+     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromBuffer(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Result<ZipFileTreeAccessors>;
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).
+     * @param file - The File object containing ZIP data.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromFile(file: File, prefix?: string): Promise<Result<ZipFileTreeAccessors>>;
+    /**
+     * Builds the cache of all items in the ZIP archive.
+     */
+    private _buildItemCache;
+    /**
+     * Resolves paths to an absolute path.
+     */
+    resolveAbsolutePath(...paths: string[]): string;
+    /**
+     * Gets the extension of a path.
+     */
+    getExtension(path: string): string;
+    /**
+     * Gets the base name of a path.
+     */
+    getBaseName(path: string, suffix?: string): string;
+    /**
+     * Joins paths together.
+     */
+    joinPaths(...paths: string[]): string;
+    /**
+     * Gets an item from the file tree.
+     */
+    getItem(path: string): Result<FileTree.FileTreeItem>;
+    /**
+     * Gets the contents of a file in the file tree.
+     */
+    getFileContents(path: string): Result<string>;
+    /**
+     * Gets the children of a directory in the file tree.
+     */
+    getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+    /**
+     * Checks if childPath is a direct child of parentPath.
+     */
+    private _isDirectChild;
+}
+
 export { }

package/lib/index.d.ts

@@ -2,6 +2,7 @@ import * as Csv from './packlets/csv';
 import * as Experimental from './packlets/experimental';
 import * as Hash from './packlets/hash';
 import * as RecordJar from './packlets/record-jar';
+import * as ZipFileTree from './packlets/zip-file-tree';
 import { Converters } from './packlets/conversion';
-export { Converters, Csv, Experimental, Hash, RecordJar };
+export { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,GAAG,MAAM,gBAAgB,CAAC;AACtC,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,IAAI,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,WAAW,MAAM,0BAA0B,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC"}

package/lib/index.js

@@ -54,7 +54,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecordJar = exports.Hash = exports.Experimental = exports.Csv = exports.Converters = void 0;
+exports.ZipFileTree = exports.RecordJar = exports.Hash = exports.Experimental = exports.Csv = exports.Converters = void 0;
 const Csv = __importStar(require("./packlets/csv"));
 exports.Csv = Csv;
 const Experimental = __importStar(require("./packlets/experimental"));
@@ -63,6 +63,8 @@ const Hash = __importStar(require("./packlets/hash"));
 exports.Hash = Hash;
 const RecordJar = __importStar(require("./packlets/record-jar"));
 exports.RecordJar = RecordJar;
+const ZipFileTree = __importStar(require("./packlets/zip-file-tree"));
+exports.ZipFileTree = ZipFileTree;
 const conversion_1 = require("./packlets/conversion");
 Object.defineProperty(exports, "Converters", { enumerable: true, get: function () { return conversion_1.Converters; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,oDAAsC;AAOjB,kBAAG;AANxB,sEAAwD;AAM9B,oCAAY;AALtC,sDAAwC;AAKA,oBAAI;AAJ5C,iEAAmD;AAIL,8BAAS;AAFvD,sDAAmD;AAE1C,2FAFA,uBAAU,OAEA","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Csv from './packlets/csv';\nimport * as Experimental from './packlets/experimental';\nimport * as Hash from './packlets/hash';\nimport * as RecordJar from './packlets/record-jar';\n\nimport { Converters } from './packlets/conversion';\n\nexport { Converters, Csv, Experimental, Hash, RecordJar };\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,oDAAsC;AAQjB,kBAAG;AAPxB,sEAAwD;AAO9B,oCAAY;AANtC,sDAAwC;AAMA,oBAAI;AAL5C,iEAAmD;AAKL,8BAAS;AAJvD,sEAAwD;AAIC,kCAAW;AAFpE,sDAAmD;AAE1C,2FAFA,uBAAU,OAEA","sourcesContent":["/*\n * Copyright (c) 2020 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport * as Csv from './packlets/csv';\nimport * as Experimental from './packlets/experimental';\nimport * as Hash from './packlets/hash';\nimport * as RecordJar from './packlets/record-jar';\nimport * as ZipFileTree from './packlets/zip-file-tree';\n\nimport { Converters } from './packlets/conversion';\n\nexport { Converters, Csv, Experimental, Hash, RecordJar, ZipFileTree };\n"]}

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

@@ -0,0 +1,11 @@
+/**
+ * ZIP-based FileTree implementation for ts-extras.
+ *
+ * This packlet provides a FileTree accessor implementation that can read from ZIP archives,
+ * making it useful for browser environments where files need to be bundled and transferred
+ * as a single archive.
+ *
+ * @packageDocumentation
+ */
+export { ZipFileTreeAccessors, ZipFileItem, ZipDirectoryItem } from './zipFileTreeAccessors';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/zip-file-tree/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/packlets/zip-file-tree/index.ts"],"names":[],"mappings":"AAsBA;;;;;;;;GAQG;AAEH,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

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

@@ -0,0 +1,38 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipDirectoryItem = exports.ZipFileItem = exports.ZipFileTreeAccessors = void 0;
+/**
+ * ZIP-based FileTree implementation for ts-extras.
+ *
+ * This packlet provides a FileTree accessor implementation that can read from ZIP archives,
+ * making it useful for browser environments where files need to be bundled and transferred
+ * as a single archive.
+ *
+ * @packageDocumentation
+ */
+var zipFileTreeAccessors_1 = require("./zipFileTreeAccessors");
+Object.defineProperty(exports, "ZipFileTreeAccessors", { enumerable: true, get: function () { return zipFileTreeAccessors_1.ZipFileTreeAccessors; } });
+Object.defineProperty(exports, "ZipFileItem", { enumerable: true, get: function () { return zipFileTreeAccessors_1.ZipFileItem; } });
+Object.defineProperty(exports, "ZipDirectoryItem", { enumerable: true, get: function () { return zipFileTreeAccessors_1.ZipDirectoryItem; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/zip-file-tree/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/zip-file-tree/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AAEH;;;;;;;;GAQG;AAEH,+DAA6F;AAApF,4HAAA,oBAAoB,OAAA;AAAE,mHAAA,WAAW,OAAA;AAAE,wHAAA,gBAAgB,OAAA","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * ZIP-based FileTree implementation for ts-extras.\n *\n * This packlet provides a FileTree accessor implementation that can read from ZIP archives,\n * making it useful for browser environments where files need to be bundled and transferred\n * as a single archive.\n *\n * @packageDocumentation\n */\n\nexport { ZipFileTreeAccessors, ZipFileItem, ZipDirectoryItem } from './zipFileTreeAccessors';\n"]}

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

@@ -0,0 +1,158 @@
+import { Result, Converter, Validator, FileTree } from '@fgv/ts-utils';
+/**
+ * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * @public
+ */
+export declare class ZipFileItem implements FileTree.IFileTreeFileItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a file.
+     */
+    readonly type: 'file';
+    /**
+     * The absolute path of the file within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the file
+     */
+    readonly name: string;
+    /**
+     * The base name of the file (without extension)
+     */
+    readonly baseName: string;
+    /**
+     * The extension of the file
+     */
+    readonly extension: string;
+    /**
+     * The pre-loaded contents of the file.
+     */
+    private readonly _contents;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipFileItem.
+     * @param zipFilePath - The path of the file within the ZIP.
+     * @param contents - The pre-loaded contents of the file.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the contents of the file as parsed JSON.
+     */
+    getContents(): Result<unknown>;
+    getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;
+    /**
+     * Gets the raw contents of the file as a string.
+     */
+    getRawContents(): Result<string>;
+}
+/**
+ * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
+ * @public
+ */
+export declare class ZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {
+    /**
+     * Indicates that this `FileTree.FileTreeItem` is a directory.
+     */
+    readonly type: 'directory';
+    /**
+     * The absolute path of the directory within the ZIP archive.
+     */
+    readonly absolutePath: string;
+    /**
+     * The name of the directory
+     */
+    readonly name: string;
+    /**
+     * The ZIP file tree accessors that created this item.
+     */
+    private readonly _accessors;
+    /**
+     * Constructor for ZipDirectoryItem.
+     * @param directoryPath - The path of the directory within the ZIP.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(directoryPath: string, accessors: ZipFileTreeAccessors);
+    /**
+     * Gets the children of the directory.
+     */
+    getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+}
+/**
+ * File tree accessors for ZIP archives.
+ * @public
+ */
+export declare class ZipFileTreeAccessors implements FileTree.IFileTreeAccessors {
+    /**
+     * The AdmZip instance containing the archive.
+     */
+    private readonly _zip;
+    /**
+     * Optional prefix to prepend to paths.
+     */
+    private readonly _prefix;
+    /**
+     * Cache of all items in the ZIP for efficient lookups.
+     */
+    private readonly _itemCache;
+    /**
+     * Constructor for ZipFileTreeAccessors.
+     * @param zip - The AdmZip instance.
+     * @param prefix - Optional prefix to prepend to paths.
+     */
+    private constructor();
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer.
+     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromBuffer(zipBuffer: ArrayBuffer | Uint8Array, prefix?: string): Result<ZipFileTreeAccessors>;
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).
+     * @param file - The File object containing ZIP data.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromFile(file: File, prefix?: string): Promise<Result<ZipFileTreeAccessors>>;
+    /**
+     * Builds the cache of all items in the ZIP archive.
+     */
+    private _buildItemCache;
+    /**
+     * Resolves paths to an absolute path.
+     */
+    resolveAbsolutePath(...paths: string[]): string;
+    /**
+     * Gets the extension of a path.
+     */
+    getExtension(path: string): string;
+    /**
+     * Gets the base name of a path.
+     */
+    getBaseName(path: string, suffix?: string): string;
+    /**
+     * Joins paths together.
+     */
+    joinPaths(...paths: string[]): string;
+    /**
+     * Gets an item from the file tree.
+     */
+    getItem(path: string): Result<FileTree.FileTreeItem>;
+    /**
+     * Gets the contents of a file in the file tree.
+     */
+    getFileContents(path: string): Result<string>;
+    /**
+     * Gets the children of a directory in the file tree.
+     */
+    getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>>;
+    /**
+     * Checks if childPath is a direct child of parentPath.
+     */
+    private _isDirectChild;
+}
+//# sourceMappingURL=zipFileTreeAccessors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"zipFileTreeAccessors.d.ts","sourceRoot":"","sources":["../../../src/packlets/zip-file-tree/zipFileTreeAccessors.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,293 @@
+"use strict";
+/*
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipFileTreeAccessors = exports.ZipDirectoryItem = exports.ZipFileItem = void 0;
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
+ * @public
+ */
+class ZipFileItem {
+    /**
+     * Constructor for ZipFileItem.
+     * @param zipFilePath - The path of the file within the ZIP.
+     * @param contents - The pre-loaded contents of the file.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(zipFilePath, contents, accessors) {
+        /**
+         * Indicates that this `FileTree.FileTreeItem` is a file.
+         */
+        this.type = 'file';
+        this._contents = contents;
+        this._accessors = accessors;
+        this.absolutePath = '/' + zipFilePath;
+        this.name = accessors.getBaseName(zipFilePath);
+        this.extension = accessors.getExtension(zipFilePath);
+        this.baseName = accessors.getBaseName(zipFilePath, this.extension);
+    }
+    getContents(converter) {
+        return this.getRawContents()
+            .onSuccess((contents) => {
+            return (0, ts_utils_1.captureResult)(() => {
+                const parsed = JSON.parse(contents);
+                if (converter) {
+                    if ('convert' in converter) {
+                        return converter.convert(parsed);
+                    } /* c8 ignore next 3 - validator branch functionally tested but coverage tool misses due to interface complexity */
+                    else {
+                        return converter.validate(parsed);
+                    }
+                }
+                return (0, ts_utils_1.succeed)(parsed);
+            }).onFailure(() => {
+                return (0, ts_utils_1.fail)(`Failed to parse JSON from file: ${this.absolutePath}`);
+            });
+        })
+            .onFailure((error) => {
+            return (0, ts_utils_1.fail)(`Failed to get contents from file: ${error}`);
+        });
+    }
+    /**
+     * Gets the raw contents of the file as a string.
+     */
+    getRawContents() {
+        return (0, ts_utils_1.succeed)(this._contents);
+    }
+}
+exports.ZipFileItem = ZipFileItem;
+/**
+ * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.
+ * @public
+ */
+class ZipDirectoryItem {
+    /**
+     * Constructor for ZipDirectoryItem.
+     * @param directoryPath - The path of the directory within the ZIP.
+     * @param accessors - The ZIP file tree accessors.
+     */
+    constructor(directoryPath, accessors) {
+        /**
+         * Indicates that this `FileTree.FileTreeItem` is a directory.
+         */
+        this.type = 'directory';
+        this._accessors = accessors;
+        this.absolutePath = '/' + directoryPath.replace(/\/$/, ''); // Normalize path
+        this.name = accessors.getBaseName(directoryPath);
+    }
+    /**
+     * Gets the children of the directory.
+     */
+    getChildren() {
+        return this._accessors.getChildren(this.absolutePath);
+    }
+}
+exports.ZipDirectoryItem = ZipDirectoryItem;
+/**
+ * File tree accessors for ZIP archives.
+ * @public
+ */
+class ZipFileTreeAccessors {
+    /**
+     * Constructor for ZipFileTreeAccessors.
+     * @param zip - The AdmZip instance.
+     * @param prefix - Optional prefix to prepend to paths.
+     */
+    constructor(zip, prefix) {
+        /**
+         * Cache of all items in the ZIP for efficient lookups.
+         */
+        this._itemCache = new Map();
+        this._zip = zip;
+        this._prefix = prefix || '';
+        this._buildItemCache();
+    }
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer.
+     * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static fromBuffer(zipBuffer, prefix) {
+        try {
+            const buffer = Buffer.from(zipBuffer);
+            const zip = new adm_zip_1.default(buffer);
+            return (0, ts_utils_1.succeed)(new ZipFileTreeAccessors(zip, prefix));
+        }
+        catch (error) {
+            /* c8 ignore next 1 - defensive coding: AdmZip always throws Error objects in practice */
+            return (0, ts_utils_1.fail)(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).
+     * @param file - The File object containing ZIP data.
+     * @param prefix - Optional prefix to prepend to paths.
+     * @returns Result containing the ZipFileTreeAccessors instance.
+     */
+    static async fromFile(file, prefix) {
+        try {
+            const arrayBuffer = await file.arrayBuffer();
+            return ZipFileTreeAccessors.fromBuffer(new Uint8Array(arrayBuffer), prefix);
+        }
+        catch (error) {
+            return (0, ts_utils_1.fail)(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Builds the cache of all items in the ZIP archive.
+     */
+    _buildItemCache() {
+        const directories = new Set();
+        const entries = this._zip.getEntries();
+        // First pass: collect all directories from file paths
+        entries.forEach((entry) => {
+            if (!entry.isDirectory) {
+                // Extract directory path from file path
+                const pathParts = entry.entryName.split('/');
+                for (let i = 1; i < pathParts.length; i++) {
+                    const dirPath = pathParts.slice(0, i).join('/');
+                    directories.add(dirPath);
+                }
+            }
+            else {
+                // Also add explicit directories
+                const dirPath = entry.entryName.replace(/\/$/, ''); // Remove trailing slash
+                if (dirPath) {
+                    directories.add(dirPath);
+                }
+            }
+        });
+        // Add directory items to cache
+        directories.forEach((dirPath) => {
+            const absolutePath = this.resolveAbsolutePath(dirPath);
+            const item = new ZipDirectoryItem(dirPath, this);
+            this._itemCache.set(absolutePath, item);
+        });
+        // Add file items to cache
+        entries.forEach((entry) => {
+            if (!entry.isDirectory) {
+                const absolutePath = this.resolveAbsolutePath(entry.entryName);
+                const contents = entry.getData().toString('utf8');
+                const item = new ZipFileItem(entry.entryName, contents, this);
+                this._itemCache.set(absolutePath, item);
+            }
+        });
+    }
+    /**
+     * Resolves paths to an absolute path.
+     */
+    resolveAbsolutePath(...paths) {
+        const joinedPath = this.joinPaths(...paths);
+        const prefixed = this._prefix ? this.joinPaths(this._prefix, joinedPath) : joinedPath;
+        return prefixed.startsWith('/') ? prefixed : '/' + prefixed;
+    }
+    /**
+     * Gets the extension of a path.
+     */
+    getExtension(path) {
+        const name = this.getBaseName(path);
+        const lastDotIndex = name.lastIndexOf('.');
+        return lastDotIndex >= 0 ? name.substring(lastDotIndex) : '';
+    }
+    /**
+     * Gets the base name of a path.
+     */
+    getBaseName(path, suffix) {
+        const normalizedPath = path.replace(/\/$/, ''); // Remove trailing slash
+        const parts = normalizedPath.split('/');
+        let baseName = parts[parts.length - 1] || '';
+        if (suffix && baseName.endsWith(suffix)) {
+            baseName = baseName.substring(0, baseName.length - suffix.length);
+        }
+        return baseName;
+    }
+    /**
+     * Joins paths together.
+     */
+    joinPaths(...paths) {
+        return paths
+            .filter((p) => p && p.length > 0)
+            .map((p) => p.replace(/^\/+|\/+$/g, '')) // Remove leading/trailing slashes
+            .join('/')
+            .replace(/\/+/g, '/'); // Normalize multiple slashes
+    }
+    /**
+     * Gets an item from the file tree.
+     */
+    getItem(path) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        const item = this._itemCache.get(absolutePath);
+        if (item) {
+            return (0, ts_utils_1.succeed)(item);
+        }
+        return (0, ts_utils_1.fail)(`Item not found: ${absolutePath}`);
+    }
+    /**
+     * Gets the contents of a file in the file tree.
+     */
+    getFileContents(path) {
+        return this.getItem(path).onSuccess((item) => {
+            if (item.type !== 'file') {
+                return (0, ts_utils_1.fail)(`Path is not a file: ${path}`);
+            }
+            return item.getRawContents();
+        });
+    }
+    /**
+     * Gets the children of a directory in the file tree.
+     */
+    getChildren(path) {
+        const absolutePath = this.resolveAbsolutePath(path);
+        const children = [];
+        // Find all items that are direct children of this directory
+        for (const [itemPath, item] of this._itemCache) {
+            if (this._isDirectChild(absolutePath, itemPath)) {
+                children.push(item);
+            }
+        }
+        return (0, ts_utils_1.succeed)(children);
+    }
+    /**
+     * Checks if childPath is a direct child of parentPath.
+     */
+    _isDirectChild(parentPath, childPath) {
+        // Normalize paths
+        const normalizedParent = parentPath.replace(/\/$/, '');
+        const normalizedChild = childPath.replace(/\/$/, '');
+        // Child must start with parent path
+        if (!normalizedChild.startsWith(normalizedParent + '/')) {
+            return false;
+        }
+        // Get the relative path from parent to child
+        const relativePath = normalizedChild.substring(normalizedParent.length + 1);
+        // Direct child means no additional slashes in the relative path
+        return !relativePath.includes('/');
+    }
+}
+exports.ZipFileTreeAccessors = ZipFileTreeAccessors;
+//# sourceMappingURL=zipFileTreeAccessors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"zipFileTreeAccessors.js","sourceRoot":"","sources":["../../../src/packlets/zip-file-tree/zipFileTreeAccessors.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport AdmZip from 'adm-zip';\nimport { Result, succeed, fail, captureResult, Converter, Validator, FileTree } from '@fgv/ts-utils';\n\n/**\n * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.\n * @public\n */\nexport class ZipFileItem implements FileTree.IFileTreeFileItem {\n  /**\n   * Indicates that this `FileTree.FileTreeItem` is a file.\n   */\n  public readonly type: 'file' = 'file';\n\n  /**\n   * The absolute path of the file within the ZIP archive.\n   */\n  public readonly absolutePath: string;\n\n  /**\n   * The name of the file\n   */\n  public readonly name: string;\n\n  /**\n   * The base name of the file (without extension)\n   */\n  public readonly baseName: string;\n\n  /**\n   * The extension of the file\n   */\n  public readonly extension: string;\n\n  /**\n   * The pre-loaded contents of the file.\n   */\n  private readonly _contents: string;\n\n  /**\n   * The ZIP file tree accessors that created this item.\n   */\n  private readonly _accessors: ZipFileTreeAccessors;\n\n  /**\n   * Constructor for ZipFileItem.\n   * @param zipFilePath - The path of the file within the ZIP.\n   * @param contents - The pre-loaded contents of the file.\n   * @param accessors - The ZIP file tree accessors.\n   */\n  public constructor(zipFilePath: string, contents: string, accessors: ZipFileTreeAccessors) {\n    this._contents = contents;\n    this._accessors = accessors;\n    this.absolutePath = '/' + zipFilePath;\n    this.name = accessors.getBaseName(zipFilePath);\n    this.extension = accessors.getExtension(zipFilePath);\n    this.baseName = accessors.getBaseName(zipFilePath, this.extension);\n  }\n\n  /**\n   * Gets the contents of the file as parsed JSON.\n   */\n  public getContents(): Result<unknown>;\n  public getContents<T>(converter: Validator<T> | Converter<T>): Result<T>;\n  public getContents<T>(converter?: Validator<T> | Converter<T>): Result<T | unknown> {\n    return this.getRawContents()\n      .onSuccess((contents) => {\n        return captureResult(() => {\n          const parsed = JSON.parse(contents);\n          if (converter) {\n            if ('convert' in converter) {\n              return converter.convert(parsed);\n            } /* c8 ignore next 3 - validator branch functionally tested but coverage tool misses due to interface complexity */ else {\n              return (converter as Validator<T>).validate(parsed);\n            }\n          }\n          return succeed(parsed);\n        }).onFailure(() => {\n          return fail(`Failed to parse JSON from file: ${this.absolutePath}`);\n        });\n      })\n      .onFailure((error) => {\n        return fail(`Failed to get contents from file: ${error}`);\n      });\n  }\n\n  /**\n   * Gets the raw contents of the file as a string.\n   */\n  public getRawContents(): Result<string> {\n    return succeed(this._contents);\n  }\n}\n\n/**\n * Implementation of `IFileTreeDirectoryItem` for directories in a ZIP archive.\n * @public\n */\nexport class ZipDirectoryItem implements FileTree.IFileTreeDirectoryItem {\n  /**\n   * Indicates that this `FileTree.FileTreeItem` is a directory.\n   */\n  public readonly type: 'directory' = 'directory';\n\n  /**\n   * The absolute path of the directory within the ZIP archive.\n   */\n  public readonly absolutePath: string;\n\n  /**\n   * The name of the directory\n   */\n  public readonly name: string;\n\n  /**\n   * The ZIP file tree accessors that created this item.\n   */\n  private readonly _accessors: ZipFileTreeAccessors;\n\n  /**\n   * Constructor for ZipDirectoryItem.\n   * @param directoryPath - The path of the directory within the ZIP.\n   * @param accessors - The ZIP file tree accessors.\n   */\n  public constructor(directoryPath: string, accessors: ZipFileTreeAccessors) {\n    this._accessors = accessors;\n    this.absolutePath = '/' + directoryPath.replace(/\\/$/, ''); // Normalize path\n    this.name = accessors.getBaseName(directoryPath);\n  }\n\n  /**\n   * Gets the children of the directory.\n   */\n  public getChildren(): Result<ReadonlyArray<FileTree.FileTreeItem>> {\n    return this._accessors.getChildren(this.absolutePath);\n  }\n}\n\n/**\n * File tree accessors for ZIP archives.\n * @public\n */\nexport class ZipFileTreeAccessors implements FileTree.IFileTreeAccessors {\n  /**\n   * The AdmZip instance containing the archive.\n   */\n  private readonly _zip: AdmZip;\n\n  /**\n   * Optional prefix to prepend to paths.\n   */\n  private readonly _prefix: string;\n\n  /**\n   * Cache of all items in the ZIP for efficient lookups.\n   */\n  private readonly _itemCache: Map<string, FileTree.FileTreeItem> = new Map();\n\n  /**\n   * Constructor for ZipFileTreeAccessors.\n   * @param zip - The AdmZip instance.\n   * @param prefix - Optional prefix to prepend to paths.\n   */\n  private constructor(zip: AdmZip, prefix?: string) {\n    this._zip = zip;\n    this._prefix = prefix || '';\n    this._buildItemCache();\n  }\n\n  /**\n   * Creates a new ZipFileTreeAccessors instance from a ZIP file buffer.\n   * @param zipBuffer - The ZIP file as an ArrayBuffer or Uint8Array.\n   * @param prefix - Optional prefix to prepend to paths.\n   * @returns Result containing the ZipFileTreeAccessors instance.\n   */\n  public static fromBuffer(\n    zipBuffer: ArrayBuffer | Uint8Array,\n    prefix?: string\n  ): Result<ZipFileTreeAccessors> {\n    try {\n      const buffer = Buffer.from(zipBuffer);\n      const zip = new AdmZip(buffer);\n      return succeed(new ZipFileTreeAccessors(zip, prefix));\n    } catch (error) {\n      /* c8 ignore next 1 - defensive coding: AdmZip always throws Error objects in practice */\n      return fail(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  /**\n   * Creates a new ZipFileTreeAccessors instance from a File object (browser environment).\n   * @param file - The File object containing ZIP data.\n   * @param prefix - Optional prefix to prepend to paths.\n   * @returns Result containing the ZipFileTreeAccessors instance.\n   */\n  public static async fromFile(file: File, prefix?: string): Promise<Result<ZipFileTreeAccessors>> {\n    try {\n      const arrayBuffer = await file.arrayBuffer();\n      return ZipFileTreeAccessors.fromBuffer(new Uint8Array(arrayBuffer), prefix);\n    } catch (error) {\n      return fail(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  /**\n   * Builds the cache of all items in the ZIP archive.\n   */\n  private _buildItemCache(): void {\n    const directories = new Set<string>();\n    const entries = this._zip.getEntries();\n\n    // First pass: collect all directories from file paths\n    entries.forEach((entry) => {\n      if (!entry.isDirectory) {\n        // Extract directory path from file path\n        const pathParts = entry.entryName.split('/');\n        for (let i = 1; i < pathParts.length; i++) {\n          const dirPath = pathParts.slice(0, i).join('/');\n          directories.add(dirPath);\n        }\n      } else {\n        // Also add explicit directories\n        const dirPath = entry.entryName.replace(/\\/$/, ''); // Remove trailing slash\n        if (dirPath) {\n          directories.add(dirPath);\n        }\n      }\n    });\n\n    // Add directory items to cache\n    directories.forEach((dirPath) => {\n      const absolutePath = this.resolveAbsolutePath(dirPath);\n      const item = new ZipDirectoryItem(dirPath, this);\n      this._itemCache.set(absolutePath, item);\n    });\n\n    // Add file items to cache\n    entries.forEach((entry) => {\n      if (!entry.isDirectory) {\n        const absolutePath = this.resolveAbsolutePath(entry.entryName);\n        const contents = entry.getData().toString('utf8');\n        const item = new ZipFileItem(entry.entryName, contents, this);\n        this._itemCache.set(absolutePath, item);\n      }\n    });\n  }\n\n  /**\n   * Resolves paths to an absolute path.\n   */\n  public resolveAbsolutePath(...paths: string[]): string {\n    const joinedPath = this.joinPaths(...paths);\n    const prefixed = this._prefix ? this.joinPaths(this._prefix, joinedPath) : joinedPath;\n    return prefixed.startsWith('/') ? prefixed : '/' + prefixed;\n  }\n\n  /**\n   * Gets the extension of a path.\n   */\n  public getExtension(path: string): string {\n    const name = this.getBaseName(path);\n    const lastDotIndex = name.lastIndexOf('.');\n    return lastDotIndex >= 0 ? name.substring(lastDotIndex) : '';\n  }\n\n  /**\n   * Gets the base name of a path.\n   */\n  public getBaseName(path: string, suffix?: string): string {\n    const normalizedPath = path.replace(/\\/$/, ''); // Remove trailing slash\n    const parts = normalizedPath.split('/');\n    let baseName = parts[parts.length - 1] || '';\n\n    if (suffix && baseName.endsWith(suffix)) {\n      baseName = baseName.substring(0, baseName.length - suffix.length);\n    }\n\n    return baseName;\n  }\n\n  /**\n   * Joins paths together.\n   */\n  public joinPaths(...paths: string[]): string {\n    return paths\n      .filter((p) => p && p.length > 0)\n      .map((p) => p.replace(/^\\/+|\\/+$/g, '')) // Remove leading/trailing slashes\n      .join('/')\n      .replace(/\\/+/g, '/'); // Normalize multiple slashes\n  }\n\n  /**\n   * Gets an item from the file tree.\n   */\n  public getItem(path: string): Result<FileTree.FileTreeItem> {\n    const absolutePath = this.resolveAbsolutePath(path);\n    const item = this._itemCache.get(absolutePath);\n\n    if (item) {\n      return succeed(item);\n    }\n\n    return fail(`Item not found: ${absolutePath}`);\n  }\n\n  /**\n   * Gets the contents of a file in the file tree.\n   */\n  public getFileContents(path: string): Result<string> {\n    return this.getItem(path).onSuccess((item) => {\n      if (item.type !== 'file') {\n        return fail(`Path is not a file: ${path}`);\n      }\n      return item.getRawContents();\n    });\n  }\n\n  /**\n   * Gets the children of a directory in the file tree.\n   */\n  public getChildren(path: string): Result<ReadonlyArray<FileTree.FileTreeItem>> {\n    const absolutePath = this.resolveAbsolutePath(path);\n    const children: FileTree.FileTreeItem[] = [];\n\n    // Find all items that are direct children of this directory\n    for (const [itemPath, item] of this._itemCache) {\n      if (this._isDirectChild(absolutePath, itemPath)) {\n        children.push(item);\n      }\n    }\n\n    return succeed(children);\n  }\n\n  /**\n   * Checks if childPath is a direct child of parentPath.\n   */\n  private _isDirectChild(parentPath: string, childPath: string): boolean {\n    // Normalize paths\n    const normalizedParent = parentPath.replace(/\\/$/, '');\n    const normalizedChild = childPath.replace(/\\/$/, '');\n\n    // Child must start with parent path\n    if (!normalizedChild.startsWith(normalizedParent + '/')) {\n      return false;\n    }\n\n    // Get the relative path from parent to child\n    const relativePath = normalizedChild.substring(normalizedParent.length + 1);\n\n    // Direct child means no additional slashes in the relative path\n    return !relativePath.includes('/');\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.0.0-0",
+  "version": "5.0.0-3",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -45,16 +45,18 @@
     "@types/heft-jest": "1.0.6",
     "@rushstack/heft-jest-plugin": "~0.16.9",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils-jest": "5.0.0-0",
-    "@fgv/ts-utils": "5.0.0-0"
+    "@fgv/ts-utils-jest": "5.0.0-3",
+    "@fgv/ts-utils": "5.0.0-3"
   },
   "dependencies": {
     "luxon": "^3.6.1",
     "mustache": "^4.2.0",
-    "papaparse": "^5.4.1"
+    "papaparse": "^5.4.1",
+    "@types/adm-zip": "~0.5.7",
+    "adm-zip": "~0.5.16"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-0"
+    "@fgv/ts-utils": "5.0.0-3"
   },
   "scripts": {
     "build": "heft test --clean",