@fgv/ts-extras 5.1.0-12 → 5.1.0-14

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

@@ -116,6 +116,18 @@ export class NodeCryptoProvider {
             });
         });
     }
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    async sha256(data) {
+        return captureResult(() => {
+            const hash = crypto.createHash('sha256');
+            hash.update(data, 'utf8');
+            return hash.digest('hex');
+        });
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================

package/dist/packlets/yaml/index.js

@@ -20,4 +20,5 @@
  * SOFTWARE.
  */
 export * from './converters';
+export * from './serializers';
 //# sourceMappingURL=index.js.map

package/dist/packlets/yaml/serializers.js

@@ -0,0 +1,48 @@
+/*
+ * 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.
+ */
+import { captureResult, fail } from '@fgv/ts-utils';
+import * as yaml from 'js-yaml';
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+export function yamlStringify(value, options) {
+    if (value === null || value === undefined) {
+        return fail('Cannot serialize null or undefined to YAML');
+    }
+    if (typeof value !== 'object') {
+        return fail('YAML serialization requires an object or array');
+    }
+    return captureResult(() => yaml.dump(value, {
+        indent: options === null || options === void 0 ? void 0 : options.indent,
+        flowLevel: options === null || options === void 0 ? void 0 : options.flowLevel,
+        sortKeys: options === null || options === void 0 ? void 0 : options.sortKeys,
+        lineWidth: options === null || options === void 0 ? void 0 : options.lineWidth,
+        noRefs: options === null || options === void 0 ? void 0 : options.noRefs,
+        noArrayIndent: options === null || options === void 0 ? void 0 : options.noArrayIndent,
+        forceQuotes: options === null || options === void 0 ? void 0 : options.forceQuotes
+    }));
+}
+//# sourceMappingURL=serializers.js.map

package/dist/ts-extras.d.ts

@@ -939,6 +939,12 @@ declare interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
@@ -1445,6 +1451,42 @@ declare interface IVariableRef {
     readonly isSection: boolean;
 }
 
+/**
+ * Options for YAML serialization, mirroring commonly-used `js-yaml` `DumpOptions`.
+ * @public
+ */
+declare interface IYamlSerializeOptions {
+    /**
+     * Indentation width in spaces (default: 2).
+     */
+    readonly indent?: number;
+    /**
+     * Nesting level at which to switch from block to flow style.
+     * -1 means block style everywhere (default: -1).
+     */
+    readonly flowLevel?: number;
+    /**
+     * If true, sort keys when dumping (default: false).
+     */
+    readonly sortKeys?: boolean;
+    /**
+     * Maximum line width (default: 80).
+     */
+    readonly lineWidth?: number;
+    /**
+     * If true, don't convert duplicate objects into references (default: false).
+     */
+    readonly noRefs?: boolean;
+    /**
+     * If true, don't add an indentation level to array elements (default: false).
+     */
+    readonly noArrayIndent?: boolean;
+    /**
+     * If true, all non-key strings will be quoted (default: false).
+     */
+    readonly forceQuotes?: boolean;
+}
+
 /**
  * Simple interface for a file to be added to a zip file.
  * @public
@@ -2000,6 +2042,12 @@ declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with derived 32-byte key, or `Failure` with an error.
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate
@@ -2312,7 +2360,9 @@ declare const uint8ArrayFromBase64: Converter<Uint8Array>;
 
 declare namespace Yaml {
     export {
-        yamlConverter
+        yamlConverter,
+        yamlStringify,
+        IYamlSerializeOptions
     }
 }
 export { Yaml }
@@ -2325,6 +2375,15 @@ export { Yaml }
  */
 declare function yamlConverter<T>(converter: Converter<T>): Converter<T>;
 
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+declare function yamlStringify(value: unknown, options?: IYamlSerializeOptions): Result<string>;
+
 /**
  * Supported compression levels for zip files.
  * @public

package/lib/packlets/crypto-utils/model.d.ts

@@ -145,6 +145,12 @@ export interface ICryptoProvider {
      * @returns Success with derived 32-byte key, or Failure with error
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns Success with hex-encoded hash string, or Failure with error
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate

package/lib/packlets/crypto-utils/nodeCryptoProvider.d.ts

@@ -35,6 +35,12 @@ export declare class NodeCryptoProvider implements ICryptoProvider {
      * @returns `Success` with derived 32-byte key, or `Failure` with an error.
      */
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    sha256(data: string): Promise<Result<string>>;
     /**
      * Generates cryptographically secure random bytes.
      * @param length - Number of bytes to generate

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

@@ -152,6 +152,18 @@ class NodeCryptoProvider {
             });
         });
     }
+    /**
+     * Computes a SHA-256 hash of the given data.
+     * @param data - UTF-8 string to hash
+     * @returns `Success` with hex-encoded hash string, or `Failure` with an error.
+     */
+    async sha256(data) {
+        return (0, ts_utils_1.captureResult)(() => {
+            const hash = crypto.createHash('sha256');
+            hash.update(data, 'utf8');
+            return hash.digest('hex');
+        });
+    }
     // ============================================================================
     // Platform Utility Methods
     // ============================================================================

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

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

package/lib/packlets/yaml/index.js

@@ -36,4 +36,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./converters"), exports);
+__exportStar(require("./serializers"), exports);
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,45 @@
+import { Result } from '@fgv/ts-utils';
+/**
+ * Options for YAML serialization, mirroring commonly-used `js-yaml` `DumpOptions`.
+ * @public
+ */
+export interface IYamlSerializeOptions {
+    /**
+     * Indentation width in spaces (default: 2).
+     */
+    readonly indent?: number;
+    /**
+     * Nesting level at which to switch from block to flow style.
+     * -1 means block style everywhere (default: -1).
+     */
+    readonly flowLevel?: number;
+    /**
+     * If true, sort keys when dumping (default: false).
+     */
+    readonly sortKeys?: boolean;
+    /**
+     * Maximum line width (default: 80).
+     */
+    readonly lineWidth?: number;
+    /**
+     * If true, don't convert duplicate objects into references (default: false).
+     */
+    readonly noRefs?: boolean;
+    /**
+     * If true, don't add an indentation level to array elements (default: false).
+     */
+    readonly noArrayIndent?: boolean;
+    /**
+     * If true, all non-key strings will be quoted (default: false).
+     */
+    readonly forceQuotes?: boolean;
+}
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+export declare function yamlStringify(value: unknown, options?: IYamlSerializeOptions): Result<string>;
+//# sourceMappingURL=serializers.d.ts.map

package/lib/packlets/yaml/serializers.js

@@ -0,0 +1,84 @@
+"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.yamlStringify = yamlStringify;
+const ts_utils_1 = require("@fgv/ts-utils");
+const yaml = __importStar(require("js-yaml"));
+/**
+ * Serializes a value to a YAML string.
+ * @param value - The value to serialize (must be an object or array)
+ * @param options - Optional serialization options
+ * @returns `Success` with YAML string, or `Failure` with error
+ * @public
+ */
+function yamlStringify(value, options) {
+    if (value === null || value === undefined) {
+        return (0, ts_utils_1.fail)('Cannot serialize null or undefined to YAML');
+    }
+    if (typeof value !== 'object') {
+        return (0, ts_utils_1.fail)('YAML serialization requires an object or array');
+    }
+    return (0, ts_utils_1.captureResult)(() => yaml.dump(value, {
+        indent: options === null || options === void 0 ? void 0 : options.indent,
+        flowLevel: options === null || options === void 0 ? void 0 : options.flowLevel,
+        sortKeys: options === null || options === void 0 ? void 0 : options.sortKeys,
+        lineWidth: options === null || options === void 0 ? void 0 : options.lineWidth,
+        noRefs: options === null || options === void 0 ? void 0 : options.noRefs,
+        noArrayIndent: options === null || options === void 0 ? void 0 : options.noArrayIndent,
+        forceQuotes: options === null || options === void 0 ? void 0 : options.forceQuotes
+    }));
+}
+//# sourceMappingURL=serializers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-12",
+  "version": "5.1.0-14",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -86,10 +86,10 @@
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/heft-dual-rig": "5.1.0-12",
-    "@fgv/ts-utils-jest": "5.1.0-12",
-    "@fgv/ts-utils": "5.1.0-12",
-    "@fgv/typedoc-compact-theme": "5.1.0-12"
+    "@fgv/heft-dual-rig": "5.1.0-14",
+    "@fgv/typedoc-compact-theme": "5.1.0-14",
+    "@fgv/ts-utils-jest": "5.1.0-14",
+    "@fgv/ts-utils": "5.1.0-14"
   },
   "dependencies": {
     "luxon": "^3.7.2",
@@ -97,10 +97,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-12"
+    "@fgv/ts-json-base": "5.1.0-14"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-12"
+    "@fgv/ts-utils": "5.1.0-14"
   },
   "repository": {
     "type": "git",