@flowscripter/dynamic-cli-framework 12.0.1 → 12.2.0

package/dist/src/service/configuration/configTargets.d.ts

@@ -0,0 +1,91 @@
+import { type Command, type ComplexOption, type GlobalCommandArgument, type GroupCommand, type Option, type CommandRegistry, type CLIConfig, type SingleValueType, type Values, type ValueNode } from "@flowscripter/dynamic-cli-framework-api";
+import { type DeferredCustomValidation } from "../../runtime/values/argumentValueValidation.ts";
+export declare const MASK = "********";
+type Node = unknown;
+/**
+ * A command whose default argument values can be managed via the `config` group commands.
+ */
+export interface ConfigTarget {
+    /** The key under `defaults`: the command name or `<group name>:<member name>`. */
+    readonly key: string;
+    readonly command: Command;
+    readonly group?: GroupCommand;
+    /** Set for global commands and global modifier commands. */
+    readonly argument?: GlobalCommandArgument;
+    /** Empty for global commands. */
+    readonly options: ReadonlyArray<Option | ComplexOption>;
+}
+/**
+ * Collect all commands in the registry with `enableConfiguration` set, except the `config` modifier.
+ */
+export declare function getConfigTargets(registry: CommandRegistry): Map<string, ConfigTarget>;
+export interface PathStep {
+    readonly name: string;
+    readonly index?: number;
+}
+/**
+ * Parse an option path such as `address[1].port` into steps.
+ */
+export declare function parseOptionPath(path: string): Array<PathStep> | string;
+export interface ResolvedPath {
+    readonly steps: Array<PathStep>;
+    readonly leaf: Option | ComplexOption;
+}
+/**
+ * Walk the steps through the target's options returning the option the path refers to.
+ */
+export declare function resolveOptionPath(target: ConfigTarget, path: string): ResolvedPath | string;
+export declare function containsSecret(option: Option | ComplexOption): boolean;
+export declare function getAtPath(root: Node, steps: ReadonlyArray<PathStep>): Node;
+/**
+ * Set a value at the path in the provided (mutable) root creating parents as needed.
+ */
+export declare function setAtPath(root: Record<string, Node>, steps: ReadonlyArray<PathStep>, value: Node): void;
+/**
+ * Remove the value at the path and any parent objects left empty. Returns false if there was no value.
+ */
+export declare function removeAtPath(root: Record<string, Node>, steps: ReadonlyArray<PathStep>): boolean;
+/**
+ * All `__SECRET__:` sentinel strings within the value.
+ */
+export declare function collectSentinels(value: Node): Array<string>;
+/**
+ * A validated, converted change to a single option of a target.
+ */
+export interface ConfigChange {
+    readonly steps: ReadonlyArray<PathStep>;
+    readonly path: string;
+    readonly leaf: Option | ComplexOption;
+    /** Native value, or the plain text of a SECRET which must be stored via the secret service. */
+    readonly value: Node;
+    readonly isSecret: boolean;
+}
+/**
+ * Validate and convert the raw (string) value for the option path of the target. Required checks are
+ * not applied. Custom validators of the target are run later by {@link validateChanges}.
+ */
+export declare function prepareChange(target: ConfigTarget, path: string, raw: string, deferred: Array<DeferredCustomValidation>): ConfigChange | string;
+/**
+ * Validate a raw value for a global command argument.
+ */
+export declare function prepareGlobalValue(target: ConfigTarget, raw: string, deferred: Array<DeferredCustomValidation>): {
+    value: SingleValueType;
+    isSecret: boolean;
+} | string;
+/**
+ * Apply the changes to a copy of the existing values and run the custom validators of the target.
+ * Returns the new values or an error message.
+ */
+export declare function applyChanges(target: ConfigTarget, existing: Values | undefined, changes: ReadonlyArray<ConfigChange>, deferred: Array<DeferredCustomValidation>): Values | string;
+/**
+ * Copy of a stored default value with SECRET typed values and any secret sentinels masked.
+ */
+export declare function maskDefault(target: ConfigTarget | undefined, value: Node): Node;
+export type { ValueNode };
+/**
+ * Whether an environment variable would override the stored value at the path.
+ */
+export declare function isOverriddenByEnvVar(provider: {
+    readonly envVarsEnabled: boolean;
+}, cliConfig: CLIConfig, target: ConfigTarget, steps: ReadonlyArray<PathStep>): boolean;
+//# sourceMappingURL=configTargets.d.ts.map

package/dist/src/service/configuration/configTargets.d.ts.map

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

package/dist/src/service/configuration/configTargets.js

@@ -0,0 +1,348 @@
+import { MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH, SECRET_SENTINEL_PREFIX, ValueTypeName, } from "@flowscripter/dynamic-cli-framework-api";
+import { isComplexOption } from "../../runtime/argument/ArgumentTypeGuards.js";
+import { getInvalidArgumentString, runCustomValidation, validateGlobalCommandArgumentValue, validateOptionValue, } from "../../runtime/values/argumentValueValidation.js";
+import { getGlobalCommandValueFromEnvVars, getSubCommandValuesFromEnvVars, } from "../../util/envVarHelper.js";
+import { isGlobalModifierCommand } from "../../runtime/command/CommandTypeGuards.js";
+export const MASK = "********";
+/**
+ * Collect all commands in the registry with `enableConfiguration` set, except the `config` modifier.
+ */
+export function getConfigTargets(registry) {
+    const targets = new Map();
+    const globals = [...registry.getGlobalCommands(), ...registry.getGlobalModifierCommands()];
+    for (const command of globals) {
+        if (command.enableConfiguration !== true || command.argument === undefined) {
+            continue;
+        }
+        if (isGlobalModifierCommand(command) && command.name === "config") {
+            continue;
+        }
+        targets.set(command.name, {
+            key: command.name,
+            command,
+            argument: command.argument,
+            options: [],
+        });
+    }
+    for (const command of registry.getSubCommands()) {
+        if (command.enableConfiguration === true) {
+            targets.set(command.name, { key: command.name, command, options: command.options });
+        }
+    }
+    for (const [key, { groupCommand, command }] of registry.getGroupAndMemberCommandsByJoinedName()) {
+        if (command.enableConfiguration === true) {
+            targets.set(key, { key, command, group: groupCommand, options: command.options });
+        }
+    }
+    return targets;
+}
+/**
+ * Parse an option path such as `address[1].port` into steps.
+ */
+export function parseOptionPath(path) {
+    const elements = path.split(".");
+    if (elements.length > MAXIMUM_COMPLEX_OPTION_NESTING_DEPTH) {
+        return `option path '${path}' exceeds the maximum nesting depth`;
+    }
+    const steps = [];
+    for (const element of elements) {
+        const match = /^([^[\]]+)(?:\[(\d+)\])?$/.exec(element);
+        if (match === null) {
+            return `invalid option path '${path}'`;
+        }
+        steps.push(match[2] === undefined ? { name: match[1] } : { name: match[1], index: Number(match[2]) });
+    }
+    return steps;
+}
+/**
+ * Walk the steps through the target's options returning the option the path refers to.
+ */
+export function resolveOptionPath(target, path) {
+    const steps = parseOptionPath(path);
+    if (typeof steps === "string") {
+        return steps;
+    }
+    let candidates = target.options;
+    let leaf;
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        leaf = candidates.find((o) => o.name === step.name);
+        if (leaf === undefined) {
+            return `unknown option '${step.name}' in '${path}'`;
+        }
+        if (step.index !== undefined && leaf.isArray !== true) {
+            return `option '${step.name}' is not an array`;
+        }
+        if (i < steps.length - 1) {
+            if (!isComplexOption(leaf)) {
+                return `option '${step.name}' has no properties`;
+            }
+            if (leaf.isArray === true && step.index === undefined) {
+                return `option '${step.name}' is an array and requires an index`;
+            }
+            candidates = leaf.properties;
+        }
+    }
+    return { steps, leaf: leaf };
+}
+export function containsSecret(option) {
+    if (isComplexOption(option)) {
+        return option.properties.some(containsSecret);
+    }
+    return option.type === ValueTypeName.SECRET;
+}
+function asOptional(option) {
+    if (isComplexOption(option)) {
+        return {
+            ...option,
+            isOptional: true,
+            properties: option.properties.map(asOptional),
+        };
+    }
+    return { ...option, isOptional: true };
+}
+function clone(value) {
+    return value === undefined ? value : structuredClone(value);
+}
+export function getAtPath(root, steps) {
+    let current = root;
+    for (const step of steps) {
+        if (typeof current !== "object" || current === null) {
+            return undefined;
+        }
+        current = current[step.name];
+        if (step.index !== undefined) {
+            if (!Array.isArray(current)) {
+                return undefined;
+            }
+            current = current[step.index];
+        }
+    }
+    return current;
+}
+/**
+ * Set a value at the path in the provided (mutable) root creating parents as needed.
+ */
+export function setAtPath(root, steps, value) {
+    let container = root;
+    steps.forEach((step, i) => {
+        const isLast = i === steps.length - 1;
+        if (step.index === undefined) {
+            if (isLast) {
+                container[step.name] = value;
+                return;
+            }
+            if (typeof container[step.name] !== "object" || container[step.name] === null) {
+                container[step.name] = {};
+            }
+            container = container[step.name];
+            return;
+        }
+        if (!Array.isArray(container[step.name])) {
+            container[step.name] = [];
+        }
+        const array = container[step.name];
+        if (step.index > array.length) {
+            throw new Error(`cannot set '${step.name}[${step.index}]': array has ${array.length} element(s) and sparse arrays are not supported`);
+        }
+        if (isLast) {
+            array[step.index] = value;
+            return;
+        }
+        if (typeof array[step.index] !== "object" || array[step.index] === null) {
+            array[step.index] = {};
+        }
+        container = array[step.index];
+    });
+}
+/**
+ * Remove the value at the path and any parent objects left empty. Returns false if there was no value.
+ */
+export function removeAtPath(root, steps) {
+    if (getAtPath(root, steps) === undefined) {
+        return false;
+    }
+    const last = steps[steps.length - 1];
+    if (last.index !== undefined) {
+        throw new Error("unsetting an array element is not supported: unset the whole option instead");
+    }
+    const parents = [root];
+    let container = root;
+    for (const step of steps.slice(0, -1)) {
+        container =
+            step.index === undefined
+                ? container[step.name]
+                : container[step.name][step.index];
+        parents.push(container);
+    }
+    delete container[last.name];
+    for (let i = steps.length - 2; i >= 0; i--) {
+        const step = steps[i];
+        if (step.index !== undefined || Object.keys(parents[i + 1]).length > 0) {
+            break;
+        }
+        delete parents[i][step.name];
+    }
+    return true;
+}
+/**
+ * All `__SECRET__:` sentinel strings within the value.
+ */
+export function collectSentinels(value) {
+    if (typeof value === "string") {
+        return value.startsWith(SECRET_SENTINEL_PREFIX) ? [value] : [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap(collectSentinels);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.values(value).flatMap(collectSentinels);
+    }
+    return [];
+}
+/**
+ * @param secrets plain text SECRET values which must not appear in the message.
+ */
+function invalidMessage(invalid, secrets = []) {
+    return invalid
+        .map((i) => {
+        const hidden = secrets.includes(i.value) ? { ...i, value: undefined } : i;
+        return getInvalidArgumentString(hidden, false) + (i.message ?? "");
+    })
+        .join("; ");
+}
+/**
+ * Validate and convert the raw (string) value for the option path of the target. Required checks are
+ * not applied. Custom validators of the target are run later by {@link validateChanges}.
+ */
+export function prepareChange(target, path, raw, deferred) {
+    const resolved = resolveOptionPath(target, path);
+    if (typeof resolved === "string") {
+        return resolved;
+    }
+    const { steps, leaf } = resolved;
+    const hasIndex = steps[steps.length - 1].index !== undefined;
+    const whole = isComplexOption(leaf) || (leaf.isArray === true && !hasIndex);
+    const invalid = [];
+    let value;
+    if (whole) {
+        if (!/^\s*[[{]/.test(raw)) {
+            return `option '${path}' requires a JSON ${leaf.isArray === true && !hasIndex ? "array" : "object"} value`;
+        }
+        if (containsSecret(leaf)) {
+            return `option '${path}' contains SECRET values: set each secret property individually`;
+        }
+        try {
+            value = JSON.parse(raw);
+        }
+        catch (err) {
+            return `invalid JSON value for '${path}': ${err.message}`;
+        }
+        value = validateOptionValue(asOptional(leaf), value, invalid, deferred);
+    }
+    else {
+        value = validateOptionValue({ ...asOptional(leaf), isArray: false }, raw, invalid, deferred);
+    }
+    if (invalid.length > 0) {
+        return `${path}: ${invalidMessage(invalid, [raw])}`;
+    }
+    const isSecret = !isComplexOption(leaf) && leaf.type === ValueTypeName.SECRET;
+    return { steps, path, leaf, value, isSecret };
+}
+/**
+ * Validate a raw value for a global command argument.
+ */
+export function prepareGlobalValue(target, raw, deferred) {
+    const invalid = [];
+    const argument = { ...target.argument, isOptional: true };
+    const value = validateGlobalCommandArgumentValue({ ...target.command, argument }, raw, invalid, deferred);
+    if (invalid.length > 0 || value === undefined) {
+        return invalidMessage(invalid, [raw]);
+    }
+    return { value, isSecret: target.argument.type === ValueTypeName.SECRET };
+}
+/**
+ * Apply the changes to a copy of the existing values and run the custom validators of the target.
+ * Returns the new values or an error message.
+ */
+export function applyChanges(target, existing, changes, deferred) {
+    const values = clone(existing ?? {});
+    try {
+        for (const change of changes) {
+            setAtPath(values, change.steps, change.value);
+        }
+    }
+    catch (err) {
+        return err.message;
+    }
+    const invalid = [];
+    runCustomValidation(deferred, target.command, values, invalid);
+    if (invalid.length > 0) {
+        return invalidMessage(invalid, changes.filter((c) => c.isSecret).map((c) => c.value));
+    }
+    return values;
+}
+function maskSentinels(value) {
+    if (typeof value === "string") {
+        return value.startsWith(SECRET_SENTINEL_PREFIX) ? MASK : value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(maskSentinels);
+    }
+    if (typeof value === "object" && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskSentinels(v)]));
+    }
+    return value;
+}
+function maskOption(option, value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (isComplexOption(option)) {
+        if (Array.isArray(value)) {
+            return value.map((v) => maskOption({ ...option, isArray: false }, v));
+        }
+        return maskOptions(option.properties, value);
+    }
+    if (option.type === ValueTypeName.SECRET) {
+        return Array.isArray(value) ? value.map(() => MASK) : MASK;
+    }
+    return value;
+}
+function maskOptions(options, value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, v]) => {
+        const option = options.find((o) => o.name === name);
+        return [name, option === undefined ? v : maskOption(option, v)];
+    }));
+}
+/**
+ * Copy of a stored default value with SECRET typed values and any secret sentinels masked.
+ */
+export function maskDefault(target, value) {
+    let masked = value;
+    if (target?.argument !== undefined) {
+        if (target.argument.type === ValueTypeName.SECRET && value !== undefined) {
+            masked = MASK;
+        }
+    }
+    else if (target !== undefined) {
+        masked = maskOptions(target.options, value);
+    }
+    return maskSentinels(masked);
+}
+/**
+ * Whether an environment variable would override the stored value at the path.
+ */
+export function isOverriddenByEnvVar(provider, cliConfig, target, steps) {
+    if (!provider.envVarsEnabled) {
+        return false;
+    }
+    if (target.argument !== undefined) {
+        return (getGlobalCommandValueFromEnvVars(cliConfig, target.command) !== undefined);
+    }
+    const values = getSubCommandValuesFromEnvVars(cliConfig, target.command, target.group);
+    return getAtPath(values, steps) !== undefined;
+}

package/dist/src/service/configuration/format/ConfigFormat.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The top level structure of a configuration file: `defaults` and `key-values` objects.
+ */
+export type ConfigData = Record<string, any>;
+/**
+ * Defines the on-disk syntax of the CLI configuration file.
+ *
+ * The built-in implementation is JSON (the default). YAML and TOML implementations are available
+ * from the `@flowscripter/dynamic-cli-framework/yaml` and `@flowscripter/dynamic-cli-framework/toml`
+ * entry points. Third party formats can be supplied by implementing this interface.
+ */
+export default interface ConfigFormat {
+    /**
+     * The extension (without the leading dot) used for the default configuration file name,
+     * e.g. `json`.
+     */
+    readonly fileExtension: string;
+    /**
+     * Parse configuration file text.
+     *
+     * @returns the parsed `data` and an opaque `handle` retaining whatever the format needs to write
+     * changes back while preserving comments and layout (`undefined` if the format has nothing to retain).
+     * @throws if the text is not valid for this format.
+     */
+    parse(text: string): {
+        data: ConfigData;
+        handle: unknown;
+    };
+    /**
+     * Produce updated file text from a `handle` returned by {@link parse}.
+     *
+     * @param handle the handle returned by {@link parse} for the text being updated.
+     * @param changes the complete updated configuration data. The format reconciles the existing text
+     * with it, leaving unchanged content (including comments) untouched.
+     */
+    apply(handle: unknown, changes: ConfigData): string;
+    /**
+     * Produce new file text from scratch.
+     */
+    serialize(data: ConfigData): string;
+}
+//# sourceMappingURL=ConfigFormat.d.ts.map

package/dist/src/service/configuration/format/ConfigFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigFormat.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/format/ConfigFormat.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,WAAW,YAAY;IACnC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAE3D;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CAAC;IAEpD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;CACrC"}

package/dist/src/service/configuration/format/JsonConfigFormat.d.ts

@@ -0,0 +1,7 @@
+import type ConfigFormat from "./ConfigFormat.ts";
+/**
+ * The built-in JSON {@link ConfigFormat}. The file is regenerated on write: JSON has no comments to preserve.
+ */
+declare const jsonFormat: ConfigFormat;
+export default jsonFormat;
+//# sourceMappingURL=JsonConfigFormat.d.ts.map

package/dist/src/service/configuration/format/JsonConfigFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonConfigFormat.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/format/JsonConfigFormat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAOlD;;GAEG;AACH,QAAA,MAAM,UAAU,EAAE,YASjB,CAAC;eAEa,UAAU"}

package/dist/src/service/configuration/format/JsonConfigFormat.js

@@ -0,0 +1,17 @@
+function serialize(data) {
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * The built-in JSON {@link ConfigFormat}. The file is regenerated on write: JSON has no comments to preserve.
+ */
+const jsonFormat = {
+    fileExtension: "json",
+    parse(text) {
+        return { data: JSON.parse(text), handle: undefined };
+    },
+    apply(_handle, changes) {
+        return serialize(changes);
+    },
+    serialize,
+};
+export default jsonFormat;

package/dist/src/service/configuration/format/TomlConfigFormat.d.ts

@@ -0,0 +1,10 @@
+import type ConfigFormat from "./ConfigFormat.ts";
+/**
+ * A TOML {@link ConfigFormat} which preserves comments, whitespace and layout when writing changes back.
+ * Dates and times are not supported as configuration values.
+ *
+ * Requires the optional `@decimalturn/toml-patch` peer dependency.
+ */
+declare const tomlFormat: ConfigFormat;
+export default tomlFormat;
+//# sourceMappingURL=TomlConfigFormat.d.ts.map

package/dist/src/service/configuration/format/TomlConfigFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TomlConfigFormat.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/format/TomlConfigFormat.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAoElD;;;;;GAKG;AACH,QAAA,MAAM,UAAU,EAAE,YAajB,CAAC;eAEa,UAAU"}

package/dist/src/service/configuration/format/TomlConfigFormat.js

@@ -0,0 +1,78 @@
+import { isDeepStrictEqual } from "node:util";
+import { parse, patch, stringify } from "@decimalturn/toml-patch";
+// new tables nested deeper than this (e.g. `defaults.<command>.<option>`) are left to patch() to
+// lay out as inline tables
+const MAX_TABLE_HEADER_DEPTH = 3;
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function formatKey(key) {
+    return /^[A-Za-z0-9_-]+$/.test(key) ? key : JSON.stringify(key);
+}
+function collectNewTables(existing, updated, path, newTables) {
+    for (const [key, value] of Object.entries(updated)) {
+        if (!isPlainObject(value) || path.length + 1 > MAX_TABLE_HEADER_DEPTH) {
+            continue;
+        }
+        const childPath = [...path, key];
+        const existingChild = isPlainObject(existing) ? existing[key] : undefined;
+        if (existingChild === undefined) {
+            newTables.push(childPath);
+        }
+        collectNewTables(existingChild, value, childPath, newTables);
+    }
+}
+// parse() results do not share prototypes with plain objects
+function plain(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Append an empty `[table]` header for every new table, so that patch() fills it in at the end
+ * of the file rather than hoisting it to the top as a dotted key. Returns the original text if the
+ * result is not equivalent to it plus the empty tables (e.g. the parent is an inline table which
+ * cannot be extended).
+ */
+function addNewTableHeaders(text, existing, changes) {
+    const newTables = [];
+    collectNewTables(existing, changes, [], newTables);
+    if (newTables.length === 0) {
+        return text;
+    }
+    const expected = structuredClone(existing);
+    for (const tablePath of newTables) {
+        let node = expected;
+        for (const key of tablePath.slice(0, -1)) {
+            node = (node[key] ??= {});
+        }
+        node[tablePath[tablePath.length - 1]] ??= {};
+    }
+    const headers = newTables.map((tablePath) => `[${tablePath.map(formatKey).join(".")}]`);
+    const withHeaders = `${text.trimEnd()}\n\n${headers.join("\n\n")}\n`;
+    try {
+        return isDeepStrictEqual(plain(parse(withHeaders)), plain(expected)) ? withHeaders : text;
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * A TOML {@link ConfigFormat} which preserves comments, whitespace and layout when writing changes back.
+ * Dates and times are not supported as configuration values.
+ *
+ * Requires the optional `@decimalturn/toml-patch` peer dependency.
+ */
+const tomlFormat = {
+    fileExtension: "toml",
+    parse(text) {
+        return { data: parse(text), handle: text };
+    },
+    apply(handle, changes) {
+        const text = handle;
+        const existing = parse(text);
+        return patch(addNewTableHeaders(text, existing, changes), changes);
+    },
+    serialize(data) {
+        return stringify(data);
+    },
+};
+export default tomlFormat;

package/dist/src/service/configuration/format/YamlConfigFormat.d.ts

@@ -0,0 +1,9 @@
+import type ConfigFormat from "./ConfigFormat.ts";
+/**
+ * A YAML {@link ConfigFormat} which preserves comments, blank lines and key order when writing changes back.
+ *
+ * Requires the optional `yaml` peer dependency.
+ */
+declare const yamlFormat: ConfigFormat;
+export default yamlFormat;
+//# sourceMappingURL=YamlConfigFormat.d.ts.map

package/dist/src/service/configuration/format/YamlConfigFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlConfigFormat.d.ts","sourceRoot":"","sources":["../../../../../src/service/configuration/format/YamlConfigFormat.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,YAAY,MAAM,mBAAmB,CAAC;AAqClD;;;;GAIG;AACH,QAAA,MAAM,UAAU,EAAE,YA0BjB,CAAC;eAEa,UAAU"}