@fgv/ts-extras 5.0.2 → 5.1.0-0

package/lib/packlets/mustache/mustacheTemplate.js

@@ -0,0 +1,249 @@
+"use strict";
+/*
+ * Copyright (c) 2020 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.MustacheTemplate = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const mustache_1 = __importDefault(require("mustache"));
+/**
+ * Default options for MustacheTemplate
+ */
+const DEFAULT_OPTIONS = {
+    tags: ['{{', '}}'],
+    includeComments: false,
+    includePartials: false
+};
+/**
+ * A helper class for working with Mustache templates that provides
+ * validation, variable extraction, and context validation utilities.
+ * @public
+ */
+class MustacheTemplate {
+    constructor(template, tokens, options) {
+        this.template = template;
+        this._tokens = tokens;
+        this.options = options;
+    }
+    /**
+     * Creates a new MustacheTemplate instance.
+     * @param template - The Mustache template string to parse
+     * @param options - Optional parsing options
+     * @returns Success with the template instance, or Failure if parsing fails
+     */
+    static create(template, options) {
+        const resolvedOptions = MustacheTemplate._resolveOptions(options);
+        return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess((tokens) => {
+            return (0, ts_utils_1.succeed)(new MustacheTemplate(template, tokens, resolvedOptions));
+        });
+    }
+    /**
+     * Validates that a template string has valid Mustache syntax.
+     * @param template - The template string to validate
+     * @param options - Optional parsing options
+     * @returns Success with true if valid, or Failure with a descriptive error message
+     */
+    static validate(template, options) {
+        const resolvedOptions = MustacheTemplate._resolveOptions(options);
+        return MustacheTemplate._parseTokens(template, resolvedOptions).onSuccess(() => (0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * Checks if this template instance has valid syntax.
+     * Always returns Success(true) since parsing succeeded in create().
+     * @returns Success with true
+     */
+    validate() {
+        return (0, ts_utils_1.succeed)(true);
+    }
+    /**
+     * Extracts all variable references from the template.
+     * @returns An array of variable references found in the template
+     */
+    extractVariables() {
+        if (this._variables === undefined) {
+            this._variables = this._extractVariablesFromTokens(this._tokens);
+        }
+        return this._variables;
+    }
+    /**
+     * Extracts unique variable names from the template.
+     * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])
+     */
+    extractVariableNames() {
+        const variables = this.extractVariables();
+        const seen = new Set();
+        const names = [];
+        for (const variable of variables) {
+            if (!seen.has(variable.name)) {
+                seen.add(variable.name);
+                names.push(variable.name);
+            }
+        }
+        return names;
+    }
+    /**
+     * Validates that a context object has all required variables.
+     * @param context - The context object to validate
+     * @returns Success with validation result containing details about present/missing variables
+     */
+    validateContext(context) {
+        const variables = this.extractVariables();
+        const presentVariables = [];
+        const missingVariables = [];
+        const missingDetails = [];
+        const checked = new Set();
+        for (const variable of variables) {
+            if (checked.has(variable.name)) {
+                continue;
+            }
+            checked.add(variable.name);
+            const lookup = this._lookupPath(context, variable.path);
+            if (lookup.found) {
+                presentVariables.push(variable.name);
+            }
+            else {
+                missingVariables.push(variable.name);
+                missingDetails.push({
+                    variable,
+                    failedAtSegment: lookup.failedAt,
+                    existingPath: lookup.existingPath
+                });
+            }
+        }
+        return (0, ts_utils_1.succeed)({
+            isValid: missingVariables.length === 0,
+            presentVariables,
+            missingVariables,
+            missingDetails
+        });
+    }
+    /**
+     * Renders the template with the given context.
+     * Use this for pre-validated contexts where you've already checked
+     * that all required variables are present.
+     * @param context - The context object for template rendering
+     * @returns Success with the rendered string, or Failure if rendering fails
+     */
+    render(context) {
+        return (0, ts_utils_1.captureResult)(() => mustache_1.default.render(this.template, context));
+    }
+    /**
+     * Validates the context and renders the template if validation passes.
+     * @param context - The context object to validate and render with
+     * @returns Success with the rendered string, or Failure with validation or render errors
+     */
+    validateAndRender(context) {
+        return this.validateContext(context).onSuccess((validation) => {
+            if (!validation.isValid) {
+                const missing = validation.missingVariables.join(', ');
+                return (0, ts_utils_1.fail)(`Missing required variables: ${missing}`);
+            }
+            return this.render(context);
+        });
+    }
+    static _resolveOptions(options) {
+        var _a, _b;
+        if (options === undefined) {
+            return DEFAULT_OPTIONS;
+        }
+        return {
+            tags: options.tags ? [options.tags[0], options.tags[1]] : DEFAULT_OPTIONS.tags,
+            includeComments: (_a = options.includeComments) !== null && _a !== void 0 ? _a : DEFAULT_OPTIONS.includeComments,
+            includePartials: (_b = options.includePartials) !== null && _b !== void 0 ? _b : DEFAULT_OPTIONS.includePartials
+        };
+    }
+    static _parseTokens(template, options) {
+        return (0, ts_utils_1.captureResult)(() => mustache_1.default.parse(template, options.tags));
+    }
+    _extractVariablesFromTokens(tokens) {
+        const variables = [];
+        for (const token of tokens) {
+            const type = token[0];
+            const value = token[1];
+            // Skip text tokens
+            if (type === 'text') {
+                continue;
+            }
+            // Handle comments based on options
+            if (type === '!' && !this.options.includeComments) {
+                continue;
+            }
+            // Handle partials based on options
+            if (type === '>' && !this.options.includePartials) {
+                continue;
+            }
+            // Handle variable tokens: 'name', '&', '#', '^', and optionally '!', '>'
+            if (type === 'name' || type === '&' || type === '#' || type === '^' || type === '!' || type === '>') {
+                const isSection = type === '#' || type === '^';
+                variables.push({
+                    name: value,
+                    path: this._parsePath(value),
+                    tokenType: type,
+                    isSection
+                });
+            }
+            // Recursively extract from nested tokens in sections
+            if ((type === '#' || type === '^') && token.length > 4) {
+                const nestedTokens = token[4];
+                if (nestedTokens) {
+                    variables.push(...this._extractVariablesFromTokens(nestedTokens));
+                }
+            }
+        }
+        return variables;
+    }
+    _parsePath(name) {
+        // Handle special case of '.' which means current context
+        if (name === '.') {
+            return ['.'];
+        }
+        // Split on dots to get path segments
+        return name.split('.').filter((segment) => segment.length > 0);
+    }
+    _lookupPath(context, path) {
+        // Handle '.' which always exists if context is not null/undefined
+        if (path.length === 1 && path[0] === '.') {
+            return { found: context !== undefined && context !== null, existingPath: [] };
+        }
+        let current = context;
+        const existingPath = [];
+        for (const segment of path) {
+            if (current === undefined || current === null) {
+                return { found: false, existingPath, failedAt: segment };
+            }
+            if (typeof current !== 'object') {
+                return { found: false, existingPath, failedAt: segment };
+            }
+            const obj = current;
+            if (!(segment in obj)) {
+                return { found: false, existingPath, failedAt: segment };
+            }
+            current = obj[segment];
+            existingPath.push(segment);
+        }
+        return { found: true, existingPath };
+    }
+}
+exports.MustacheTemplate = MustacheTemplate;
+//# sourceMappingURL=mustacheTemplate.js.map

package/lib/packlets/record-jar/recordJarHelpers.js

@@ -153,7 +153,7 @@ class RecordParser {
         var _a, _b;
         let trimmed = line.trim();
         if (!this._body.isContinuation) {
-            /* c8 ignore next */
+            /* c8 ignore next - functional code tested but coverage intermittently missed */
             const fixedSize = (_b = (_a = this.options) === null || _a === void 0 ? void 0 : _a.fixedContinuationSize) !== null && _b !== void 0 ? _b : 0;
             if (fixedSize > 0) {
                 if (trimmed.length < line.length - fixedSize) {

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

@@ -0,0 +1,9 @@
+import { Converter } from '@fgv/ts-utils';
+/**
+ * Creates a converter that parses YAML string content and then applies the supplied converter.
+ * @param converter - Converter to apply to the parsed YAML
+ * @returns Converter that parses YAML then validates
+ * @public
+ */
+export declare function yamlConverter<T>(converter: Converter<T>): Converter<T>;
+//# sourceMappingURL=converters.d.ts.map

package/lib/packlets/yaml/converters.js

@@ -0,0 +1,82 @@
+"use strict";
+/*
+ * Copyright (c) 2024 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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yamlConverter = yamlConverter;
+const ts_utils_1 = require("@fgv/ts-utils");
+const yaml = __importStar(require("js-yaml"));
+/**
+ * Creates a converter that parses YAML string content and then applies the supplied converter.
+ * @param converter - Converter to apply to the parsed YAML
+ * @returns Converter that parses YAML then validates
+ * @public
+ */
+function yamlConverter(converter) {
+    return new ts_utils_1.Conversion.BaseConverter((from) => {
+        if (typeof from !== 'string') {
+            return (0, ts_utils_1.fail)('Input must be a string');
+        }
+        const parseResult = (0, ts_utils_1.captureResult)(() => yaml.load(from));
+        if (parseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse YAML: ${parseResult.message}`);
+        }
+        const parsed = parseResult.value;
+        if (typeof parsed !== 'object' || parsed === null) {
+            return (0, ts_utils_1.fail)('Failed to parse YAML: YAML content must be an object');
+        }
+        return converter.convert(parsed);
+    });
+}
+//# sourceMappingURL=converters.js.map

package/lib/packlets/yaml/index.d.ts

@@ -0,0 +1,2 @@
+export * from './converters';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/yaml/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/*
+ * Copyright (c) 2024 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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./converters"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -8,4 +8,5 @@
  * @packageDocumentation
  */
 export { ZipFileTreeAccessors, ZipFileItem, ZipDirectoryItem } from './zipFileTreeAccessors';
+export * from './zipFileTreeWriter';
 //# sourceMappingURL=index.d.ts.map

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

@@ -20,6 +20,20 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZipDirectoryItem = exports.ZipFileItem = exports.ZipFileTreeAccessors = void 0;
 /**
@@ -35,4 +49,5 @@ 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; } });
+__exportStar(require("./zipFileTreeWriter"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -1,4 +1,4 @@
-import { Result, Converter, Validator } from '@fgv/ts-utils';
+import { Result, Converter, Validator, DetailedResult } from '@fgv/ts-utils';
 import { FileTree, JsonValue } from '@fgv/ts-json-base';
 /**
  * Implementation of `FileTree.IFileTreeFileItem` for files in a ZIP archive.
@@ -52,6 +52,22 @@ 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.
@@ -103,7 +119,7 @@ export declare class ZipDirectoryItem<TCT extends string = string> implements Fi
  * File tree accessors for ZIP archives.
  * @public
  */
-export declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IFileTreeAccessors<TCT> {
+export declare class ZipFileTreeAccessors<TCT extends string = string> implements FileTree.IMutableFileTreeAccessors<TCT> {
     /**
      * The unzipped file data.
      */
@@ -175,6 +191,19 @@ 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

@@ -61,6 +61,30 @@ 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.
@@ -182,7 +206,7 @@ class ZipFileTreeAccessors {
                         resolve((0, ts_utils_1.succeed)(new ZipFileTreeAccessors(files, normalizedParams)));
                     }
                 });
-                /* c8 ignore next 6 - defensive coding: fflate reports errors via callback, not exceptions */
+                /* c8 ignore next 5 - defensive coding: fflate reports errors via callback, not exceptions */
             }
             catch (error) {
                 resolve((0, ts_utils_1.fail)(`Failed to load ZIP archive: ${error instanceof Error ? error.message : String(error)}`));
@@ -243,6 +267,23 @@ 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/lib/packlets/zip-file-tree/zipFileTreeWriter.d.ts

@@ -0,0 +1,27 @@
+import { Result } from '@fgv/ts-utils';
+/**
+ * Simple interface for a file to be added to a zip file.
+ * @public
+ */
+export interface IZipTextFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/**
+ * Supported compression levels for zip files.
+ * @public
+ */
+export type ZipCompressionLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+/**
+ * Options for creating a zip file from text files.
+ * @public
+ */
+export interface ICreateZipOptions {
+    readonly level?: ZipCompressionLevel;
+}
+/**
+ * Creates a zip file from an array of text files.
+ * @public
+ */
+export declare function createZipFromTextFiles(files: ReadonlyArray<IZipTextFile>, options?: ICreateZipOptions): Result<Uint8Array>;
+//# sourceMappingURL=zipFileTreeWriter.d.ts.map

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

@@ -0,0 +1,43 @@
+"use strict";
+/*
+ * Copyright (c) 2026 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.createZipFromTextFiles = createZipFromTextFiles;
+const fflate_1 = require("fflate");
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Creates a zip file from an array of text files.
+ * @public
+ */
+function createZipFromTextFiles(files, options) {
+    return (0, ts_utils_1.captureResult)(() => {
+        var _a;
+        const out = {};
+        for (const f of files) {
+            const normalizedPath = f.path.replace(/^\/+/, '');
+            out[normalizedPath] = (0, fflate_1.strToU8)(f.contents);
+        }
+        return (0, fflate_1.zipSync)(out, { level: (_a = options === null || options === void 0 ? void 0 : options.level) !== null && _a !== void 0 ? _a : 6 });
+        /* c8 ignore next - defensive: zipSync only throws on internal library errors */
+    }).withErrorFormat((e) => `Failed to create zip: ${e}`);
+}
+//# sourceMappingURL=zipFileTreeWriter.js.map