@fgv/ts-extras 5.0.2 → 5.1.0-0

package/lib/packlets/crypto-utils/nodeCryptoProvider.js

@@ -0,0 +1,196 @@
+"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.nodeCryptoProvider = exports.NodeCryptoProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const ts_utils_1 = require("@fgv/ts-utils");
+const Constants = __importStar(require("./constants"));
+/**
+ * Node.js implementation of {@link CryptoUtils.ICryptoProvider} using the built-in crypto module.
+ * Uses AES-256-GCM for authenticated encryption.
+ * @public
+ */
+class NodeCryptoProvider {
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns `Success` with encryption result, or `Failure` with an error.
+     */
+    async encrypt(plaintext, key) {
+        return (0, ts_utils_1.captureResult)(() => {
+            if (key.length !== Constants.AES_256_KEY_SIZE) {
+                throw new Error(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+            }
+            // Generate random IV
+            const iv = crypto.randomBytes(Constants.GCM_IV_SIZE);
+            // Create cipher
+            const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+            // Encrypt
+            const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+            // Get auth tag
+            const authTag = cipher.getAuthTag();
+            return {
+                iv: new Uint8Array(iv),
+                authTag: new Uint8Array(authTag),
+                encryptedData: new Uint8Array(encrypted)
+            };
+        });
+    }
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+     */
+    async decrypt(encryptedData, key, iv, authTag) {
+        if (key.length !== Constants.AES_256_KEY_SIZE) {
+            return (0, ts_utils_1.fail)(`Key must be ${Constants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        if (iv.length !== Constants.GCM_IV_SIZE) {
+            return (0, ts_utils_1.fail)(`IV must be ${Constants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+        }
+        if (authTag.length !== Constants.GCM_AUTH_TAG_SIZE) {
+            return (0, ts_utils_1.fail)(`Auth tag must be ${Constants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        }
+        return (0, ts_utils_1.captureResult)(() => {
+            // Create decipher
+            const decipher = crypto.createDecipheriv('aes-256-gcm', Buffer.from(key), Buffer.from(iv));
+            // Set auth tag
+            decipher.setAuthTag(Buffer.from(authTag));
+            // Decrypt
+            const decrypted = Buffer.concat([decipher.update(Buffer.from(encryptedData)), decipher.final()]);
+            return decrypted.toString('utf8');
+        }).withErrorFormat((e) => `Decryption failed: ${e}`);
+    }
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns `Success` with generated key, or `Failure` with an error.
+     */
+    async generateKey() {
+        return (0, ts_utils_1.captureResult)(() => {
+            const key = crypto.randomBytes(Constants.AES_256_KEY_SIZE);
+            return new Uint8Array(key);
+        });
+    }
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns `Success` with derived 32-byte key, or `Failure` with an error.
+     */
+    async deriveKey(password, salt, iterations) {
+        if (iterations < 1) {
+            return (0, ts_utils_1.fail)('Iterations must be at least 1');
+        }
+        if (salt.length < 8) {
+            return (0, ts_utils_1.fail)('Salt should be at least 8 bytes');
+        }
+        return new Promise((resolve) => {
+            crypto.pbkdf2(password, Buffer.from(salt), iterations, Constants.AES_256_KEY_SIZE, 'sha256', (err, derivedKey) => {
+                /* c8 ignore next 3 - PBKDF2 internal errors are hard to trigger with valid parameters */
+                if (err) {
+                    resolve((0, ts_utils_1.fail)(`Key derivation failed: ${err.message}`));
+                }
+                else {
+                    resolve((0, ts_utils_1.succeed)(new Uint8Array(derivedKey)));
+                }
+            });
+        });
+    }
+    // ============================================================================
+    // Platform Utility Methods
+    // ============================================================================
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length) {
+        if (length < 1) {
+            return ts_utils_1.Failure.with('Length must be at least 1');
+        }
+        return (0, ts_utils_1.captureResult)(() => new Uint8Array(crypto.randomBytes(length)));
+    }
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data) {
+        return Buffer.from(data).toString('base64');
+    }
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64) {
+        // Check for obviously invalid characters
+        if (!/^[A-Za-z0-9+/]*={0,2}$/.test(base64)) {
+            return ts_utils_1.Failure.with('Invalid base64 string');
+        }
+        return ts_utils_1.Success.with(new Uint8Array(Buffer.from(base64, 'base64')));
+    }
+}
+exports.NodeCryptoProvider = NodeCryptoProvider;
+/**
+ * Singleton instance of {@link CryptoUtils.NodeCryptoProvider}.
+ * @public
+ */
+exports.nodeCryptoProvider = new NodeCryptoProvider();
+//# sourceMappingURL=nodeCryptoProvider.js.map

package/lib/packlets/experimental/formatter.d.ts

@@ -31,7 +31,7 @@ export declare class FormattableBase {
      */
     protected static _tryAddDetail(details: string[], label: string, value: string | undefined): void;
     /**
-     * {@inheritdoc Experimental.Formattable.format}
+     * {@inheritDoc Experimental.Formattable.format}
      */
     format(template: string): Result<string>;
 }

package/lib/packlets/experimental/formatter.js

@@ -48,7 +48,7 @@ class FormattableBase {
         }
     }
     /**
-     * {@inheritdoc Experimental.Formattable.format}
+     * {@inheritDoc Experimental.Formattable.format}
      */
     format(template) {
         return (0, ts_utils_1.captureResult)(() => mustache_1.default.render(template, this));

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

@@ -0,0 +1,3 @@
+export { IContextValidationResult, IMissingVariableDetail, IMustacheTemplateOptions, IVariableRef, MustacheTokenType } from './interfaces';
+export { MustacheTemplate } from './mustacheTemplate';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/mustache/index.js

@@ -0,0 +1,27 @@
+"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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MustacheTemplate = void 0;
+var mustacheTemplate_1 = require("./mustacheTemplate");
+Object.defineProperty(exports, "MustacheTemplate", { enumerable: true, get: function () { return mustacheTemplate_1.MustacheTemplate; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/mustache/interfaces.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Type of a Mustache token as returned by Mustache.parse()
+ * @public
+ */
+export type MustacheTokenType = 'text' | 'name' | '&' | '#' | '^' | '!' | '>' | '=';
+/**
+ * Represents a variable reference extracted from a Mustache template.
+ * @public
+ */
+export interface IVariableRef {
+    /**
+     * The raw variable name as it appears in the template (e.g., 'user.name')
+     */
+    readonly name: string;
+    /**
+     * The path segments parsed from the variable name (e.g., ['user', 'name'])
+     */
+    readonly path: readonly string[];
+    /**
+     * The type of token this variable was extracted from
+     */
+    readonly tokenType: MustacheTokenType;
+    /**
+     * Whether this variable is used in a section context (# or ^)
+     * Section variables may reference arrays/objects for iteration
+     */
+    readonly isSection: boolean;
+}
+/**
+ * Details about a missing variable in context validation.
+ * @public
+ */
+export interface IMissingVariableDetail {
+    /**
+     * The variable reference that is missing
+     */
+    readonly variable: IVariableRef;
+    /**
+     * The path segment where the lookup failed
+     * (e.g., for 'user.profile.name' if 'profile' is missing, this would be 'profile')
+     */
+    readonly failedAtSegment?: string;
+    /**
+     * The parent path that exists (e.g., ['user'] if 'user' exists but 'user.profile' does not)
+     */
+    readonly existingPath: readonly string[];
+}
+/**
+ * Result of context validation, containing details about missing variables.
+ * @public
+ */
+export interface IContextValidationResult {
+    /**
+     * Whether the context is valid (has all required variables)
+     */
+    readonly isValid: boolean;
+    /**
+     * Variables that are present in the context
+     */
+    readonly presentVariables: readonly string[];
+    /**
+     * Variables that are missing from the context
+     */
+    readonly missingVariables: readonly string[];
+    /**
+     * Detailed information about each missing variable
+     */
+    readonly missingDetails: readonly IMissingVariableDetail[];
+}
+/**
+ * Options for template parsing and validation.
+ * @public
+ */
+export interface IMustacheTemplateOptions {
+    /**
+     * Custom opening and closing tags (default: `['{{', '}}']`)
+     */
+    readonly tags?: readonly [string, string];
+    /**
+     * Whether to include comment tokens in variable extraction (default: false)
+     */
+    readonly includeComments?: boolean;
+    /**
+     * Whether to include partial references in variable extraction (default: false)
+     */
+    readonly includePartials?: boolean;
+}
+/**
+ * Required version of options with all fields populated.
+ * @internal
+ */
+export interface IRequiredMustacheTemplateOptions {
+    readonly tags: [string, string];
+    readonly includeComments: boolean;
+    readonly includePartials: boolean;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/packlets/mustache/interfaces.js

@@ -0,0 +1,26 @@
+"use strict";
+/* c8 ignore start - Type definitions only, no runtime code */
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/* c8 ignore stop */
+//# sourceMappingURL=interfaces.js.map

package/lib/packlets/mustache/mustacheTemplate.d.ts

@@ -0,0 +1,76 @@
+import { Result } from '@fgv/ts-utils';
+import { IContextValidationResult, IMustacheTemplateOptions, IRequiredMustacheTemplateOptions, IVariableRef } from './interfaces';
+/**
+ * A helper class for working with Mustache templates that provides
+ * validation, variable extraction, and context validation utilities.
+ * @public
+ */
+export declare class MustacheTemplate {
+    /**
+     * The original template string
+     */
+    readonly template: string;
+    /**
+     * The options used for parsing this template
+     */
+    readonly options: Readonly<IRequiredMustacheTemplateOptions>;
+    private readonly _tokens;
+    private _variables?;
+    private constructor();
+    /**
+     * 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: string, options?: IMustacheTemplateOptions): Result<MustacheTemplate>;
+    /**
+     * 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: string, options?: IMustacheTemplateOptions): Result<true>;
+    /**
+     * Checks if this template instance has valid syntax.
+     * Always returns Success(true) since parsing succeeded in create().
+     * @returns Success with true
+     */
+    validate(): Result<true>;
+    /**
+     * Extracts all variable references from the template.
+     * @returns An array of variable references found in the template
+     */
+    extractVariables(): readonly IVariableRef[];
+    /**
+     * Extracts unique variable names from the template.
+     * @returns An array of unique variable name strings (e.g., ['user.name', 'items'])
+     */
+    extractVariableNames(): readonly string[];
+    /**
+     * 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: unknown): Result<IContextValidationResult>;
+    /**
+     * 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: unknown): Result<string>;
+    /**
+     * 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: unknown): Result<string>;
+    private static _resolveOptions;
+    private static _parseTokens;
+    private _extractVariablesFromTokens;
+    private _parsePath;
+    private _lookupPath;
+}
+//# sourceMappingURL=mustacheTemplate.d.ts.map